포트 하나 안 열고 홈 서버 운영하기 (2) git push 로 배포하기

홈서버-따라하기 시리즈 2편. 서버에 접속해서 명령을 치지 않고, 저장소에 push 하면 몇 분 안에 배포되게 만든다. 도구는 Portainer 의 git 스택이다.

구성

• 앱마다 git 저장소 하나. 루트에 Dockerfile 과 docker-compose.yml.
• Portainer 에서 "Repository" 방식으로 스택을 만들고 저장소 주소를 준다.
• 자동 갱신(폴링)을 켜면 Portainer 가 주기적으로 새 커밋을 확인해 다시 배포한다. 나는 5분으로 두었다.

compose 파일 예시

services:
  app:
    build: .
    pull_policy: build
    restart: unless-stopped
    ports:
      - "127.0.0.1:8081:3000"
    environment:
      TZ: Asia/Seoul
      ENV_FILE: /config/.env
    volumes:
      - /home/user/app.env:/config/.env:ro
      - state:/state
    logging:
      driver: json-file
      options: { max-size: "10m", max-file: "3" }

volumes:
  state:

왜 이렇게 썼나

• build: . — 소스 폴더 마운트는 안 된다. Portainer 는 저장소를 자기 데이터 볼륨 안에 내려받는다. 그 경로는 호스트의 일반 폴더가 아니라서 ./src:/app 같은 바인드 마운트가 동작하지 않는다. 코드는 이미지 안에 넣어야 한다.
• pull_policy: build — 없으면 재배포가 헛돈다. 이미지가 이미 있으면 compose 는 다시 빌드하지 않는다. 이 한 줄이 빠지면 배포 기록은 성공인데 코드는 그대로다.
• 포트는 127.0.0.1 에만. 바깥 노출은 1편의 터널이 맡는다. 컨테이너 포트를 LAN 에 열 이유가 없다.
• 시크릿은 호스트의 고정 경로에 두고 읽기 전용으로 마운트. 저장소에는 .env.example 만 올린다. Portainer 스택은 호스트의 env_file 을 읽지 못하므로, 파일을 컨테이너에 마운트하고 앱이 시작할 때 그 경로를 읽게 했다.
• 상태는 이름 있는 볼륨에. 컨테이너를 다시 만들어도 남아야 하는 데이터만 넣는다.

Dockerfile 요령

FROM node:24-alpine
WORKDIR /app
COPY package.json server.js ./
COPY lib ./lib
COPY public ./public
ENV NODE_OPTIONS="--dns-result-order=ipv4first"
HEALTHCHECK CMD wget -qO- http://127.0.0.1:3000/healthz || exit 1
CMD ["node", "server.js"]

• COPY . . 대신 필요한 것만 적는다. git 스택의 체크아웃에는 저장소에서 지운 파일이 남아 있을 수 있어서, 통째로 복사하면 지운 파일이 이미지에 되살아난다.
• 내 서버의 컨테이너 네트워크에는 IPv6 경로가 없어서, 외부 API 호출이 IPv6 주소를 먼저 시도하다 지연되는 일이 있었다. IPv4 우선 옵션으로 해결했다.

비공개 저장소라면

Portainer 가 저장소를 읽을 수 있어야 한다. 읽기 전용 액세스 토큰을 발급해 스택에 등록한다. 시크릿이 전혀 없는 정적 사이트 같은 것은 저장소를 공개로 두면 인증 자체가 필요 없다.

배포가 됐는지 확인

배포 기록의 "성공"보다 결과물을 본다. 앱이 버전이나 빌드 시각을 /healthz 로 내보내게 해 두면 편하다.

curl -s http://127.0.0.1:8081/healthz

이 과정에서 밟은 함정 두 가지는 Portainer 라벨의 글에 자세히 적었다. 다음 편은 관리 화면을 로그인 뒤로 숨기는 방법이다. 시리즈 전체 목록은 여기.