AWS EC2 에 OpenVPN 서버 구축

리눅스에서 OpenVPN 서버 구축해 보도록 한다. 리눅스 서버는 Ubuntu 24.04 LTS 이다.

아키텍쳐

현재 AWS 아키텍쳐는 다음과 같다.

OpenVPN 를 설치할 서버는 AWS 에 Public Subnet 에 있으며 외부에서 접속을 위해서 EIP(Elastic IP) 를 할당 해줬다. VPC 내에 모든 서버들은 172.31.0.0/16 대역폭에 자동으로 IP를 할당받아 Private IP 를 구성하도록 되어 있다.

이제 사내망 PC 에서 server1 에 Private IP 로 접속을 하기 위한 방법으로 OpenVPN 서버를 설치해보도록 한다.

OpenVPN 작동 방식

OpenVPN 의 작동방법은 NAT 기능을 이용하는 것이다. 먼저, OpenVPN 서버를 설치하고 기동하면 OpenVPN 서버는 서버에 tun0 라고 하는 네트워크 인터페이스 생성한다. 물론 이렇게 생성한 NIC에 네트워크 서브넷을 할당한다. tun0 에 IP를 할당하고 서브넷 라우팅도 함께 구성하게 된다.

이제 OpenVPN 클라이언트를 설치하고 설정파일을 읽어 연결을 하게 되면, OpenVPN 클라이언트는 PC 에 tap0 라고 하는 네트워크 인터페이스를 생성한다. 그리고 이 tap0 에는 OpenVPN 서버로부터 네트워크 관련 정보를 전달 받아서 tun0 와 동일네트워크에 IP, Defaut GW 를 구성하게 된다. 이를 다이어그램으로 표현하면 다음과 같다.

OpenVPN 을 이용하는 이유는 172.31.0.0/16 대역에 있는 서버에 접속하기 위해서다. AWS 아키텍쳐 그림상 server1 에 사내PC가 직접 접속할 방법이 없다. 하지만 OpenVPN 을 이용하면 가능하다. 다음과 같이 접속이 이루어진다.

사내PC(192.168.96.112.66) -> tap(192.168.200.56) —– 인터넷 —–> OpenVPN 서버 tun0(192.168.96.200.1) — NAT –> server1(172.31.0.43)

이러한 흐름을 보면 OpenVPN 서버의 설정에서 OpenVPN 서버와 Client 연결을 위한 네트워크 대역 할당과 server1 의 접속은 OpenVPN 서버를 거쳐서 와야하기 때문에 AWS VPC 네트워크 대역을 알려줘야 하고 OpenVPN 서버는 NAT 서버로 동작해야 한다는(그래서 iptables 을 이용한 MASQUERADE 설정을 한다.) 걸 알게 된다.

OpenVPN 2.6

현 시점에서 OpenVPN 은 2.5 를 기준으로 구분이 된다. 2.6 은 현재 최신 버전으로 사용되고 있는데, 2.5 를 기준으로해서 설정에 많은 변화가 있음으로 만일 처음 구축한다면 2.6으로 하고 호환성을 고려한다면 2.4 를 기준으로 구축하는 걸 권장 한다.

OpenVPN 설치

설치는 Ubuntu 24.04 LTS 에서 기본으로 제공하는 패키지로 설치가 가능하다. 이때 OpenVPN 이 사용할 인증서 생성을 위해서 easy-rsa 명령어도 함께 설치해야 한다.

openvpn 설치
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
~# apt install openvpn easy-rsa
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
  libpkcs11-helper1t64
Suggested packages:
  openvpn-dco-dkms openvpn-systemd-resolved easy-rsa
The following NEW packages will be installed:
  libpkcs11-helper1t64 openvpn
0 upgraded, 2 newly installed, 0 to remove and 122 not upgraded.
Need to get 731 kB of archives.
After this operation, 1957 kB of additional disk space will be used.
Do you want to continue? [Y/n]

인증서 생성

OpenVPN 서버는 Client 와 보안통신을 위해서 인증서를 필요로 한다. 인증서를 만드는 것은 그렇게 쉬운 절차가 아니여서 많은 이들이 어려움을 겪는데, easy-rsa 를 이용하면 비교적 쉽게 만들 수 있다.

인증서는 서버 인증서와 클라이언트 인증서가 필요하고 이 둘의 인증서를 만들기 위한 CA 인증서도 있어야 한다.

easy-rsa 명령어만 이용하는게 아니라 디렉토리도 있어야 하는데 /usr/share/easy-rsa/3 에서 작업해야 한다.(중요)

easyrsa 초기화

먼저 easyrsa 를 초기화 해준다. /usr/share/easy-rsa 디렉토리로 이동한다. 여기서 다음과 같이 vars 파일을 만든다.

vars 파일
1
2
3
4
5
6
set_var EASYRSA_REQ_COUNTRY     "KR"
set_var EASYRSA_REQ_PROVINCE    "Gangseo-gu"
set_var EASYRSA_REQ_CITY        "Seoul"
set_var EASYRSA_REQ_ORG         "SYSTEMV"
set_var EASYRSA_REQ_EMAIL       "admin@systemv.pe.kr"
set_var EASYRSA_REQ_OU          "Linux"

이 파일은 CSR 내용이기 때문에 상황에 맞게 입력해주면 된다. 그리고 다음과 같이 easy-rsa 를 초기화 한다.

easyrsa 초기화
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
]# ./easyrsa init-pki
Using Easy-RSA 'vars' configuration:
* /usr/share/easy-rsa/3/vars
 
Notice
------
'init-pki' complete; you may now create a CA or requests.
 
Your newly created PKI dir is:
* /usr/share/easy-rsa/3/pki
 
Using Easy-RSA configuration:
* /usr/share/easy-rsa/3/vars

CA 인증서 제작

다음과 같이 root CA 인증서를 제작한다.

root CA 인증서
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
]# ./easyrsa build-ca nopass
Using Easy-RSA 'vars' configuration:
* /usr/share/easy-rsa/3/vars
.......................+++++
....................................................................................................................................................................+++++
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Common Name (eg: your user, host, or server name) [Easy-RSA CA]:lgcns.fcc.co.kr
 
Notice
------
CA creation complete. Your new CA certificate is at:
* /usr/share/easy-rsa/3/pki/ca.crt
 
Create an OpenVPN TLS-AUTH|TLS-CRYPT-V1 key now: See 'help gen-tls'
 
Build-ca completed successfully.

root CA 인증서가 생성되었다.

서버 인증서

서버 인증서를 만든다. 서버 인증서를 만들기 위해서는 도메인이 필요하다. 이 도메인은 반드시 있어야 하는건 아니고 서버-클라이언트간 보안을 위한 검증을 위한 것으로 가상으로 입력해줘도 된다.

서버 인증서
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
]# ./easyrsa build-server-full openvpn.systemv.pe.kr nopass
Using Easy-RSA 'vars' configuration:
* /usr/share/easy-rsa/3/vars
Generating a RSA private key
...............+++++
.......................................................................................................................+++++
writing new private key to '/usr/share/easy-rsa/3/pki/8f3780fb/temp.2.1'
-----
 
Notice
------
Private-Key and Public-Certificate-Request files created.
Your files are:
* req: /usr/share/easy-rsa/3/pki/reqs/openvpn.systemv.pe.kr.req
* key: /usr/share/easy-rsa/3/pki/private/openvpn.systemv.pe.kr.key
 
You are about to sign the following certificate:
 
  Requested CN:     'openvpn.systemv.pe.kr'
  Requested type:   'server'
  Valid for:        '825' days
 
 
subject=
    commonName                = openvpn.systemv.pe.kr
 
Type the word 'yes' to continue, or any other input to abort.
  Confirm requested details: yes
 
Using configuration from /usr/share/easy-rsa/3/pki/02b0a94b/temp.6.1
Check that the request matches the signature
Signature ok
The Subject's Distinguished Name is as follows
commonName            :ASN.1 12:'openvpn.systemv.pe.kr'
Certificate is to be certified until Jun 22 05:41:51 2027 GMT (825 days)
 
Write out database with 1 new entries
Data Base Updated
 
Notice
------
Inline file created:
* /usr/share/easy-rsa/3/pki/inline/private/openvpn.systemv.pe.kr.inline
 
 
Notice
------
Certificate created at:
* /usr/share/easy-rsa/3/pki/issued/openvpn.systemv.pe.kr.crt

openvpn.systemv.pe.kr 도메인은 가상으로 그냥 적은 것이다. 굳이 신경쓸 필요는 없다.

클라이언트 인증서 제작

여기서 특징이 있는데, OpenVPN 을 위한 Client 인증서는 사용자마다 제작을 해줘야 한다. 그래서 Client 이름은 ID나 이메일등을 지정해 주면 된다.

Client 인증서 제작
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
]# ./easyrsa build-client-full sbhyun nopass
Using Easy-RSA 'vars' configuration:
* /usr/share/easy-rsa/3/vars
Generating a RSA private key
...............+++++
......................................................+++++
writing new private key to '/usr/share/easy-rsa/3/pki/aade4cae/temp.2.1'
-----
 
Notice
------
Private-Key and Public-Certificate-Request files created.
Your files are:
* req: /usr/share/easy-rsa/3/pki/reqs/linux.req
* key: /usr/share/easy-rsa/3/pki/private/linux.key
 
You are about to sign the following certificate:
 
  Requested CN:     'linux'
  Requested type:   'client'
  Valid for:        '825' days
 
 
subject=
    commonName                = linux
 
Type the word 'yes' to continue, or any other input to abort.
  Confirm requested details: yes
 
Using configuration from /usr/share/easy-rsa/3/pki/06c316d2/temp.6.1
Check that the request matches the signature
Signature ok
The Subject's Distinguished Name is as follows
commonName            :ASN.1 12:'linux'
Certificate is to be certified until Jun 22 05:44:31 2027 GMT (825 days)
 
Write out database with 1 new entries
Data Base Updated
 
Notice
------
Inline file created:
* /usr/share/easy-rsa/3/pki/inline/private/linux.inline
 
 
Notice
------
Certificate created at:
* /usr/share/easy-rsa/3/pki/issued/linux.crt

Diffie-Hellman key 생성

서버 접속을 위한 Diffie-Hellman key 를 다음과 같이 생성해 준다.

Diffie-Hellman key 생성
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
]# ./easyrsa gen-dh
Using Easy-RSA 'vars' configuration:
* /usr/share/easy-rsa/3/vars
Generating DH parameters, 2048 bit long safe prime, generator 2
This is going to take a long time
......+...........................
DH parameters appear to be ok.
 
Notice
------
 
DH parameters of size 2048 created at:
* /usr/share/easy-rsa/3/pki/dh.pem

TLS-Auth key 인증 키 생성

다음과 같이 TLS-Auth 키를 생성해 준다.

TLS-Auth 키 생성
ZSH
1
]# openvpn --genkey --secret ./pki/ta.key

생성한 키 복사

이렇게 생성한 키들을 OpenVPN 서버에 설정 디렉토리에 복사해 준다. 여기서 주의해야 할것이 배포판마다 설정 디렉토리가 다를 수 있다. Ubuntu24.04 LTS 의 경우에 /etc/openvpn 디렉토리다.

생성한 키 복사
ZSH
1
]# cp -pR /usr/share/easy-rsa/3/pki/{issued,private,ca.crt,dh.pem,ta.key} /etc/openvpn

OpenVPN 서버 설정

이제 필요한 파일을 모두 갖췄으니, OpenVPN 설정을 해야 한다. 설정을 어떻게 해야할지 모르기 때문에 OpenVPN 에서 제공하는 Sample 파일을 이용해서 해보자.

openvpn 설정 파일 복사
ZSH
1
]# cp /usr/share/doc/openvpn/sample/sample-config-files/server.conf /etc/openvpn

이제 server.conf 파일을 다음과 같이 설정해준다.

server.conf
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
port 1194
proto udp
dev tun                                 # Network Interface Card
ca ca.crt
cert issued/linux.systemvp.pe.kr.crt
dh dh.pem
server 192.168.200.0 255.255.255.0      # OpenVPN CIDR
ifconfig-pool-persist /var/log/openvpn/ipp.txt
push "route 172.31.0.0 255.255.0.0"     # AWS VPC CIDR
push "dhcp-option DNS 8.8.8.8"          # Public Primary DNS Server
push "dhcp-option DNS 8.8.4.4"          # Public Sencondary DNS Server
keepalive 10 120
persist-key
persist-tun
status /var/log/openvpn/openvpn-status.log
log         /var/log/openvpn/openvpn.log
log-append  /var/log/openvpn/openvpn.log
verb 3
explicit-exit-notify 0
comp-lzo

여기서 AWS VPC CIDR 과 OpenVPN CIDR, DNS 서버 설정등을 주의해서 봐야 한다.

iptables 설정

테스트 하는 서버에는 ufw 명령어가 없다. 만일 ufw 명령어가 있다면 이것을 이용하는 방법으로 해야한다.

iptables 설정을 하는 이유는 MASQUERADE 때문이다. OpenVPN 서버가 NAT로 작동하기 위해서 Iptables 을 이용해 패킷의 흐름을 제어해야 하기 때문이다.

여기서 또 한가지, OpenVPN 서버가 실행중일 때에만 MASQUERADE 설정을 유지하고 실행하지 않을때에는 설정을 꺼야 한다. Iptables 초기화를 하면 설정이 초기화 된다. 이를 위해서 Iptables 설정과 해제 두개의 파일을 작성한다.

먼저 add-bridge.sh 라는 이름으로 쉘 스크립트를 다음과 같이 만든다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
#!/bin/bash
 
if [ ! -x /usr/sbin/iptables ]; then
        exit 0
fi
 
IPTABLES=/usr/sbin/iptables
MY_IP=172.31.2.195
IF=enX0
VPNIF=tun0
PORT=1194
 
# flush a default policy of rules
$IPTABLES -F
# flush a policy in the custom rules
$IPTABLES -X
 
# Defined a default policy of rules
$IPTABLES -P INPUT ACCEPT
$IPTABLES -P OUTPUT ACCEPT
$IPTABLES -P FORWARD ACCEPT
 
# default rule 22,443,53
$IPTABLES -A INPUT -i ${IF} -p tcp ! --syn -j ACCEPT
 
# 22
$IPTABLES -A INPUT -i ${IF} -p TCP --sport 1024: -d ${MY_IP} --dport 22 -j ACCEPT
$IPTABLES -A OUTPUT -o ${IF} -p TCP ! --syn -s ${MY_IP} --sport 22 --dport 1024: -j ACCEPT
 
# 53
$IPTABLES -A OUTPUT -p UDP --sport 1024: --dport 53 -m state --state NEW -j ACCEPT
$IPTABLES -A INPUT -p UDP --sport 53 --dport 1024: -m state --state ESTABLISHED -j ACCEPT
$IPTABLES -A OUTPUT -p TCP --sport 1024: --dport 53 -m state --state NEW -j ACCEPT
$IPTABLES -A INPUT -p TCP --sport 53 --dport 1024: -m state --state ESTABLISHED -j ACCEPT
 
# 443
#$IPTABLES -A INPUT -i ${IF} -p TCP --sport 1024: -d ${MY_IP} --dport 443 -j ACCEPT
#$IPTABLES -A OUTPUT -o ${IF} -p TCP ! --syn -s ${MY_IP} --sport 443 --dport 1024: -j ACCEPT
 
# 1194
$IPTABLES -A INPUT -i ${IF} -p UDP --sport ${PORT} --dport 1024: -m state --state ESTABLISHED -j ACCEPT
$IPTABLES -A OUTPUT -o ${IF} -p UDP --sport 1024: --dport ${PORT} -m state --state NEW -j ACCEPT
 
# NAT to a vpn
$IPTABLES -I FORWARD 1 -i ${VPNIF} -s 192.168.200.0/24 -o ${IF} -d 172.31.0.0/16 -j ACCEPT
# Masquerade
$IPTABLES -t nat -I POSTROUTING 1 -o ${IF} -j MASQUERADE

내용이 많지만, 맨 아래 두줄이 핵심이다. tun0 네트워크 장치로부터 192.168.200.0/24 대역으로 들어온 IP에 대해서 enX0 장치를 이용해 172.31.0.0/16 대역으로 패킷을 포워딩 하고 MASQUERADE 설정을 해주고 있다.

OpenVPN 서버가 정지하면 초기화 해주는 remove-bridge.sh 파일을 만들어 준다.

remove-bridge.sh 파일 생성
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#!/bin/bash
 
if [ ! -x /usr/sbin/iptables ]; then
        exit 0
fi
 
IPTABLES=/usr/sbin/iptables
 
# flush a default policy of rules
$IPTABLES -F
$IPTABLES -X
 
$IPTABLES -P INPUT ACCEPT
$IPTABLES -P OUTPUT ACCEPT
$IPTABLES -P FORWARD ACCEPT
 
# general nat
$IPTABLES -t nat -D POSTROUTING 1

모든 체인을 플러쉬하고 POSTROUTING 룰을 삭제한다.

이렇게 만들어진 파일을 systemd unit 파일인 openvpn@server 에 override 설정으로 추가해준다. override 설정은 파일을 일반 편집으로 해서 추가해주면 자동으로 알아서 추가가 된다.

ZSH
1
2
3
4
5
6
]# export SYSTEMD_EDITOR=vim
]# systemctl edit openvpn@server
 
[Service]
ExecStartPost=/etc/openvpn/add-bridge.sh
ExecStopPost=/etc/openvpn/remove-bridge.sh

이렇게 하면 openvpn 시작/중지 때마다 쉘 스크립트가 실행 된다.

시작/중지

이제 시작과 중지를 해보자. 다음과 같이 한다.

openvpn 시작/중지
ZSH
1
2
]# systemctl start openvpn@server
]# systemctl stop openvpn@server

OpenVPN 클라이언트 설정

OpenVPN 홈페이지에서 Windows 용 클라이언트를 다운받아 설치한다. 설정 파일은 개인마다 가지고 있어야 해서 전체 시스템에 액세스하는 디렉토리에 넣으면 좋지 않다. 이는 설치가 끝나면 팝업으로 알려주는데, C:\Users\계정ID\OpenVPN\config 이다.

이 디렉토리에 서버에서 작성한 파일을 복사해줘야 한다. 복사해야 할 파일은 다음과 같다.

  • linux.crt (클라이언트 인증서)
  • linux.key (클라이언트 인증서 암호화 키)
  • ca.crt (CA 인증서)
  • ta.key (TLS-Auth Key)

이제 linux.ovpn 파일을 다음과 같이 작성한다.

linux.ovpn
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
client
dev tun
proto udp
remote <openvpn 공인IP> 1194
resolv-retry infinite
nobind
persist-key
persist-tun
ca ca.crt
cert linux.crt
key linux.key
remote-cert-tls server
comp-lzo yes
tls-auth ta.key 1
verb 3

위와같이 작성하고 OpenVPN Client 에서 설정 파일을 지정하고 연결하기 하면 연결이 된다.

Self Signed 인증서 만들기

이 포스팅은 Self Signed 인증서 만들기 간략한 버전이다. 이론적인 내용은 빼고 OpenSSL 을 이용해서 만드는 방법을 설명한다.

만들기 순서

Self Signed 인증서 만들때에는 순서가 있다.

  1. root CA 를 위한 비밀키 생성(비대칭키)
  2. root 인증서 생성 위한 CSR 생성
  3. root 인증서 생성
  4. Server 인증서를 위한 비밀키 생성(비대칭키)
  5. Server 인증서 생성을 위한 CSR 생성
  6. Server 인증서 생성

대략 위와 같은 순서를 따른다. 비대칭 비밀키를 생성을 위해서 openssl 명령어를 사용한다. 글의 진행을 위해서 a.com 도메인에 대한 인증서를 생성하는 것으로 가정한다.

v3 확장

한가지 알고 가야할 것이 x509 표준에 v3 확장이다. 이 확장은 인증서에 대한 버전을 말하는 것으로 현재 Version 3 에서 확장(Extend) 된 것을 말한다.

v3 확장을 이용하면 SAN(Subject Alternative Name) 을 포함한 인증서를 생성할 수 있다.

이러한 확장을 이용하기 위해서 일종의 명세서 파일을 이용하게 되는데, 인증서 생성에 있어서 이 명세서 파일이 핵심이라고 할 수 있다. CSR 및 인증서 생성에 명세서 파일이 사용된다고 할 수 있다.

root CA 를 위한 비밀키 생성

openssl 를 이용해서 root CA 를 위한 비밀키를 다음과 같이 생성한다.

root CA 를 위한 비밀키 생성
ZSH
1
openssl genrsa -out RootCA-key.pem 2048

비밀키가 정상적으로 생성이 된다. 생성된 비밀키에 대한 정보는 다음의 명령어로 확인이 가능하다.

RootCA 비밀키 확인
ZSH
1
2
3
4
5
6
7
$ openssl rsa -in RootCA-key.pem -check
RSA key ok
writing RSA key
-----BEGIN PRIVATE KEY-----
$ openssl rsa -in RootCA-key.pem -noout -text
Private-Key: (2048 bit, 2 primes)
modulus:

참고로 비밀키를 이용해서 공개키(Public Key) 를 생성할 수 있는데, 다음과 같다.

비밀키를 이용한 공개키 생성
ZSH
1
2
$ openssl rsa -inform PEM -in rootCA-key.pem -pubout -outform PEM -out rootCA-public-key.pem
writing RSA key

root 인증서 생성 위한 CSR 생성

CSR 파일을 생성하기 명세서 파일을 이용한다. 명세서 파일은 CSR 만 아니라 인증서 생성에도 사용된다. 명세서 파일을 rootCA.cnf 이름으로 생성한다.

명세서 파일 작성
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
[req]
default_bits = 2048
default_md = sha256
default_keyfile  = RootCA-key.pem
distinguished_name = dn
req_extensions = v3_req
x509_extensions = v3_ca
 
[ v3_req ]
basicConstraints       = critical, CA:TRUE
subjectKeyIdentifier   = hash
 
[ v3_ca ]
basicConstraints       = critical, CA:TRUE
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid:always, issuer
keyUsage               = critical, cRLSign, digitalSignature, keyCertSign
extendedKeyUsage        = clientAuth, serverAuth
 
[dn]
countryName                     = Country Name (2 letter code)
countryName_default             = KR
countryName_min                 = 2
countryName_max                 = 2
 
stateOrProvinceName             = State or Province Name
stateOrProvinceName_default     = Magokjungang 8-ro, Gangseo-gu
 
localityName                    = Locality Name
localityName_default            = Seoul
 
organizationName                = Organization Name (eg, company)
organizationName_default        = Systemv
 
organizationalUnitName          = Organizational Unit Name (eg, section)
organizationalUnitName_default  = AI
 
commonName                      = Common Name (eg, your name or your server's hostname)
commonName_default              = a.com
commonName_max                  = 64
 
emailAddress                    = Email Address
emailAddress_default            = linux@a.com
emailAddress_max                = 64

위 명세서는 아무렇게나 만는게 아니며 정해진 규칙이 있다. dn 섹션에는 CSR 작성시 입력할 인증서에 대한 요청자 정보를 입력하는 필드를 지정할 수 있다.

이제 RootCA.cnf 명세서 파일을 이용해서 CSR 파일을 다음과 같이 작성한다.

RootCA.csr 파일 생성
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$ openssl req -new -key RootCA-key.pem -out RootCA.csr -config RootCA.cnf
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [KR]:
State or Province Name [Magokjungang 8-ro, Gangseo-gu]:
Locality Name [Seoul]:
Organization Name (eg, company) [Systemv]:
Organizational Unit Name (eg, section) [AI]:
Common Name (eg, your name or your servers hostname) [a.com]:
Email Address [linux@a.com]:

명세서에 dn 섹션에 내용을 출력하고 있다. CSR 파일이 생성이 되었다.

root 인증서 생성

이제 지금까지 생성된 비밀키와 CSR 파일을 이용해 인증서를 생성한다. 인증서를 생성할때에는 인증서의 사용기간을 정해야 한다.

RootCA 인증서 생성
ZSH
1
2
3
4
$ openssl x509 -req -days 730 -extensions v3_ca -set_serial 1 -in RootCA.csr -signkey RootCA-key.pem -out RootCA.crt -extf
ile RootCA.cnf
Certificate request self-signature ok
subject=C = KR, ST = "Magokjungang 8-ro, Gangseo-gu", L = Seoul, O = Systemv, OU = AI, CN = a.com, emailAddress = linux@a.com

인증서의 사용기간은 730 일이다. 그리고 -extensions v3_ca 를 인자로 줬는데, 명세서 파일인 RootCA.cnf 파일에 v3_ca 섹션을 사용하라는 뜻이다. v3_ca 섹션에는 인증서에 대한 사용범위, RootCA 임을 증명하는 CA:TRUE 등이 있다.

확인은 다음과 같이 할 수 있다.

RootCA 인증서 확인
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
$ openssl x509 -in RootCA.crt -noout -text
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 1 (0x1)
        Signature Algorithm: sha256WithRSAEncryption
        Issuer: C = KR, ST = "Magokjungang 8-ro, Gangseo-gu", L = Seoul, O = Systemv, OU = AI, CN = a.com, emailAddress = linux@a.com
        Validity
            Not Before: Feb 28 05:58:12 2025 GMT
            Not After : Feb 28 05:58:12 2027 GMT
        Subject: C = KR, ST = "Magokjungang 8-ro, Gangseo-gu", L = Seoul, O = Systemv, OU = AI, CN = a.com, emailAddress = linux@a.com
        Subject Public Key Info:
            Public Key Algorithm: rsaEncryption
                Public-Key: (2048 bit)
                Modulus:
                    00:f2:c8:c0:76:9d:13:e5:cf:1b:4e:9f:68:0b:93:
                    b9:06:12:af:a4:f1:50:3a:87:f4:95:27:f6:d0:1e:
                    6b:ff:cf:0f:74:a8:da:7d:a3:d4:04:dd:f4:7d:a8:
                    b1:68:db:3e:32:82:4a:ab:31:f9:da:22:db:fd:59:
                    fc:93:0d:f2:51:41:ec:6a:25:7b:c7:ca:9a:43:57:
                    50:64:29:b5:79:21:b9:9d:5c:c4:3e:fd:e1:c9:fc:
                    e7:11:40:81:fc:60:8a:42:df:5b:7a:27:5e:5b:7c:
                    fb:8f:49:55:ea:00:ce:32:e4:b4:18:2f:e7:b5:6b:
                    59:1f:e5:30:75:eb:47:56:6f:ba:01:a2:82:23:4e:
                    e7:c7:7f:a8:c3:4d:c7:28:f3:aa:bd:46:0c:f4:75:
                    88:68:ea:4f:2d:0b:9c:33:df:03:73:9e:76:14:33:
                    f8:2f:e3:27:e8:cd:3a:77:c6:d4:e1:98:6a:0b:b2:
                    57:f7:89:08:ad:8b:10:e3:47:70:85:3d:e0:9f:b6:
                    67:a4:1f:87:b9:95:3c:07:bc:8f:16:7b:8b:0a:05:
                    db:a9:d9:12:dd:3c:33:74:26:16:d4:16:d4:c5:db:
                    bc:ae:7f:e9:cf:89:19:38:76:57:fe:b3:db:59:b1:
                    fd:96:51:bf:82:d5:25:4e:c2:ec:4f:3f:97:5f:27:
                    cb:01
                Exponent: 65537 (0x10001)
        X509v3 extensions:
            X509v3 Basic Constraints: critical
                CA:TRUE
            X509v3 Subject Key Identifier:
                4D:D5:A8:E9:42:7B:4E:66:10:1A:34:7B:87:4A:B6:DD:0E:7B:EC:2F
            X509v3 Authority Key Identifier:
                4D:D5:A8:E9:42:7B:4E:66:10:1A:34:7B:87:4A:B6:DD:0E:7B:EC:2F
            X509v3 Key Usage: critical
                Digital Signature, Certificate Sign, CRL Sign
            X509v3 Extended Key Usage:
                TLS Web Client Authentication, TLS Web Server Authentication
    Signature Algorithm: sha256WithRSAEncryption
    Signature Value:
        64:23:20:4d:4f:af:01:56:8e:a8:eb:67:5f:38:87:0c:6f:b3:
        2f:32:66:f3:ff:38:15:20:bb:15:8e:b1:ac:3c:77:36:37:b3:
        c6:92:13:a7:df:75:eb:b3:2f:4b:b0:16:b4:f5:9d:18:7f:5f:
        6f:e1:4f:31:e0:37:e4:43:5f:0c:36:d0:9f:92:0a:b3:30:b0:
        70:d4:73:d7:a6:fb:76:3d:29:b4:74:d0:ec:57:13:57:85:d7:
        80:14:88:dc:48:a6:c8:91:da:35:3e:bd:75:c3:d3:e3:31:84:
        0c:a9:e5:5b:63:57:56:36:6e:94:1d:83:3a:cc:11:b0:12:92:
        69:12:e9:55:17:04:3a:8c:c1:42:d6:ad:6b:8e:26:26:38:b1:
        06:70:51:a8:d5:cc:6a:c0:05:01:43:b1:27:f9:7a:43:b2:58:
        38:41:5a:56:07:76:a8:e4:4e:a9:1e:b5:f8:ac:37:a8:68:ec:
        36:25:77:76:59:41:b3:d2:aa:d3:9c:6c:9f:88:c1:56:96:84:
        c7:39:45:2c:8d:c7:fa:d4:e0:3b:36:3e:d8:f9:ce:cf:b0:f3:
        a4:c6:76:00:73:f7:aa:b8:ce:87:69:6c:50:00:5c:81:b7:40:
        c5:cc:9e:b7:1c:91:2d:b5:ce:35:86:83:0a:33:39:39:97:77:
        9d:1c:c6:b8

Server 인증서를 위한 비밀키 생성(비대칭키)

이제 서버 인증서를 생성해야 한다. 서버 인증서를 위한 비밀키를 다음과 같이 생성한다.

Server 인증서를 위한 비밀키 생성
ZSH
1
$ openssl genrsa -out server-key.pem 2048

Server 인증서 생성을 위한 CSR 생성

이제 서버 인증서 생성을 위한 명세서 파일을 server.cnf 파일 이름으로 다음과 같이 생성 한다.

Server 인증서를 위한 명세서 파일
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
[req]
default_bits = 2048
default_md = sha256
distinguished_name = dn
req_extensions = v3_req
x509_extensions = v3_ca
 
[ v3_req ]
basicConstraints       = critical, CA:FALSE
subjectKeyIdentifier   = hash
 
[ v3_ca ]
basicConstraints       = critical, CA:FALSE
subjectAltName          = @alt_names
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid:always, issuer
keyUsage               = critical, digitalSignature
extendedKeyUsage        = clientAuth, serverAuth
 
[dn]
countryName                     = Country Name (2 letter code)
countryName_default             = KR
countryName_min                 = 2
countryName_max                 = 2
 
stateOrProvinceName             = State or Province Name (full name)
stateOrProvinceName_default     = Magokjungang 8-ro, Gangseo-gu
 
localityName                    = Locality Name (eg, city)
localityName_default            = Seoul
 
organizationName                = Organization Name (eg, company)
organizationName_default        = Systemv
 
organizationalUnitName          = Organizational Unit Name (eg, section)
organizationalUnitName_default  = AI
 
commonName                      = Common Name (eg, server FQDN or YOUR name)
commonName_default              = a.com
commonName_max                  = 64
 
emailAddress                    = Email Address
emailAddress_default            = linux@a.com
emailAddress_max                = 64
 
[alt_names]
DNS.1 = a.com
DNS.2 = *.a.com
IP.1 = 127.0.0.1

RootCA 인증서와 차이점이 보인다. alt_names 섹션이 추가 되었다. 그리고 CA:FALSE 이며 keyUsage 도 다르다. 이 명세서를 이용해서 서버인증서를 위한 CSR 를 생성한다.

Server 인증서를 위한 CSR 파일 생성
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
$ openssl req -new -key server-key.pem -out server.csr -config server.cnf
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [KR]:
State or Province Name (full name) [Magokjungang 8-ro, Gangseo-gu]:
Locality Name (eg, city) [Seoul]:
Organization Name (eg, company) [Systemv]:
Organizational Unit Name (eg, section) [AI]:
Common Name (eg, server FQDN or YOUR name) [a.com]:
Email Address [linux@a.com]:

예제를 위해서 CSR 입력 내용이 RootCA 와 동일하지만 공인 인증서는 서버CSR 입력 내용이 RootCA 와 같을 수가 없다.

Server 인증서 생성

이제 Server 비밀키와 CSR, RootCA 인증서, RootCA 비밀키를 이용해서 Server 인증서를 생성한다.

Server 인증서 생성하기
ZSH
1
2
3
openssl x509 -req -in server.csr -CA RootCA.crt -CAkey RootCA-key.pem -CAcreateserial -out server.crt -days 730 -extensions v3_ca -sha256 -extfile server.cnf
Certificate request self-signature ok
subject=C = KR, ST = "Magokjungang 8-ro, Gangseo-gu", L = Seoul, O = Systemv, OU = AI, CN = a.com, emailAddress = linux@a.com

생성된 인증서를 확인해 보면 CA:FALSE 로 나타나고, Subject Alternative Name 이 명세서에 내용과 같다.

PKCS12 포맷 인증서 변경

PKCS12 포맷은 Java 시스템에서 사용하는 인증서 포맷이다. 앞서 생성한 인증서는 PEM 포맷 인증서라서 Java 시스템에서 바로 이용할 수 없다. PEM 파일이 있다면 PCKS 포맷 인증서로 변경이 가능하다.

PCKS12 인증서 변환
ZSH
1
2
3
$ openssl pkcs12 -export -out keystore.p12 -inkey server-key.pem -in server.crt -name aiwire
Enter Export Password:
Verifying - Enter Export Password:

-name 은 Alias Name 을 말한다. 패스워드를 지정하지 않을려면 입력하지 않고 엔터만 치면 된다.

제대로 되었는지 다음과 같이 확인할 수 있다.

PKCS12 인증서 확인
ZSH
1
2
$ keytool -list -v -keystore keystore.p12 -storetype pkcs12
Enter keystore password:

SpringBoot 에서는 다음과 같이 application.properties 에 다음과 같이 사용할 수 있다.

SpringBoot 의 Embedded Server를 위한 SSL 설정
INI
1
2
3
4
5
#SSL
server.ssl.key-alias=aiwire
server.ssl.key-store=classpath:keystore.p12
server.ssl.key-store-type=PKCS12
server.ssl.key-store-password=12345

React + TypeScript 설치(yarn)

React + TypeScript 설치하는 방법으로 npm 을 이용하는 방법이 있다. 하지만 현 시점, 그러니까 React 버전이 19인 경우 경우에는 npm 명령어 설치할 경우에 오류를 만날 수 있다.

React 설치 오류

보통 React 설치를 위해서 다음과 같이 npx 명령어를 사용한다.

npx 를 이용한 react 설치
ZSH
1
npx create-react-app myapp --template typescript

하지만 이렇게 할 경우에 현시점에서 다음과 같이 오류가 발생한다.

React 설치 오류
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
Creating a new React app in D:\NodeJS\blogsample2\myapp.
 
Installing packages. This might take a couple of minutes.
Installing react, react-dom, and react-scripts with cra-template-typescript...
 
 
added 1323 packages in 40s
 
267 packages are looking for funding
  run `npm fund` for details
 
Initialized a git repository.
 
Installing template dependencies using npm...
npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: myapp@0.1.0
npm error Found: react@19.0.0
npm error node_modules/react
npm error   react@"^19.0.0" from the root project
npm error
npm error Could not resolve dependency:
npm error peer react@"^18.0.0" from @testing-library/react@13.4.0
npm error node_modules/@testing-library/react
npm error   @testing-library/react@"^13.0.0" from the root project
npm error
npm error Fix the upstream dependency conflict, or retry
npm error this command with --force or --legacy-peer-deps
npm error to accept an incorrect (and potentially broken) dependency resolution.
npm error
npm error
npm error For a full report see:
npm error C:\Users\orion\AppData\Local\npm-cache\_logs\2025-01-15T17_21_29_276Z-eresolve-report.txt
npm error A complete log of this run can be found in: C:\Users\orion\AppData\Local\npm-cache\_logs\2025-01-15T17_21_29_276Z-debug-0.log
`npm install --no-audit --save @testing-library/jest-dom@^5.14.1 @testing-library/react@^13.0.0 @testing-library/user-event@^13.2.1 @types/jest@^27.0.1 @types/node@^16.7.13 @types/react@^18.0.0 @types/react-dom@^18.0.0 typescript@^4.4.2 web-vitals@^2.1.0` failed

이에 대한 해결 방법으로 React 18 로 다운그레이드 하면 된다고 글도 많은데, 프로젝트가 React 18 을 요구하지 않을 경우를 제외하고 다운그레이드는 권장하지 않는다.

오류 원인

React 19 로 넘어오면서 의존성 라이브러리가 교체되었다고 한다. React 18 까지는 web-vitals 를 사용했었지만 19로 넘어오면서 vite 를 사용하도록 되었다고 한다. 변경된 라이브러리로 인해서 React 19 설치 명령어도 변경이 있었다.

Yarn 을 이용한 설치

npm 이 버전이 업데이트 되면서 yarn 의 사용이 많이 준 것도 사실이다. 하지만 현 시점에서 React + TypeScrpt 조합과 web-vitals 를 이용하고자 한다면 yarn 을 이용하는 것이 좋다.

yarn 을 글로벌(Global) 로 설치해 준다.

yarn 설치
ZSH
1
npm install -g yarn

그리고 yarn 을 이용해서 다음과 같이 명령어를 쳐준다.

yarn 를 이용한 React + TypeScript 앱 생성
ZSH
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
yarn create react-app myapp --template typescript
yarn create v1.22.22
[1/4] Resolving packages...
[2/4] Fetching packages...
[3/4] Linking dependencies...
[4/4] Building fresh packages...
 
success Installed "create-react-app@5.0.1" with binaries:
      - create-react-app
[#################################################################] 65/65
Creating a new React app in D:\NodeJS\blogsample2\myapp.
 
Installing packages. This might take a couple of minutes.
Installing react, react-dom, and react-scripts with cra-template-typescript...
 
yarn add v1.22.22
info No lockfile found.
 
.....
.....
 
success Uninstalled packages.
Done in 2.91s.
 
Created git commit.
 
Success! Created myapp at D:\NodeJS\blogsample2\myapp
Inside that directory, you can run several commands:
 
  yarn start
    Starts the development server.
 
  yarn build
    Bundles the app into static files for production.
 
  yarn test
    Starts the test runner.
 
  yarn eject
    Removes this tool and copies build dependencies, configuration files
    and scripts into the app directory. If you do this, you can’t go back!
 
We suggest that you begin by typing:
 
  cd myapp
  yarn start
 
Happy hacking!
Done in 37.33s.

yarn 을 이용하면 위와 같이 정상적으로 생성이 가능해진다. package.json 파일을 보면 다음과 같다.

package.json 파일
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "name": "myapp",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@testing-library/jest-dom": "^5.14.1",
    "@testing-library/react": "^13.0.0",
    "@testing-library/user-event": "^13.2.1",
    "@types/jest": "^27.0.1",
    "@types/node": "^16.7.13",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "react-scripts": "5.0.1",
    "typescript": "^4.4.2",
    "web-vitals": "^2.1.0"
  },

의존성 정보를 보면 React 19 와 web-vitals 를 조합해 설치된 것을 알 수 있다.

VSCode 설정

React + TypeScript 설치가 되었다면 프로그래밍을 해야한다. 대부분 VSCode 를 많이 쓰는데, VSCode 에서 제공하는 확장(Extensions) 를 활용하면 많은 이점이 있다. 이에 대해서 간단하게 알아본다.

ESLint

Create 으로 생성된 React 앱에서는 이미 ESLint 가 포함되어 있다. package.json 파일을 열어보면 eslint 관련 설정이 들어 있는 것을 확인할 수 있다.

이것을 VSCode 에디터 차원에서 지원을 할 수 있는데, ESLint 확장을 설치하면 된다.

이것을 설치하고 난 후에 VSCode 에 세팅(Setting) 에서 관련 내용을 추가할 수 있다.

Settings 에서 ‘eslint: probe’ 로 검색 후에 Workspace 탭을 확인하면 되는데, 여기서 javascript 와 typescript, typescriptreact 등이 있으면 된다.

Code Formatting

코드 포맷팅은 아주 중요하다고 할 수 있다. 여러사람이 협업을 하는 현대의 프로그래밍 작업에서 일관된 코드 포맷팅만큼 중요한 건 없다.

Prettier 는 유명한 코드 포맷터이다. React 앱을 생성하더라도 Prettier 는 설치가 되지 않는다. 다음과 같이 설치해 준다.

Prettier 설치
ZSH
1
npm i -D prettier

하지만 이렇게 하면 에러가 발생한다. npx 를 이용해 React 앱을 생성하려고 했던 거와 동일한 에러가 발생한다. yarn 을 이용해 React 앱을 생성했기 때문에 yarn 을 이용해야 한다.

Yarn 을 이용한 Prettier 설치
ZSH
1
yarn add --dev prettier

ESLint 도 코드 포맷관련해 기능을 가지고 있다. Prettier 를 설치하면 이 둘이 충돌이 발생할 수 있어서 이를 피하기 위해서 다음의 플러그인도 함께 설치해 준다.

ESLint 충돌을 피하기 위한 플러그인 설치
ZSH
1
yarn add --dev eslint-config-prettier eslint-plugin-prettier

‘eslint-config-prettier’ 는 ESLint Rule 충돌을 방지해주고 ‘eslint-plugin-prettier’ 는 ESLint 에게 코드 포맷터로 Prettier 를 사용하라고 알려준다.

ESLint 설정에서 Prettier 를 사용하도록 설정을 해준다. package.json 파일에 eslintConfig 세션에서 다음과 같이 prettier 설정을 추가해 준다.

1
2
3
4
5
6
7
8
9
10
11
{
...
  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest",
      "plugin:prettier/recommended"
    ]
  },
...
}

Prettier 설정을 위해서 .prettierrc.json 파일을 다음과 같이 생성한다.

.prettierrc.json 파일
1
2
3
4
5
6
7
8
{
  "printWidth": 100,
  "singleQuote": true,
  "semi": true,
  "tabWidth": 2,
  "trailingComma": "all",
  "endOfLine": "auto"
}

소스코드 작성시에 VSCode 에서 이를 활용할 수 있도록 Prettier 확장을 설치한다.

그리고 Settings -> Workspace 탭에서 Format On Save 를 체크 한다.

또, VSCode 의 Default Formatter 를 Prettier 로 변경해 준다.

마치며

React 19 로 넘어오면서 Vite(비트 라고 발음한다. 영어가 아니라 프랑어라고 한다.) 로 변경되었다. 그래서 npx 를 이용해 React 앱을 생성하면 오류가 발생하는데, yarn 을 통해서 React 19 를 사용하면 기본의 컴포넌트 조합을 그대로 사용할 수가 있다.

또, VSCode 와 통합을 위한 플러그인 설치과 설정등도 간단하게 알아 봤다.

React + Typescript 세팅하기(Webpack)

최근에 React + TypeScript 를 배우고 있는데, 생각만큼 잘 되지 않는 부분도 있고 각각의 의미가 다 있는 만큼 한번 정리할 필요가 있어서 글을 쓴다.

React + TypeScript 를 세팅하는 방법에는 두가지가 있다.

  • Webpack 을 이용하기
  • React App 생성하기

여기서는 Webpack 을 이용해 React + TypeScript 세팅을 해볼 것이다.

Webpack 프로젝트 생성

webpack 은 프로젝트 생성 툴이 아니다. webpack 은 React + TypeScript 와 아무런 상관이 없다. 단지 React + TypeScript 생성을 이용할 수 있는 하나의 방법이다.

webpack 은 CSS, JavaScript 등을 모두 생성해 준다. 특징이 있다면 JavaScript 의 경우에는 하나의 파일로 만들어 준다. 여러가지 파일을 만드는 것이 아니라 오직 한개의 파일로 모두 작성된다.

package.json 파일 생성

nodejs 에 프로젝트 정보파일인 package.json 파일을 생성해 준다. 프로젝트 이름, 의존성, npm 스크립트등을 기재하면 할 수 있지만 일단 최소한의 정보만 입력한다.

package.json 파일 생성
1
2
3
4
5
{
  "name": "myapp",
  "version": "0.1.0",
  "description": "My React and TypeScript app"
}

nodejs 의 의존성 패키지들은 npm 명령어로 설치하면 자동으로 package.json 파일에 기재된다.

web page 추가

src 폴더를 생성하고 그 안에 index.html 파일을 작성한다.

index.html 파일 생성
XHTML
1
2
3
4
5
6
7
8
9
10
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>My app</title>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

React 가 실행되면서 속성값인 id=”root” 의 div 에 내용을 추가해 준다.

TypeScript 추가

npm 명령어를 이용해서 TypeScript 를 추가해 준다. 한가지 주의해야 할 것은 결과물은 어짜피 JavaScript 로 나오기 때문에 개발할때만 TypeScript 만 필요하게 된다. 따라서 npm 을 이용해 설치할 때에는 개발목적으로 설치 하는게 좋다. ‘–save-dev’ 옵션을 사용하면 개발목적으로 설치할 수 있다.

TypeScript 개발목적으로 설치
ZSH
1
npm install --save-dev typescript

위 명령어는 다음과 같이 축약 할 수 있다.

npm 설치 명령어 축약
1
npm i -D typescript

설치를 하고 나면 다음과 같이 package.json 파일에 TypeScript 의존성이 추가 된다.

TypeScript 가 추가된 package.json
1
2
3
4
5
6
7
8
{
    "name": "myapp",
    "version": "0.1.0",
    "description": "My React and TypeScript app",
    "devDependencies": {
        "typescript": "^5.7.3"
    }
}

‘devDependencies’ 는 개발목적의 의존성을 말하며 그 안에 TypeScript 가 있다. 설치된 버전은 최신버전으인데, 설치할때에 버전을 따로 지정해 주지 않으면 최신버전으로 설치가 된다.

이제 TypeScript 를 위한 설정 파일을 root 폴더에 ‘tsconfig.json’ 이름으로 생성해 준다.

tsconfig.json 파일 생성
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
    "compilerOptions": {
        "noEmit": true,
        "lib": [
            "DOM",
            "DOM.Iterable",
            "ESNext"
        ],
        "moduleResolution": "node",
        "allowSyntheticDefaultImports": true,
        "esModuleInterop": true,
        "jsx": "react",
        "forceConsistentCasingInFileNames": true,
        "strict": true
    },
    "include": ["src"],
    "exclude": ["node_modules","dist"]
}

몇가지 설정은 다음과 같다.

  • ‘noEmit’ 를 true 로 하게되면 TypeScript 컴파일러가 아무것도 트랜스파일(trnaspilation)을 하지 않는다.
  • ‘allowSyntheticDefaultImports’ 와 ‘esModuleInterop’ 를 true 로 하게 되면 React 를 디폴트 임포트해준다. import React from ‘react’ 를 자동으로 해주는데, false 로 되었을 경우에는 import * as React from ‘react’ 로 임포트 된다.
  • ‘forceConsistentCasingInFileNames’를 true로 설정하면 임포트문에서 참조된 파일 이름의 케이싱이 일관되게 유지되는지 확인할 수 있는 타입 체킹 프로세스가 활성화 된다.

React 추가

이제 React 와 TypeScript 를 설치 한다.

React 설치
ZSH
1
npm install react react-dom

‘react’ 는 react 에 코어 라이브러리다. 모든 React 관련 라이브리가 사용한다. ‘react-dom’ 은 웹 앱(web app) 을 빌드하는데 사용되는 라이브러리다.

React 는 TypeScript 를 포함하지 않는다. 따라서 별도로 설치를 해줘야 하는데, 다음과 같이 해준다.

React 를 위한 TypeScript 설치
ZSH
1
npm install --save-dev @types/react @types/react-dom

‘–save-dev’ 옵션을 줘서 개발목적으로만 설치를 한다. 빌드하고 나온 결과물은 Javascript 로 되기 때문에 TypeScript 는 필요가 없기 때문에 개발목적으로만 설치를 하면 된다.

src 폴더에 루트(root) 컴포넌트라고 하는 ‘index.tsx’ 파일을 작성한다.

src/index.tsx
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import React, { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
 
const root = createRoot(
    document.getElementById('root') as HTMLElement
);
 
function App() {
    return <h1>My Super React and TypeScript App!</h1>;
}
 
root.render(
    <StrictMode>
        <App />
    </StrictMode>
);

위 코드는 id 가 ‘root’ 인 DOM 에 React 앱을 주입시켜 준다. 확장자가 js 가 아닌 tsx 로 한 이유는 Babel이 트랜스컴파일을 위해 JSX 를 포함하는 TypeScript 파일을 자동으로 찾도록 하고 TypScript 가 타입 체크 프로세스를 진행할 수 있도록 한다. 확장자가 ts 인 경우에는 TypeScript 코드인데 JSX 를 포함할 수 없다.

‘document.getElementById(‘root’) as HTMLElement’ 에서 ‘as HTMLElement’ 를 type assertion 이라고 하는데, TypeScript 를 이용하기 때문에 어떤 타입인지를 명시를 해줘야 한다. ‘document.getElementById’ 은 ‘as HTMLElement’ 거나 null 타입을 가질 수 있는데, ‘as HTMLElement’ 타입을 가지라고 명시하고 있다.

Babel 추가

Babel 은 React 와 TypeScript 코드를 JavaScript 코드로 트랜스파일(transpile, 혹은 transcompile)을 해준다. 역시 결과물은 JavaScript 만 있으면 되는거라서 개발목적으로만 설치하면 된다.

Babel 라이브러리 설치
ZSH
1
npm install --save-dev @babel/core

또, 최신의 JavaScript 기능을 사용하도록 하기 뒤해서 @babel/preset-env 라고 하는 Babel 플러그인을 설치해 준다.

@babel/preset-env 설치.
ZSH
1
npm i -D @babel/preset-env

또, React 를 JavaScript 로 변환하기 위해 @babel/preset-react 라고 하는 Babel 플러그인을 설치해 준다.

@babel/preset-react 설치
ZSH
1
npm i -D @babel/preset-react

똑같이 TypeScript 를 JavaScript 로 변환하기 위해 @babel/preset-typescript 라고 하는 Babel 플러그인을 설치해 준다.

@babel/preset-typescript 설치
ZSH
1
npm i -D @babel/preset-typescript

마지막으로 JavaScript 에 async 와 await 를 사용할 수 있도록 다음 두개의 플러그인을 설치해 준다.

JavaScript 에 async 와 await
ZSH
1
npm i -D @babel/plugin-transform-runtime @babel/runtime

Babel 관련해 설치는 마무리 되었다. 이제 .babelrc.json 설정 파일을 다음과 같이 작성해 준다.

.babelrc.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
    "presets": [
        "@babel/preset-env",
        "@babel/preset-react",
        "@babel/preset-typescript"
    ],
    "plugins": [
        [
            "@babel/plugin-transform-runtime",
            {
                "regenerator": true
            }
        ]
    ]
}

위 설정은 Babel 에게 설치된 Babel 플러그인들을 사용하도록 하며 설정된 되로 동작하도록 한다.

Webpack 추가

Webpack 은 주로 JavaScript 소스 코드 파일을 함께 묶는 유명한 툴이다. 파일을 스캔하는 것처럼 Babel 과 같은 다른 툴들을 실행시킬 수 있다. 또, 모든 소스 파일을 스캔하고 이것을 JavaScript 파일로 트랜스파일해 준다. Webpack 으로 만들어지는 결과물은 index.html 파일 하나로 작성되며 JavaScript 소스코드로 이 안에 있게된다.

Webpack 설치

Webpack 설치는 다음과 같다.

Webpack 설치
ZSH
1
npm i -D webpack webpack-cli

Webpack 은 ‘webpack’ 패키지 안에 TypeScript 타입을 가지고 있어서 별도로 TypeScript 를 설치하지 않아도 된다.

다음으로 Webpack 개발 서버를 설치한다.

webpack 개발 서버 설치
ZSH
1
npm i -D webpack-dev-server

Webpack 개발 서버는 개발하는 동안 사용되는 서버로, 소스코드가 변경되면 자동으로 웹 앱을 업데이트 해준다.

Babel 이 React 와 TypeScript 코드를 JavaScript 로 트랜스파일하도록 Webpack 플러그인을 설치 해줘야 한다. 이 플러그인을 ‘babel-loader’ 라고 한다.

babel 트랜스파일 플러그인 설치
ZSH
1
npm i -D babel-loader

Webpack 은 React 앱을 호스트 하기 위해 index.html 파일을 생성할 수 있는데, 마치 템플릿 처럼 그리고 React 앱들을 index.html 파일로 번들하기 위해서 index.html 파일을 사용할 것이다. 이러한 기능을 위해서 ‘html-webpack-plugin’ 플러그인을 설치해야 한다.

html-webpack-plugin 설치
1
npm i -D html-webpack-plugin

이제 Webpack 과 연관된 라이브러리 설치가 모두 끝났다.

Webpack 설정

Webpack 개발을 위한 설정이 필요하다. 먼저 설정을 TypeScript 형식으로 기술할 수 있도록 ‘ts-node’ 플러그인을 설치한다.

ts-node 설치
ZSH
1
npm i -D ts-node

이제 TypeScript 형식으로 Webpack 설정을 할 수 있다. Webpack 개발 설정 파일 이름은 ‘webpack.dev.config.ts’ 로 한다. ts 확정자를 가지고 있기 때문에 TypeScript 를 사용할 수 있으며, 이는 ‘ts-node’ 플러그인 때문에 가능한 것이다.

프로젝트 루트 디렉토리에 ‘webpack.dev.config.ts’ 파일을 다음과 같이 작성한다.

webpack.dev.config.ts 설정 파일
TypeScript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
import path from 'path';
import HtmlWebpackPlugin from 'html-webpack-plugin'
import {
    Configuration as WebpackConfig,
    HotModuleReplacementPlugin,
} from 'webpack';
import {
    Configuration as WebpackDevServerConfig
} from 'webpack-dev-server'
 
type Configuration = WebpackConfig & {
    devServer?: WebpackDevServerConfig;
}
 
const config: Configuration = {
    mode: 'development',
    output: {
        publicPath: '/',
    },
    entry: './src/index.tsx',
    module: {
        rules: [
            {
                test:/\.(ts|js)x?$/i,
                exclude: /node_modules/,
                use: {
                    loader: 'babel-loader',
                    options: {
                        presets: ['@babel/preset-env', '@babel/preset-react', '@babel/preset-typescript'],
                    }
                }
            }
        ]
    },
    resolve: {
        extensions: ['.tsx', '.ts', '.js']
    },
    plugins: [
        new HtmlWebpackPlugin({
            template: 'src/index.html',
        }),
        new HotModuleReplacementPlugin(),
    ],
    devtool: 'inline-source-map',
    devServer: {
        static: path.join(__dirname, 'dist'),
        historyApiFallback: true,
        port: 4000,
        open: true,
        hot: true
    }
};
 
export default config;
  • ‘import path’ 는 webpack 번들이 어디에 위치하는지 지정할 수 있다.
  • ‘import HtmlWebpackPlugin’ 은 index.html 파일 생성할 수 있도록 해준다.
  • webpack 설정 TypeScript 타입은 ‘webpack’ 과 ‘webpack-dev-server’ 패키지에서 제공된다. intersect type 을 사용해 이를 연결하고 Configuration이라는 타입을 만든다.

‘const config: Configuration’ 에서 Configuration 타입을 사용하는 것을 알 수 있다. 위 설정에 대해서 다음과 같은 의미를 가진다.

  • mode: ‘development’ 는 개발 모드를 지정한다. 이 모드는 React 개발 툴을 포함한다는 뜻이다.
  • output.publicPath 는 앱의 root 패스다.
  • entry 프로젝트에서 React 앱의 엔트리 지점인 index.tsx 가 어디에 있는지를 webpack 에게 알려준다.
  • Webpack 은 configuration 객체를 기본적으로 export 되기를 기대하기 때문에 기본적으로 export default config 를 해줘야 한다.
  • module 속성은 webpack 에게 다른 모듈을 어떻게 처리해야하는지 알려준다. webpack 에게 .js, .ts, tsx 확정자를 가지는 파일에 대해서 babel-loader 를 사용하라고 알려준다.
  • resolve.extensions 속성은 webpack 이 모듈을 해석하는 동안 TypeScript 파일과 JavaScript 파일을 찾을 수 있게 알려준다.
  • HtmlWebpackPlugin 은 HTML 파일을 생성하는데, src/index.html 을 생성하도록 한다.
  • HotModuleReplacementPlugin 는 모듈이 앱을 실행하는 동안에 전체 릴로드 없이 업데이트 하도록 해준다.
  • devtool 속성은 webpack 이 전체 인라인 소스 맵(full inline source map) 을 사용하라고 알려준다. 이는 트랜스파일하기 전에 원본 소스코드를 디버깅할 수 있도록 해준다.
  • devServer 속성은 webpack 개발 서버를 위한 설정이다. 이 설정에 따르면, 웹 서버의 포트는 4000 이며 루트 디렉토리는 dist 폴더다. historyApiFallback 는 deep link 를 위해 필요하며, open: true 는 서버가 시직되면 자동으로 브라우저를 열도록 한다.

이제 webpack 서버를 구동하기 위한 Script 를 package.json 파일에 설정해 준다.

webpack 웹 서버 시작 스크립트
1
2
3
"scripts": {
    "start": "webpack serve --config webpack.dev.config.ts"
}

Webpack 웹 서버 실행

이제 모든 준비는 끝이 났다. 다음과 같이 웹 서버를 실행 시켜 준다.

webpack 서버 실행.
ZSH
1
npm run start

정상적으로 실행이 되었다면 자동으로 브라우저가 실행되면서 화면이 출력된다.

React + TypeScript 설치 방법중에 한가지로 Webpack 을 이용하는 방법에 대해서 알아봤다.

Harbor 업데이트 하기

현재 개인적으로 Harbor 를 사용하고 있다. 별로 중요하지 않은 프로젝트여서 크게 신경쓰지 않는 저장소인데, 그래도 이래저래 테스트를 하는데 유용하다. Harbor 를 사용하다가 새로운 버전이 출시되어서 어떻게 업데이트를 했는지를 기록으로 남겨둔다.

Harbor Stop

Harbor 를 정지 시켜야 한다. Harbor 는 Docker-compose 기반으로 작동됨으로 docker-compose 명령어를 이용해서 다음과 같이 정지를 시켜줘야 한다.

ZSH
1
]# docker-compose down

Backup

혹시 잘못됐을때를 대비해 Backup 을 해준다. 디렉토리를 그냥 복사해주는 것으로 하면 된다.

ZSH
1
]# mv /app/harbor /app/harbor_20241228

새로운 버전 다운로드

Docker 명령어를 이용해서 새로운 버전의 harbor 이미지를 다운로드 한다.

1
]# docker pull goharbor/prepare:v2.10.3

데이터베이스 Migration 하기

기존의 데이터베이스를 새로운 버전으로 Migration 을 해야 한다.

1
]# docker run -it --rm -v /:/hostfs goharbor/prepare:v2.10.3 migrate -i /app/harbor/harbor.yml

데이터베이스 마이그레이션할 내용이 없으면 그냥 끝나게 된다.

새로운 버전 다운로드 후 설치

새로운 버전의 Harbor 을 다운로드 하고 난후, install.sh, common.sh, prepare 파일을 기존 디렉토리에 복사해 준다.

1
2
3
]# mv harbor_2.10.3/install.sh .
]# mv harbor_2.10.3/common.sh .
]# mv harbor_2.10.3/prepare .

설치

이제 새로운 버전을 설치를 한다.

1
]# ./install.sh --with-trivy

크게 어려운건 없다. 순서대로 했는데 중간에 문제가 되거나 하지 않았다. 업데이트를 한 후에 저장소를 사용하고 있는데, 기존 자료가 이상해지거나 되는 기능이 되지 않는 문제는 없었다.

유용한 Git 명령어

유용한 Git 명령어 정리.

Git 설정

대부분 Git 설정은 명령어로 한다.

1
git config --global user.name "systemv"

하지만 Git bash 를 이용할 경우에 설정 파일을 직접 편집하도록 할 수도 있다.

git 설정 파일 편집
ZSH
1
git config -e --global

브랜치 리스트

브랜치 목록 보기
ZSH
1
2
3
git branch     # 로컬 브랜치만 보기
git branch -a  # 로컬, 원격 모두 보기
git branch -r  # 원격 브랜치만 보기

로컬 브랜치 삭제

로컬 브랜치 삭제
ZSH
1
git branch -d <브랜치 이름>

원격 브랜치 삭제

원격 브랜치 삭제는 branch 명령어를 사용하지 않는다.

원격 브랜치 삭제
ZSH
1
git push origin --delete <원격 브랜치 이름>

로컬에 원격 브랜치 목록 업데이트

원격 브랜치 목록 보기를 했을때에 실제 원격 브랜치와 차이가 있을 수 있다. 이것때문에 헷깔릴 수 있는데, 원격 브랜치 목록을 로컬에 반영하기 위해서는 다음과 같이 해준다.

원격 브랜치 목록 가져와 업데이트 하기
ZSH
1
2
3
git remote update origin --prune
git remote prune origin
git fetch --prune

prune 을 자동으로 되도록 설정할 수 있다.

prune 자동 설정
ZSH
1
2
git config --global remote.origin.prune true  # origin 저장소에 prune 설정
git config --global fetch.prune true   # 모든 fetch 작업에서 prune 활성화

git 설정 파일에서는 다음과 같이 설정할 수 있다.

Git 설정 파일
ZSH
1
2
3
4
5
6
7
8
9
# git config --global fetch.prune true
[fetch]
    prune = true
 
# git config remote.origin.prune  true
[remote "origin"]
    url = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    fetch = +refs/heads/*:refs/remotes/origin/*
    prune = true

Spring boot 에 systemd 유닛 만들기

요즘 프로젝트를 하고 있는데, 역시나 자바 시스템이 있다. Spring Boot3 을 사용하고 있고 자바 17을 쓰는등 나름대로 괜찮은 환경에서 개발이 이루어지고 있다. 그런데, 이것을 서버에서 배포를 하고 Spring Boot 를 실행해야 하는데, 어떻게 하나 봤더니 초보자 수준도 못 벗어나는 설정을 하고 있으니… 안타까운 마음에 어떻게 하는 것이 좋은 것인지 한번 적어봤다.

Spring boot, jar 실행 파일

Spring Boot3 를 컴파일 하면 jar 파일 나온다. 그리고 별다른 서버 없이도 바로 실행하고 접속이 가능해 진다. 한가지 재미있는 사실은 많은 사람들이 Spring boot3 에 실행 파일 jar 이 내장된 WAS 서버가 구동되면서 실행된다는 걸 모른다는 거다. 심지여 그것이 Tomcat 이라는 것도. 물론 어떤 프로그래밍 모델인지에 따라서 Tomcat 이 되기도 하고 Netty 되기도 하지만, 과연 Reactive Programming Model 로 짜는 사람이 몇이나 있나 싶다. 대부분 Spring MVC 이고 Servlet 이면 기본적으로 Tomcat 이 구동된다. 내장형 Tomcat

프로젝트에서 쓰는 방법

현재 프로젝트에서는 jar 실행을 위해서 스크립트 파일을 만들었다. 대략 다음과 같다.

Spring Boot 실행을 위한 시작 스크립트
ZSH
1
2
3
#!/bin/bash
 
java -jar -Dspring.profiles.active=prd -Dspring.jpa.hibernate.ddl-auto=none /app/helloworld.jar

자바 옵션인 -D 옵션과 jar 실행 파일을 인자로 주고 있다. 그런데, 특이하게도 데몬화를 하지 않았고 많은 초보자식 설정인 nohup 도 없다. 이렇게되면 프로그램이 포그라운드(Foreground) 실행이되어서 쉘이 묶이게 된다.

어떻게 했지? 봤더니 systemd 에 이 실행파일을 넣고 systemd 를 통해서 시작/중지를 하고 있었다. 다음과 같다.

Spring Boot 를 위한 Systemd 유닛 파일
INI
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[Unit]
Description=Spring Boot hello world
After=network-online.target
Wants=network-online.target
 
[Service]
Type=simple
User=lgbcadm
Environment=RUNTIME_BASE_DIR=/app
ExecStart=/app/helloworld_run.sh
ExecStop=/bin/kill -TERM ${MAINPID}
ExecReload=/bin/kill -HUP ${MAINPID}
Restart=on-failure
 
[Install]
WantedBy=multi-user.target

‘ExecStart=’ 에 쉘 스크립트 실행 파일을 지정해 주고 있다.

왜 이렇게 해야 하나? 왜? 이해 할 수 없는 구조다.

Spring 공식 문서

Systemd 유닛에 등록하는 방법은 Spring 공식문서에도 나와 있다.

57.1.2 Installation as a systemd service

이 문서에 나온 systemd 유닛 파일은 프로젝트 유닛 파일과 다르다. 공식 문서에 내용은 그냥 아주 기초적인 내용만 적혀 있다. 실제 프로젝트에 적용하기에는 무리가 있다.

설정파일 작성

Spring boot 를 위한 설정을 systemd 유닛에서 사용할 수 있는 별도의 파일로 작성한다. 이 설정은 JAVA_OPTS 의 내용을 담으면 된다.

Spring boot 를 위한 설정 파일
INI
1
JAVA_OPTS='-Dspring.profiles.active=prd -Dspring.jpa.hibernate.ddl-auto=none'

이것을 이제 systemd 에서 사용하면 다음과 같다.

Spring Boot 를 위한 Systemd 유닛 파일
INI
1
2
3
4
5
6
7
8
9
10
11
[Unit]
Description=myapp
After=syslog.target
 
[Service]
EnvironmentFile=/etc/sysconfig/helloworld.conf
ExecStart=/usr/bin/java $JAVA_OPTS -jar /app/helloworld.jar
SuccessExitStatus=143
 
[Install]
WantedBy=multi-user.target

공식문서에 나와 있는 내용과 EnvironmentFile 속성으로 외부에서 JAVA_OPTS 를 지정한 내용을 읽어오도록 하면 충분히 사용가능해 진다.

프로젝트에서 처럼 스크립트로 한번 감싸고 이것을 다시 systemd 유닛에서 실행되도록 할 필요가 없다는 것이다.

몇가지 개선 설정

공식문서는 간단한 예이다. 실행이 가능한 정도의 유닛 파일일 뿐이다. systemd 를 이용해 자바 애플리케이션을 실행할 때에는 여러가지를 고려해야 한다.

일단 자바 애플리케이션은 네트워크를 기반으로 한다. 따라서 네트워크 온라인 상태여야 한다. 또, StdOut, StdErr 를 Journal 로 내보내도록 해야 한다.