우리집 비서 만들기 프로젝트 #10 - 서버편: 컨테이너와 배포 파일

1
# 허브 이미지. 빌드 컨텍스트는 저장소 루트다 (예제 클라이언트 scripts/ 를 테스트에 쓰기 때문).
2
#   docker build -f services/hub/Dockerfile --target runtime -t secretary .
3
FROM python:3.13-slim AS base
4
ENV PYTHONDONTWRITEBYTECODE=1 \
5
    PYTHONUNBUFFERED=1 \
6
    PIP_DISABLE_PIP_VERSION_CHECK=1
7
WORKDIR /app
8
COPY services/hub/requirements.txt .
9
RUN pip install --no-cache-dir -r requirements.txt
10

11
# 테스트 단계: 테스트가 하나라도 실패하면 이미지 빌드가 실패한다.
12
FROM base AS test
13
COPY services/hub/requirements-dev.txt .
14
RUN pip install --no-cache-dir -r requirements-dev.txt
15
COPY services/hub/app ./app
16
COPY services/hub/tests ./tests
17
COPY scripts ./scripts
18
RUN python -m pytest -q
19

20
# 실행 이미지: 앱 코드만 담는다.
21
FROM base AS runtime
22
ENV SECRETARY_DATA_DIR=/data
23
COPY services/hub/app ./app
24

25
# root가 아닌 전용 사용자로 실행한다. NAS의 data 폴더 소유자를 이 UID로 맞춘다.
26
RUN useradd --uid 10001 --no-create-home --shell /usr/sbin/nologin secretary \
27
    && mkdir -p /data && chown secretary /data
28
USER secretary
29

30
EXPOSE 8080
31
HEALTHCHECK --interval=15s --timeout=3s --start-period=10s --retries=3 \
32
    CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/healthz', timeout=2)"
33

34
# 워커는 1개. Nonce와 승인 대기열을 SQLite 하나로 관리하기 때문이다.
35
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8080", "--workers", "1", "--no-server-header"]

.git
.env
.env.*
!.env.example
data
__pycache__
*.pyc
.pytest_cache
.venv

1
# Jenkins가 배포할 때 쓰는 compose 파일. 직접 손으로 올릴 때도 같은 파일을 쓴다.
2
#
3
# 설정값은 --env-file 로 넘긴 .env 에서 읽는다 (Jenkins는 Credentials의 Secret file을 넘긴다).
4
# Jenkins 배포 시 셸 환경으로 넘어오는 값:
5
#   IMAGE_TAG                Git 커밋 해시 앞 12자리
6
#   SECRETARY_DATA_DIR_HOST  NAS의 데이터 폴더 절대 경로 (예: /volume1/docker/secretary/data)
7
#
8
# 네트워크는 세 개로 나눈다.
9
#   edge     cloudflared ↔ 허브. 바깥에서 들어오는 길은 이것 하나
10
#   modules  허브 ↔ 모듈. internal: true 라서 이 네트워크로는 인터넷에 나갈 수 없다
11
#   egress   인터넷이 필요한 모듈만 붙인다 (예: 메일 모듈 → AWS SES)
12
# 모듈은 edge에 없으므로 cloudflared(= 바깥)에서 모듈로 바로 갈 길이 없다.
13
#
14
# 새 모듈을 붙이려면: 아래에 서비스를 추가하고, 허브의 SECRETARY_MODULES / SECRETARY_MODULE_TOKENS 에 한 줄씩.
15
# 허브 코드는 고치지 않는다 (docs/module-contract.md).
16

17
services:
18
  cloudflared:
19
    image: cloudflare/cloudflared:latest
20
    container_name: cloudflared
21
    restart: unless-stopped
22
    command: tunnel --no-autoupdate run
23
    environment:
24
      - TUNNEL_TOKEN=${TUNNEL_TOKEN:?TUNNEL_TOKEN is required}
25
    networks: [edge]
26

27
  # 허브: 인증, 사용자, 권한, 승인, 감사 로그, 명령 전달
28
  secretary:
29
    image: secretary:${IMAGE_TAG:-latest}
30
    build:
31
      context: .
32
      dockerfile: services/hub/Dockerfile
33
      target: runtime
34
    container_name: secretary
35
    restart: unless-stopped
36
    # env_file로 .env 전체를 넘기지 않는다. 컨테이너마다 필요한 값만 골라 넘긴다.
37
    # 허브에는 AWS 키 같은 모듈의 비밀값이 들어가지 않는다.
38
    environment:
39
      - SECRETARY_DATA_DIR=/data
40
      - SECRETARY_MAX_USERS=${SECRETARY_MAX_USERS:-4}
41
      - SECRETARY_REQUIRE_CF_ACCESS=${SECRETARY_REQUIRE_CF_ACCESS:-true}
42
      - SECRETARY_CLOCK_SKEW_SECONDS=${SECRETARY_CLOCK_SKEW_SECONDS:-60}
43
      - SECRETARY_APPROVAL_TTL_SECONDS=${SECRETARY_APPROVAL_TTL_SECONDS:-300}
44
      # 모듈을 붙이면 여기에 한 줄씩 늘어난다 (12편)
45
      - SECRETARY_MODULES=
46
      - SECRETARY_MODULE_TOKENS=
47
    volumes:
48
      - ${SECRETARY_DATA_DIR_HOST:-./data}:/data
49
    # 바깥으로 여는 포트는 없다. cloudflared만 같은 네트워크 안에서 secretary:8080 으로 닿는다.
50
    read_only: true
51
    tmpfs:
52
      - /tmp
53
    cap_drop: [ALL]
54
    security_opt:
55
      - no-new-privileges:true
56
    networks: [edge, modules]
57

58
  # 모듈은 여기 아래에 붙인다 (12편의 secretary-mail 부터)
59

60
networks:
61
  edge:
62
    name: secretary_edge
63
  modules:
64
    name: secretary_modules
65
    internal: true
66
  egress:
67
    name: secretary_egress

// Secretary 빌드·배포 파이프라인
//
// Jenkins 컨테이너에는 docker가 없다. 빌드와 배포는 NAS가 직접 한다.
//   Gitea push → webhook → Jenkins
//     1) Upload  : 이 커밋의 소스를 SSH로 NAS에 올린다 (git archive)
//     2) Test    : NAS에서 테스트 이미지 빌드 + pytest
//     3) Deploy  : main 브랜치면 .env를 올리고 NAS에서 빌드·배포·헬스체크 (실패하면 직전 이미지로)
//
// 필요한 Jenkins Credentials:
//   nas-deploy-ssh  (SSH Username with private key) NAS의 배포 전용 계정 키
//   secretary-env   (Secret file) .env 파일 전체
//
// 설치마다 다른 값은 저장소에 적지 않고 Jenkins 환경 변수로 넣는다
// (Manage Jenkins → System → Global properties → Environment variables, 또는 작업 설정):
//   SECRETARY_NAS_HOST    필수. 예: deploy@192.168.0.10
//   SECRETARY_NAS_BASE    선택. 기본 /volume1/docker/secretary (src/, data/ 가 여기 생긴다)
//   SECRETARY_NAS_DOCKER  선택. 기본 docker. 배포 계정이 docker 그룹이 아니면 "sudo docker"

pipeline {
    agent any

    options {
        disableConcurrentBuilds()
        timeout(time: 20, unit: 'MINUTES')
        buildDiscarder(logRotator(numToKeepStr: '20'))
    }

    environment {
        NAS_HOST   = "${env.SECRETARY_NAS_HOST ?: ''}"
        NAS_BASE   = "${env.SECRETARY_NAS_BASE ?: '/volume1/docker/secretary'}"
        NAS_DOCKER = "${env.SECRETARY_NAS_DOCKER ?: 'docker'}"
    }

    stages {
        stage('Prepare') {
            steps {
                script {
                    if (!env.NAS_HOST?.trim()) {
                        error('Jenkins 환경 변수 SECRETARY_NAS_HOST 를 설정하세요. 예: deploy@192.168.0.10')
                    }
                    env.IMAGE_TAG = sh(script: 'git rev-parse --short=12 HEAD', returnStdout: true).trim()
                    currentBuild.description = "secretary:${env.IMAGE_TAG}"
                }
            }
        }

        stage('Upload') {
            steps {
                withCredentials([sshUserPrivateKey(credentialsId: 'nas-deploy-ssh', keyFileVariable: 'SSH_KEY')]) {
                    // 작은따옴표 셸 스크립트: Groovy가 아니라 셸이 변수를 해석하게 해서 비밀값이 새지 않게 한다.
                    sh '''
                        SSH="ssh -i $SSH_KEY -o BatchMode=yes -o StrictHostKeyChecking=yes"
                        git archive --format=tar HEAD \
                          | $SSH "$NAS_HOST" "rm -rf '$NAS_BASE/src' && mkdir -p '$NAS_BASE/src' && tar -x -C '$NAS_BASE/src'"
                    '''
                }
            }
        }

        stage('Test') {
            steps {
                withCredentials([sshUserPrivateKey(credentialsId: 'nas-deploy-ssh', keyFileVariable: 'SSH_KEY')]) {
                    sh '''
                        SSH="ssh -i $SSH_KEY -o BatchMode=yes -o StrictHostKeyChecking=yes"
                        $SSH "$NAS_HOST" "IMAGE_TAG='$IMAGE_TAG' DOCKER='$NAS_DOCKER' bash '$NAS_BASE/src/deploy/deploy.sh' test"
                    '''
                }
            }
        }

        stage('Deploy') {
            when {
                expression { env.GIT_BRANCH in ['main', 'origin/main'] }
            }
            steps {
                withCredentials([
                    sshUserPrivateKey(credentialsId: 'nas-deploy-ssh', keyFileVariable: 'SSH_KEY'),
                    file(credentialsId: 'secretary-env', variable: 'ENV_FILE'),
                ]) {
                    sh '''
                        SSH="ssh -i $SSH_KEY -o BatchMode=yes -o StrictHostKeyChecking=yes"
                        # .env는 표준 입력으로 보낸다. 명령줄이나 로그에 값이 남지 않는다. 배포 스크립트가 끝나면 지운다.
                        $SSH "$NAS_HOST" "umask 077 && cat > '$NAS_BASE/src/.env'" < "$ENV_FILE"
                        $SSH "$NAS_HOST" "IMAGE_TAG='$IMAGE_TAG' DOCKER='$NAS_DOCKER' SECRETARY_DATA_DIR_HOST='$NAS_BASE/data' bash '$NAS_BASE/src/deploy/deploy.sh' deploy"
                    '''
                }
            }
        }
    }

    post {
        success {
            echo "완료: secretary:${env.IMAGE_TAG}"
        }
    }
}