Local PC 개발 및 테스트 - git 배포 - gitea webhook 단계별 설정

.env.example

@@ -1,17 +1,40 @@
-# timezone
+# ---------------------------------------------------------------------------
+# [Environment Configuration]
+# 이 파일을 복사하여 .env 파일을 생성하고, 환경에 맞게 주석을 해제/수정하여 사용하세요.
+# ---------------------------------------------------------------------------
+
+# [COMMON]
+APP_VERSION=dev
 TZ=Asia/Seoul
-
-COMPOSE_PROJECT_NAME=webpage
-
-# backend lotto collector sources
 LOTTO_ALL_URL=https://smok95.github.io/lotto/results/all.json
 LOTTO_LATEST_URL=https://smok95.github.io/lotto/results/latest.json
 
-# travel-proxy
+# [SECURITY]
-TRAVEL_ROOT=/data/travel
+WEBHOOK_SECRET=change_this_secret_in_prod
-TRAVEL_THUMB_ROOT=/data/thumbs
-TRAVEL_MEDIA_BASE=/media/travel
-TRAVEL_CACHE_TTL=300
 
-# CORS (travel-proxy)
+# [PATHS]
-CORS_ALLOW_ORIGINS=*
+# 1. 런타임 데이터 루트 (docker-compose.yml이 실행되는 위치)
+# NAS: /volume1/docker/webpage
+# Local: . (현재 프로젝트 루트)
+RUNTIME_PATH=.
+
+# 2. Git 저장소 루트
+# NAS: /volume1/workspace/web-page-backend
+# Local: .
+REPO_PATH=.
+
+# 3. Frontend 정적 파일 경로
+# NAS: /volume1/docker/webpage/frontend (업로드된 파일)
+# Local: ./frontend/dist (빌드된 결과물)
+FRONTEND_PATH=./frontend/dist
+
+# 4. 여행 사진 원본 경로
+# NAS: /volume1/web/images/webPage/travel
+# Local: ./mock_data/photos
+PHOTO_PATH=./mock_data/photos
+
+# [PERMISSIONS]
+# NAS: 1026:100
+# Local: 1000:1000 (Windows Docker Desktop의 경우 크게 중요하지 않음)
+PUID=1000
+PGID=1000

README.md

@@ -11,10 +11,10 @@ Frontend, Backend, Travel Proxy, Auto Deployer를 Docker Compose로 통합하여
 | --------------- | ------------------------------------- |
 | **NAS**         | Synology NAS                          |
 | **OS**          | Synology DSM                          |
-| **CPU**         | (예: Intel / AMD / ARM – 필요 시 기입) |
+| **CPU**         | Intel Celeron J4025 (2 Core, 2.0GHz)  |
-| **메모리**      | (예: 8GB / 16GB)                      |
+| **메모리**      | 18 GB                                 |
 | **Docker**      | Synology Container Manager            |
-| **Reverse Proxy** | Nginx (컨테이너)                      |
+| **Reverse Proxy** | Nginx (컨테이너)                     |
 | **Git Server**  | Gitea (self-hosted)                   |
 
 ---
@@ -80,11 +80,37 @@ Nginx (frontend container)
     -   장기 캐시(`assets/`)와 `index.html` 캐시 무효화 전략을 사용합니다.
     -   Backend / Travel API는 Nginx에서 Reverse Proxy로 연결됩니다.
 -   **배포 방식**:
+    1.  **로컬 개발**:
+        -   `.env` 파일 설정 후 `docker compose up`으로 전체 스택 실행 가능
+    2.  **운영 배포**:
+        -   Code를 Git에 Push
+        -   Webhook이 트리거되어 NAS가 자동 Pull & Deploy
+        -   (Frontend 빌드 산출물은 별도 업로드 혹은 CI 연동 필요)
+
+---
+
+## 🛠️ 개발 환경 설정 (Local Development)
+
+이 프로젝트는 **Windows/Mac 로컬 환경**과 **Synology NAS 운영 환경**을 모두 지원하도록 구성되었습니다.
+
+### 1. 환경 변수 설정
+`docker-compose.yml`은 환경 변수에 의존합니다.
+1. `.env.example` 파일을 복사하여 `.env` 파일을 생성하세요.
     ```bash
-    # 로컬 PC에서 실행
+    cp .env.example .env
-    npm run build
-    npm run deploy:nas
     ```
+2. `.env` 파일의 경로(`RUNTIME_PATH`, `PHOTO_PATH` 등)를 로컬 환경에 맞게 수정하세요.
+    - 기본값은 현재 디렉토리(`.`) 기준으로 설정되어 있어 바로 실행 가능합니다.
+
+### 2. 로컬 실행
+```bash
+docker compose up -d
+```
+- Frontend: http://localhost:8080
+- Backend API: http://localhost:18000
+- Travel API: http://localhost:19000
+
+---
 
 ---
 

docker-compose.yml

@@ -15,13 +15,13 @@ services:
       - LOTTO_ALL_URL=${LOTTO_ALL_URL:-https://smok95.github.io/lotto/results/all.json}
       - LOTTO_LATEST_URL=${LOTTO_LATEST_URL:-https://smok95.github.io/lotto/results/latest.json}
     volumes:
-      - /volume1/docker/webpage/data:/app/data
+      - ${RUNTIME_PATH}/data:/app/data
 
   travel-proxy:
     build: ./travel-proxy
     container_name: travel-proxy
     restart: unless-stopped
-    user: "1026:100"
+    user: "${PUID}:${PGID}"
     ports:
       - "19000:8000"	# 내부 확인용
     environment:
@@ -32,8 +32,8 @@ services:
       - TRAVEL_CACHE_TTL=${TRAVEL_CACHE_TTL:-300}
       - CORS_ALLOW_ORIGINS=${CORS_ALLOW_ORIGINS:-*}
     volumes:
-      - /volume1/web/images/webPage/travel:/data/travel:ro
+      - ${PHOTO_PATH}:/data/travel:ro
-      - /volume1/docker/webpage/travel-thumbs:/data/thumbs:rw
+      - ${RUNTIME_PATH}/travel-thumbs:/data/thumbs:rw
 
   frontend:
     image: nginx:alpine
@@ -42,10 +42,10 @@ services:
     ports:
       - "8080:80"
     volumes:
-      - /volume1/docker/webpage/frontend:/usr/share/nginx/html:ro
+      - ${FRONTEND_PATH}:/usr/share/nginx/html:ro
-      - /volume1/docker/webpage/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
+      - ${RUNTIME_PATH}/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
-      - /volume1/web/images/webPage/travel:/data/travel:ro
+      - ${PHOTO_PATH}:/data/travel:ro
-      - /volume1/docker/webpage/travel-thumbs:/data/thumbs:ro
+      - ${RUNTIME_PATH}/travel-thumbs:/data/thumbs:ro
     extra_hosts:
       - "host.docker.internal:host-gateway"
 
@@ -56,9 +56,9 @@ services:
     ports:
       - "19010:9000"   # 외부 노출 필요 없으면 내부만 (리버스프록시로 /webhook만 노출 추천)
     environment:
-      - WEBHOOK_SECRET=webpage_deploy_7f3A9cE2KpLwQ8N5VxRZbD4mH6TYeJ
+      - WEBHOOK_SECRET=${WEBHOOK_SECRET}
     volumes:
-      - /volume1/workspace/web-page-backend:/repo:rw
+      - ${REPO_PATH}:/repo:rw
-      - /volume1/docker/webpage:/runtime:rw
+      - ${RUNTIME_PATH}:/runtime:rw
-      - /volume1/docker/webpage/scripts:/scripts:ro
+      - ${RUNTIME_PATH}/scripts:/scripts:ro
       - /var/run/docker.sock:/var/run/docker.sock

scripts/healthcheck.sh

@@ -1,15 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-BASE="http://127.0.0.1"
-
-echo "backend health:"
-curl -fsS "${BASE}:18000/health" | sed 's/^/  /'
-
-echo "backend latest:"
-curl -fsS "${BASE}:18000/api/lotto/latest" | head -c 200; echo
-
-echo "travel regions:"
-curl -fsS "${BASE}:19000/api/travel/regions" | head -c 200; echo
-
-echo "OK"