From 005c0261c2fb5ce5a17bfe4f23456e541c65db28 Mon Sep 17 00:00:00 2001
From: gahusb <bgg8988@gmail.com>
Date: Sun, 25 Jan 2026 19:00:22 +0900
Subject: [PATCH] =?UTF-8?q?Local=20PC=20=EA=B0=9C=EB=B0=9C=20=EB=B0=8F=20?=
 =?UTF-8?q?=ED=85=8C=EC=8A=A4=ED=8A=B8=20-=20git=20=EB=B0=B0=ED=8F=AC=20-?=
 =?UTF-8?q?=20gitea=20webhook=20=EB=8B=A8=EA=B3=84=EB=B3=84=20=EC=84=A4?=
 =?UTF-8?q?=EC=A0=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .env.example           | 47 +++++++++++++++++++++++++++++++-----------
 README.md              | 38 ++++++++++++++++++++++++++++------
 docker-compose.yml     | 24 ++++++++++-----------
 scripts/healthcheck.sh | 15 --------------
 4 files changed, 79 insertions(+), 45 deletions(-)

diff --git a/.env.example b/.env.example
index 102b070..ded49d0 100644
--- a/.env.example
+++ b/.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
-TRAVEL_ROOT=/data/travel
-TRAVEL_THUMB_ROOT=/data/thumbs
-TRAVEL_MEDIA_BASE=/media/travel
-TRAVEL_CACHE_TTL=300
+# [SECURITY]
+WEBHOOK_SECRET=change_this_secret_in_prod
 
-# CORS (travel-proxy)
-CORS_ALLOW_ORIGINS=*
+# [PATHS]
+# 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
diff --git a/README.md b/README.md
index 6776acb..6813db9 100644
--- a/README.md
+++ b/README.md
@@ -11,10 +11,10 @@ Frontend, Backend, Travel Proxy, Auto Deployer를 Docker Compose로 통합하여
 | --------------- | ------------------------------------- |
 | **NAS**         | Synology NAS                          |
 | **OS**          | Synology DSM                          |
-| **CPU**         | (예: Intel / AMD / ARM – 필요 시 기입) |
-| **메모리**      | (예: 8GB / 16GB)                      |
+| **CPU**         | Intel Celeron J4025 (2 Core, 2.0GHz)  |
+| **메모리**      | 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에서 실행
-    npm run build
-    npm run deploy:nas
+    cp .env.example .env
     ```
+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
+
+---
 
 ---
 
diff --git a/docker-compose.yml b/docker-compose.yml
index 6391834..8a551c0 100644
--- a/docker-compose.yml
+++ b/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
-      - /volume1/docker/webpage/travel-thumbs:/data/thumbs:rw
+      - ${PHOTO_PATH}:/data/travel:ro
+      - ${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
-      - /volume1/docker/webpage/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
-      - /volume1/web/images/webPage/travel:/data/travel:ro
-      - /volume1/docker/webpage/travel-thumbs:/data/thumbs:ro
+      - ${FRONTEND_PATH}:/usr/share/nginx/html:ro
+      - ${RUNTIME_PATH}/nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
+      - ${PHOTO_PATH}:/data/travel: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
-      - /volume1/docker/webpage:/runtime:rw
-      - /volume1/docker/webpage/scripts:/scripts:ro
+      - ${REPO_PATH}:/repo:rw
+      - ${RUNTIME_PATH}:/runtime:rw
+      - ${RUNTIME_PATH}/scripts:/scripts:ro
       - /var/run/docker.sock:/var/run/docker.sock
diff --git a/scripts/healthcheck.sh b/scripts/healthcheck.sh
index 993fcda..e69de29 100644
--- a/scripts/healthcheck.sh
+++ b/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"