[CI/CD] Docker Compose + SFTP 방식 구성 및 배포 방법

해당 글에서는 CI/CD 파이프라인이 구축되기 전에 사용자의 수동 배포를 최소한으로 줄이기 위해 임시적으로 사용하는 SFTP 방식을 이용한 사례에 대해서 작성한 글입니다.

1) 배포방식

---

💡 배포방식

- 현재 배포 환경은 CI/CD 파이프라인이 구축되기 이전 단계로 GitHub Actions Runner 같은 자동화 도구를 통한 배포가 아닌, 사용자가 수동 배포 과정을 최소한으로 줄이기 위해 임시로 운영하는 방식입니다.

- 별도의 Docker Registry를 운영하지 않기 때문에, 개발 PC에서 Docker 이미지를 빌드한 뒤 docker save 명령으로 .tar 파일로 저장합니다. 이 파일을 SFTP를 통해 운영 서버로 전송하고, 운영 서버에서 docker load로 이미지를 로드한 뒤 docker compose up -d로 서비스를 실행하는 흐름입니다.

- 이 방식은 Registry 구축 없이도 이미지를 전달할 수 있고, 인터넷이 차단된 폐쇄망 환경에서도 적용 가능하다는 장점이 있습니다. 반면 매 배포마다 수동 작업이 필요하고, 배포 이력 관리가 어려우며, 이미지 태그 불일치 등의 휴먼 에러가 발생할 수 있다는 한계가 있습니다.

- 향후 CI/CD가 구축되면, git push를 트리거로 Runner가 자동으로 이미지를 빌드하고 Registry에 push 한 뒤 운영 서버에서 pull 하여 배포하는 구조로 전환될 예정이며, 현재의 수동 과정은 그 과도기에 사용하는 임시 배포 방식입니다.

 

1. 배포 처리 과정

---

💡 배포 처리 과정

1. 소스코드
- 배포의 시작점으로 React, Spring Boot 등 로컬에서 개발 완료된 상태의 코드를 준비합니다.
- 또한, .env, docker-compose.yml, Dockerfile 등이 함께 준비되어 있어야 합니다.

2. Docker 이미지 빌드
- Dockerfile을 기반으로 소스코드를 컨테이너 이미지로 패키징 하는 단계를 의미합니다.
- 이 시점에 OS, 런타임, 의존성, 앱 코드가 하나의 이미지로 묶이며, 빌드 결과물은 로컬 Docker에만 존재해야 합니다.

3. tar 파일 Export
- Docker 이미지를 파일로 직렬화하는 단계를 의미합니다. Docker Hub 같은 외부 레지스트리 없이 이미지를 전송하기 위해 사용이 됩니다.

4. SFTP 전송
- PC에서 압축된 tar 파일을 배포될 원격 서버로 복사를 하는 과정입니다. 이 과정에서는 FTP 또는 SFTP 전송을 하며, SFTP 클라이언트(FileZila, Termius 등)를 사용하여 전송을 합니다.

5. 파일 수신 (서버 폴더 이동)
- 서버에서 전송받은 파일 위치를 확인하는 단계이며, 별도 작업이라기보다 다음 단계 전 준비 확인 과정입니다.

6. 이미지 로드
- 서버의 Docker에 이미지를 등록하는 단계를 의미합니다.

7. 컨테이너 실행
- compose.yml 기반으로 컨테이너를 백그라운드로 실행. 포트, 볼륨, 환경변수 등이 이 파일에 정의되어 있는 파일을 실행합니다.

8. 배포 완료
- 서비스 정상 동작 확인합니다.

 

2. 서버 내 compose.yaml

---

💡 서버 내 compose.yaml

- 해당 서버는 배포될 리눅스 서버를 의미하며, 이를 위치하며 Docker Compose를 통하여서 배포가 이루어집니다.

 

 

💡 depends_on 기반 서비스 실행 과정

- 해당 서비스는 db → api → web 순서로 기동 됩니다.

1) db : PostgreSQL

- postgres:17.9 이미지로 컨테이너를 생성하며 기본적인 TimeZone 설정을 지정하였습니다.

1. command, environment 속성: 기본적인 TimeZone 설정을 지정하였습니다.

2. env_file 속성: 서버 내에 위치해 있는 파일로, 기본적인 db 연결을 위한 POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD를 지정하였습니다.

3. volumes 속성 : pgdata:/var/lib/postgresql/data 컨테이너를 삭제하더라도 데이터를 유지하기 위해 지정하였습니다.


2) api : Spring Boot

- 사전에 외부에서 .tar 파일로 빌드된 이미지를 가져와, 이미지 로드로 불러온 Spring Boot 컨테이너 이미지를 사용합니다.

1. env_file 속성: 서버 내에 위치해 있는 파일로, DB 접속 정보, Spring 프로파일 등 환경변수 주입을 하는 속성입니다.

2. volumes 속성 : bind mount로 호스트의 ./uploads 디렉토리를 컨테이너 /uploads에 매핑되며, 파일 업로드 데이터가 호스트에 직접 저장됩니다.

3. environment 속성: JVM/OS 레벨 타임존 설정을 합니다.

4. restart 속성: docker stop을 하기 전까지 수행이 됩니다.


3) web : React
- 사전에 외부에서 .tar 파일로 빌드된 이미지를 가져와, 이미지 로드로 불러온 Vite로 빌드된 정적 파일을 서빙하는 Nginx 컨테이너 이미지를 사용합니다.

1. volumes 속성: volumes로 호스트의 default.conf를 Nginx 설정에 bind mount → 이미지 재빌드 없이 Nginx 설정 변경 가능하도록 구성하였습니다. (컨테이너 재시작만 하면 됨)

2. restart 속성: docker stop을 하기 전까지 수행이 됩니다.

services:
  db:
    image: postgres:17.9
    container_name: xxx-db
    command: postgres -c timezone=Asia/Seoul
    environment:
      - TZ=Asia/Seoul
      - PGTZ=Asia/Seoul
    ports:
      - "5432:5432"
    env_file:
      - ./env/.env.db
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: always

  api:
    image: xxx-xxx-api
    container_name: xxx-api
    ports:
      - "8001:8001"
    env_file:
      - ./env/.env.dev
    depends_on:
      - db
    restart: unless-stopped
    volumes:
      - "./uploads:/uploads"
    environment:
      - TZ=Asia/Seoul
  web:
    image: xxx-xxx-web
    container_name: dkcns-web
    ports:
      - "80:80"
    depends_on:
      - api
    restart: unless-stopped
    volumes:
      - "/home/tomcat/nginx/default.conf:/etc/nginx/conf.d/default.conf"

volumes:
  pgdata:

 
 

 💡 [참고] 해당 과정에서 적용한 TimeZone에 대해 궁금하시면 아래의 글을 참고하시면 도움이 됩니다.

[DB] PostgreSQL + Docker TimeZone 설정하기

 

2) API 배포(Spring Boot)

---

 

1. DockerFile 구성

---

💡 DockerFile 구성

- 루트 경로에 소스코드를 이미지화시키기 위한 Dockerfile을 구성합니다.

 

💡 Dockerfile 파일 설명

1. FROM amazoncorretto:21-alpine
- Amazon이 만든 JDK 21으로 지정을 합니다.

2. WORKDIR /app
- 컨테이너 안에서 작업 디렉터리를 /app으로 설정합니다.

3. COPY build/libs/xxxxxAPI-0.0.1-SNAPSHOT.jar app.jar
- 로컬(내 PC 또는 CI 서버)의 Gradle 빌드 결과물을 컨테이너 안으로 복사합니다.

4. EXPOSE 8001
- 컨테이너가 8001 포트를 사용한다고 선언합니다.

5. ENTRYPOINT ["java", "-jar", "app.jar"]
- 컨테이너 시작 시 실행할 명령어. java -jar app.jar를 실행해서 Spring Boot 앱을 구동함.

# 1
FROM amazoncorretto:21-alpine

# 2
WORKDIR /app

# 3
COPY build/libs/xxxxxAPI-0.0.1-SNAPSHOT.jar app.jar

# 4
EXPOSE 8001

# 5
ENTRYPOINT ["java", "-jar", "app.jar"]

 
 

2. build-and-export.sh 구성

---

💡 build-and-export.sh 구성

- Gradle 빌드 → DockerFile 이미지 빌드 → tar 파일로 export까지 수행하는 Shell 파일입니다.

#!/bin/bash
# build-and-export.sh

# 1. Gradle 빌드
./gradlew clean build -x test

# 2. Docker 이미지 빌드
docker build --platform linux/amd64 -t xxx-api .

# 3. tar로 export
docker save -o ~/Desktop/docker/xxx-api.tar xxx-api

echo "완료: xxx-api.tar 생성됨"

 
 

3. shell 파일 실행

---

💡 shell 파일 실행

- Gradle 빌드 → DockerFile 이미지 빌드 → tar 파일로 export까지 수행을 하는 과정입니다.

# shell 파일 실행
$ ./build-and-export.sh

 
 

💡 [참고] Docker Desktop이 실행이 되었는지 확인을 합니다. 아래와 같이 오류가 발생함.

- Consider enabling configuration cache to speed up this build: https://docs.gradle.org/9.4.1/userguide/configuration_cache_enabling.html ERROR: Cannot connect to the Docker daemon at unix:///Users/leejonghoon/.docker/run/docker.sock. Is the docker daemon running? Cannot connect to the Docker daemon at unix:///Users/leejonghoon/.docker/run/docker.sock. Is the docker daemon running?

- Docker Desktop을 실행시키면 됩니다.

 
 

4. 아래와 같이 tar 파일이 생성되었습니다.

---

 

5. [Termius] 연결된 리눅스 서버에 SFTP로 해당 파일을 옮겨둡니다

---

 
 

6. [Termius] tar 파일을 로드해 옵니다.

---

 

$ docker load -i xxx-api.tar

 
 

7. [Termius] Docker 컨테이너 배포 완료

---

💡 [Termius] Docker 컨테이너 배포 완료

- Docker 컨테이너를 재 실행하여 정상적으로 소스코드 반영이 완료되었습니다.

docker compose up -d

 
 
 

3) 화면 배포(React)

---

 

1. DockerFile

---

💡 DockerFile 구성

- 루트 경로에 소스코드를 이미지화 시키기 위한 Dockerfile을 구성합니다.

 

💡 Dockerfile 파일 설명

1. FROM node:24.15.0-alpine
- Node.js 24.15.0 기반의 Alpine Linux 이미지 사용하며, Alpine은 경량 Linux 배포판으로 이미지 크기를 최소화하였습니다

2. WORKDIR /app
- 컨테이너 안에서 작업 디렉토리를 /app으로 설정합니다.

3. RUN yarn global add serve
- 정적 파일 서버인 serve 패키지를 전역 설치하며, React 빌드 결과물(정적 HTML/JS/CSS)을 HTTP로 서빙하는 역할을 수행합니다.

4. COPY dist/ ./dist/
- 로컬 머신의 dist/ 폴더(빌드 결과물)를 컨테이너의 /app/dist/로 복사합니다.

5. EXPOSE 80
- 컨테이너가 80번 포트를 사용한다고 선언합니다

6. CMD ["serve", "-s", "dist", "-l", "80"]
- dist 폴더를 80번 포트로 웹서버처럼 서빙하도록 구성

# 1
FROM node:24.15.0-alpine

# 2
WORKDIR /app

# 3
RUN yarn global add serve

# 4
COPY dist/ ./dist/

# 5
EXPOSE 80

# 6
CMD ["serve", "-s", "dist", "-l", "80"]

 
 

2. package.json 내에 스크립트 구성

---

💡 package.json 내에 스크립트 구성

- 패키지 라이브러리를 기반으로 스크립트를 수행하도록 하면, 긴 수행 과정을 하나의 명령어로 처리할 수 있습니다.
- 4개 명령어를 &&로 순서대로 실행하는 npm 스크립트이며, 하나라도 실패하면 중단이 됩니다.

"scripts": {
 "build:docker": 
 "vite build --mode production && docker build --platform linux/amd64 -f Dockerfile -t xxx-xxx-web . && docker save -o /Users/leejonghoon/Desktop/docker/xxx-xxx-web.tar xxx-xxx-web && echo '완료: xxx-xxx-web.tar 생성됨'",
}

 

💡 1단계

- 소스코드를 빌드하는 과정입니다.
- Vite로 프로덕션 빌드를 수행하며, .env.production 환경변수 적용해서 dist/ 폴더를 생성합니다

vite build --mode production

 

💡 2단계

- 빌드된 소스코드를 컨테이너 이미지화 하는 과정입니다.
1. —platform linux/amd64 : 플랫폼을 linux/amd64로 지정
2. -f Dockerfile : 사용할 Dockerfile 지정
3. -t xxx-xxx-web: 컨테이너 이미지 이름 태그
4. . : 빌드 컨텍스트(현재 디렉토리)

docker build --platform linux/amd64 -f Dockerfile -t xxx-xxx-web .

 
 
 

💡 3단계

- 컨테이너 이미지를 .tar 파일로 내보내서 내 로컬에 저장하는 과정입니다.

1. docker save : 도커 이미지를 .tar 파일로 내보내기
2. o : 출력 파일 경로 (바탕화면 docker 폴더)

- 이 tar 파일을 서버에 SCP로 전송해서 docker load로 불러올 수 있음

docker save -o /Users/leejonghoon/Desktop/docker/xxx-xxx-web.tar xxx-xxx-web

 
 

💡 4단계

- 모든 과정이 성공적으로 끝났을 때 완료 메시지 출력.

echo '완료: dkcns-homepage-web.tar 생성됨'

 
 

3. 명령어 실행

---

💡 명령어 실행

- 명령어가 실행이 되었고, 아래와 같이 파일이 생성이 되었습니다

 
 
 

4. 아래와 같이 tar 파일이 생성되었습니다.

---

 

5. [Termius] 연결된 리눅스 서버에 SFTP로 해당 파일을 옮겨둡니다

---

 

6. [Termius] tar 파일을 로드해 옵니다.

---

 

$ docker load -i xxx-xxx-web.tar

 
 

7. [Termius] Docker 컨테이너 배포 완료

---

💡 [Termius] Docker 컨테이너 배포 완료

- Docker 컨테이너를 재 실행하여 정상적으로 소스코드 반영이 완료되었습니다.

docker compose up -d

 
 
 
오늘도 감사합니다. 😀