EC2에 Docker로 배포하기

로컬에서 만든 이미지를 EC2로 옮겨 실행한다. 이 과정을 손으로 한 번 해봐야 GitHub Actions로 자동 배포하기에서 무엇이 자동화되는지 보인다.

#1. EC2에 Docker 설치

EC2 인스턴스에 SSH로 접속한 뒤 진행한다.

# Docker 설치
sudo dnf install -y docker

# 부팅 시 자동 시작 + 지금 바로 시작
sudo systemctl enable --now docker

# ec2-user 가 sudo 없이 docker 를 쓸 수 있게 한다
sudo usermod -aG docker ec2-user

$ docker ps
permission denied while trying to connect to the Docker daemon socket

재접속 후 확인한다.

$ docker version --format 'Client {{.Client.Version}} / Server {{.Server.Version}}'
Client 25.0.14 / Server 25.0.16

$ docker info | grep -E "Server Version|Storage Driver|Total Memory"
 Server Version: 25.0.16
 Storage Driver: overlay2
 Total Memory: 913.2MiB

#1-1. 컨테이너 로그 크기 제한

컨테이너를 띄우기 전에 한 번 해 둔다. 기본 설정에서는 컨테이너 로그가 디스크에 끝없이 쌓인다. 서버는 몇 달씩 켜 두는 것이라 결국 디스크를 채운다 — Docker 환경 설정 3절에서 본 문제다.

sudo tee /etc/docker/daemon.json > /dev/null <<'EOF'
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
EOF

sudo systemctl restart docker
docker info --format '{{.LoggingDriver}}'
# json-file

이제 컨테이너 하나의 로그는 최대 30 MB 로 묶인다. 이 설정은 이후에 만드는 컨테이너부터 적용되므로, 아직 아무것도 띄우지 않은 지금 해 두는 것이 좋다.

#2. 이미지를 서버로 어떻게 옮기는가

여기서 한 가지 정하고 가야 한다. EC2에서 소스를 받아 빌드할 것인가, 로컬에서 빌드한 이미지를 옮길 것인가?

이 교안은 로컬(나중에는 CI)에서 빌드하고 서버는 실행만 한다. 이유는 두 가지다.

빌드 환경이 서버마다 달라지면 안 된다. 서버에서 빌드하면 그 서버에 깔린 JDK·Gradle 버전에 결과가 좌우된다. 서버가 여러 대면 서로 다른 결과물이 돌아갈 수도 있다. 이미지를 한 번 만들어 그대로 옮기면 어느 서버에서든 똑같은 것이 돈다. 이것이 Docker 개요 장에서 말한 "빌드 한 번, 어디서나 실행"이다.

t3.micro는 빌드하기에 작다. 메모리 1GB에서 Gradle 빌드는 버겁고, 빌드하는 동안 서버 자원을 그만큼 쓴다. 운영 중인 서버라면 서비스에 영향이 간다.

그래서 흐름은 이렇게 된다.

로컬                      레지스트리(GHCR)              EC2
────                      ─────────────                ────
docker build      ──push──▶   이미지 저장   ──pull──▶   docker run

레지스트리는 이미지를 올려두고 내려받는 창고다. Docker Hub가 가장 유명하고, 이 교안은 GHCR(GitHub Container Registry)을 쓴다. GitHub 저장소를 이미 쓰고 있으니 별도 가입이 필요 없고, GitHub Actions로 자동 배포하기에서 GitHub Actions와 연결할 때 이점이 크다.

#3. 이미지 빌드와 GHCR 업로드

#3-0. GitHub 저장소 준비

여기까지는 로컬 폴더만으로 실습했다. 이 장부터는 GitHub 저장소가 필요하다 — GHCR 패키지가 저장소에 딸려 붙고, GitHub Actions로 자동 배포하기의 자동 배포는 push 를 신호로 돈다.

GitHub 에서 visit-counter 라는 이름으로 저장소를 만든다. 공개·비공개 어느 쪽이든 된다.

저장소에 넣을 것은 Docker Compose 장에서 만든 app/ 디렉터리의 내용이다. app/ 을 통째로 올리는 것이 아니라 그 안의 파일들이 저장소 루트에 오도록 넣는다.

visit-counter/            ← 저장소 루트
├── Dockerfile
├── docker-entrypoint.sh
├── build.gradle
├── settings.gradle
└── src/

cd visit-counter
git init
git add .
git commit -m "feat: 방문자 카운터"
git branch -M main
git remote add origin https://github.com/<GitHub사용자명>/visit-counter.git
git push -u origin main

#3-1. 이미지 빌드

Supabase 장의 PostgreSQL 전환까지 마친 상태로, 저장소 루트에서 빌드한다.

GHCR에 올릴 이미지는 이름 규칙이 정해져 있다.

ghcr.io/<GitHub사용자명>/<이미지이름>:<태그>

docker build --platform linux/amd64 -t ghcr.io/<GitHub사용자명>/visit-counter:1.0 .

exec /docker-entrypoint.sh: exec format error

docker image inspect ghcr.io/<GitHub사용자명>/visit-counter:1.0 --format '{{.Architecture}}'
# amd64 여야 한다

$ docker build -t ghcr.io/MyName/visit-counter:1.0 .
ERROR: failed to build: invalid tag "ghcr.io/MyName/visit-counter:1.0": repository name must be lowercase

#3-2. GHCR 로그인

GHCR에 올리려면 write:packages 권한을 가진 토큰이 필요하다.

GitHub → 우상단 프로필 → Settings → 좌측 맨 아래 Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)

Developer settings → Personal access tokens → Tokens (classic)

체크할 것은 write:packages 하나다. 만료 기간도 실습 기간에 맞춰 짧게 잡는다.

write:packages 를 체크하면 repo 까지 함께 켜지고 해제할 수 없다

# macOS / Linux / Git Bash — 토큰을 변수에 담아 로그인한다 (셸 기록에 토큰이 남지 않도록)
read -s GHCR_TOKEN
echo "$GHCR_TOKEN" | docker login ghcr.io -u <GitHub사용자명> --password-stdin
unset GHCR_TOKEN

# Windows PowerShell — 화면에 보이지 않게 입력받아 넘긴다
$t = Read-Host -AsSecureString "GHCR token"
[System.Net.NetworkCredential]::new("", $t).Password | docker login ghcr.io -u <GitHub사용자명> --password-stdin
Remove-Variable t

gh auth refresh -s write:packages
echo $(gh auth token) | docker login ghcr.io -u <GitHub사용자명> --password-stdin

docker login ghcr.io -u 이름 -p ghp_xxxxx     # 하지 말 것

#3-3. push

docker push ghcr.io/<GitHub사용자명>/visit-counter:1.0

올라간 이미지는 GitHub 프로필의 Packages 탭에서 볼 수 있다.

GitHub Packages 에 올라간 이미지 — Private 배지를 확인한다

#3-4. 패키지를 공개로 바꾸기

$ docker pull ghcr.io/이름/visit-counter:1.0
Error response from daemon: Head "https://ghcr.io/v2/이름/visit-counter/manifests/1.0": unauthorized

패키지 페이지 오른쪽의 Package settings → 맨 아래 Danger Zone → Change visibility

Package settings → Danger Zone → Change visibility

Public 을 고르고, 확인란에 패키지 이름을 직접 입력해야 버튼이 활성화된다.

패키지 이름을 직접 입력해야 전환된다

이렇게 하면 EC2에서 로그인 없이 docker pull 할 수 있다.

#4. EC2에서 내려받아 실행

#4-1. 접속 정보를 파일로 준비

Supabase 장에서 정리해 둔 세 값을 EC2에 파일로 만든다.

cat > ~/app.env <<'EOF'
SPRING_DATASOURCE_URL=jdbc:postgresql://<풀러호스트>:5432/postgres
SPRING_DATASOURCE_USERNAME=postgres.<프로젝트REF>
SPRING_DATASOURCE_PASSWORD=<비밀번호>
EOF

# 소유자만 읽을 수 있게 한다
chmod 600 ~/app.env

SPRING_DATASOURCE_PASSWORD='mypassword'

#4-2. 실행

docker pull ghcr.io/<GitHub사용자명>/visit-counter:1.0

docker run -d \
  --name visit-counter \
  -p 8080:8080 \
  --env-file ~/app.env \
  --restart unless-stopped \
  ghcr.io/<GitHub사용자명>/visit-counter:1.0

--restart unless-stopped 는 서버가 재부팅돼도 컨테이너가 다시 뜨게 한다. 이게 없으면 EC2를 재시작할 때마다 손으로 올려야 한다.

상태를 확인한다.

docker ps
docker logs -f visit-counter

#5. 보안 그룹에 8080 열기

컨테이너는 떴지만 아직 브라우저로는 접속되지 않는다. EC2 보안 그룹이 막고 있기 때문이다.

EC2 콘솔 → 인스턴스 선택 → 보안 탭 → 보안 그룹 링크 클릭

인스턴스 [보안] 탭 — 보안 그룹 링크와 현재 인바운드 규칙

열린 화면에서 인바운드 규칙 편집 → 규칙 추가

사용자 지정 TCP 8080 을 내 IP 로만 연다

#6. 동작 확인

브라우저에서 http://<EIP>:8080 으로 접속한다.

브라우저에서 http://:8080 접속

새로고침할 때마다 숫자가 올라가면 성공이다. 이 숫자는 EC2가 아니라 Supabase에 저장된다. 컨테이너를 지웠다 다시 띄워도 숫자가 유지되는지 확인해 보자.

docker rm -f visit-counter
docker run -d --name visit-counter -p 8080:8080 --env-file ~/app.env \
  --restart unless-stopped ghcr.io/<GitHub사용자명>/visit-counter:1.0

curl http://localhost:8080

숫자가 1로 돌아가지 않고 이어진다면, 애플리케이션은 상태를 갖지 않고 데이터는 데이터베이스에 있다는 구조가 제대로 된 것이다. 이 성질 덕분에 GitHub Actions로 자동 배포하기에서 컨테이너를 통째로 갈아치우는 배포가 가능해진다.

#7. 직접 연결로 바꿔보면 어떻게 되는가

Supabase 장에서 직접 연결(Direct connection)은 EC2에서 쓸 수 없다고 했다. 말로만 듣지 말고 직접 확인해 보자. 실패를 한 번 봐두면 나중에 같은 증상을 만났을 때 훨씬 빨리 알아챈다.

#7-1. EC2 에 IPv6 주소가 있는가

가장 먼저 볼 것은 상대가 아니라 내 쪽이다.

$ ip -6 addr show scope global
(아무것도 출력되지 않는다)

출력이 비어 있다. 이 인스턴스에는 글로벌 IPv6 주소가 없다. IPv6 로만 갈 수 있는 곳에는 애초에 패킷을 보낼 수 없다.

#7-2. 상대 주소는 어느 쪽인가

$ getent ahostsv4 db.<프로젝트REF>.supabase.co
(출력 없음)

$ getent ahostsv6 db.<프로젝트REF>.supabase.co
2406:da12:5ca:b702:28a6:58b9:f8f4:a76b STREAM db.<프로젝트REF>.supabase.co

직접 연결 주소에는 IPv4 주소가 아예 없다. 풀러는 반대다.

$ getent ahostsv4 <풀러호스트>
15.164.120.176  STREAM pool-tcp-ap-northeast-2-....elb.ap-northeast-2.amazonaws.com
13.124.111.232  STREAM
15.165.245.138  STREAM

::ffff:15.165.245.138 STREAM pool-tcp-....elb.ap-northeast-2.amazonaws.com

#7-3. 실제로 열어 본다

DNS 만 봐도 결론은 났지만, 연결을 직접 시도해 보면 오류 문구가 손에 남는다.

$ timeout 8 bash -c "exec 3<>/dev/tcp/db.<프로젝트REF>.supabase.co/5432"
bash: connect: Network is unreachable
bash: line 1: /dev/tcp/db.<프로젝트REF>.supabase.co/5432: Network is unreachable

$ timeout 8 bash -c "exec 3<>/dev/tcp/<풀러호스트>/5432"
(아무 출력 없이 끝난다 = 연결 성공)

Network is unreachable — 커널이 경로가 없다고 즉시 거절한 것이다. 방화벽에 막혔다면 이렇게 빨리 끝나지 않고 한참 기다리다 시간 초과가 난다.

#7-4. 애플리케이션으로 확인

같은 일을 애플리케이션으로 겪어 보면 오류가 어떻게 포장돼 나오는지 알 수 있다.

docker run --rm \
  -e SPRING_DATASOURCE_URL='jdbc:postgresql://db.<프로젝트REF>.supabase.co:5432/postgres' \
  -e SPRING_DATASOURCE_USERNAME='postgres' \
  -e SPRING_DATASOURCE_PASSWORD='<비밀번호>' \
  ghcr.io/<GitHub사용자명>/visit-counter:1.0

확인이 끝나면 다시 풀러 주소로 돌아간다. --rm 을 붙였으므로 이 컨테이너는 종료와 함께 사라진다.

#8. 실습 정리

GitHub Actions로 자동 배포하기에서 이어서 쓴다. 컨테이너는 그대로 둬도 된다.

EC2 인스턴스를 당분간 쓰지 않는다면 중지(Stop) 한다. 중지 상태에서는 인스턴스 요금이 발생하지 않는다. 다만 EC2 장에서 다룬 대로 EBS 스토리지와 공인 IPv4 요금은 계속 나간다.

다음 장 — GitHub Actions로 자동 배포하기