stage-chocoadmin 내용을 deployment.md 문서에 반영

docs/deployment.md

@@ -1,43 +1,107 @@
 # chocoadmin Deployment
 
-## 1. Production Environment
+## 1. Environment Files
 
-Create `.env.production` on the production host. Do not commit it.
+Create environment files on the Synology NAS. Do not commit real `.env.*` files.
+
+Stage file path:
+
+```bash
+/volume1/docker/service/jinaju/stage-chocoadmin/.env.stage
+```
+
+Stage example:
+
+```bash
+DATABASE_URL="mysql://USER:PASSWORD@mariadb.jisangs.com:30001/chocomae"
+AUTH_SECRET="replace-with-stage-secret"
+NEXTAUTH_SECRET="replace-with-stage-secret"
+AUTH_URL="https://stage-chocoadmin.jinaju.com"
+NEXTAUTH_URL="https://stage-chocoadmin.jinaju.com"
+```
+
+Production example:
 
 ```bash
 DATABASE_URL="mysql://CHCOCO_ADMIN_USER:PASSWORD@AWS_EC2_HOST:3306/chocomae"
 AUTH_SECRET="replace-with-production-secret"
 NEXTAUTH_SECRET="replace-with-production-secret"
-NEXTAUTH_URL="http://NAS_HOST_OR_DOMAIN:3000"
+AUTH_URL="https://NAS_HOST_OR_DOMAIN"
+NEXTAUTH_URL="https://NAS_HOST_OR_DOMAIN"
 ```
 
-Create `.env.stage` on the stage host with the same keys and stage-specific values.
-
 `AUTH_SECRET` and `NEXTAUTH_SECRET` should use the same strong random value per environment for Auth.js compatibility.
 
-## 2. Synology Container Manager
+When the public URL uses HTTPS, both `AUTH_URL` and `NEXTAUTH_URL` must use the exact external HTTPS URL. Auth.js then writes secure cookies, and `proxy.ts` reads the secure session cookie.
 
-1. Copy the repository to the NAS.
+Generate a secret on the NAS:
-2. Place `.env.production` in the repository root on the NAS.
-3. In Container Manager, create a project from `docker-compose.yml`.
-4. Build and start the project.
-5. Open `http://NAS_HOST_OR_DOMAIN:3000/login`.
-
-Equivalent CLI command:
 
 ```bash
+openssl rand -base64 32
+```
+
+## 2. Synology Stage Deployment
+
+The stage source is deployed by pulling Git on the NAS:
+
+```bash
+cd /volume1/docker/service/jinaju/stage-chocoadmin
+git pull --ff-only
+```
+
+Stage uses `docker-compose.stage.yml`, the `stage-chocoadmin` container, and the external Docker network `proxy-network`.
+
+Verify or create the network:
+
+```bash
+docker network inspect proxy-network >/dev/null 2>&1 || docker network create proxy-network
+```
+
+Start or update stage:
+
+```bash
+docker compose -f docker-compose.stage.yml down
+docker compose -f docker-compose.stage.yml up -d --build
+docker compose -f docker-compose.stage.yml ps
+docker compose -f docker-compose.stage.yml logs -f
+```
+
+`docker-compose.stage.yml` exposes container port `3000` to `proxy-network` instead of binding host port `3000`, because host port `3000` may already be used by another service such as Gitea.
+
+Nginx Proxy Manager settings:
+
+- Scheme: `http`
+- Forward Hostname / IP: `stage-chocoadmin`
+- Forward Port: `3000`
+- Websockets Support: enabled
+- SSL: enabled
+- Force SSL: enabled
+
+Stage URL:
+
+```text
+https://stage-chocoadmin.jinaju.com
+```
+
+After changing `AUTH_URL`, `NEXTAUTH_URL`, or cookie-related settings, clear browser cookies for the stage domain or test in a private window.
+
+## 3. Production Deployment
+
+Production uses `docker-compose.yml` and reads `.env.production` by default:
+
+```bash
+cd /volume1/docker/service/jinaju/chocoadmin
+git pull --ff-only
 docker compose up -d --build
+docker compose ps
+docker compose logs -f chocoadmin
 ```
 
-The Docker build uses placeholder build-time environment variables only so Next.js can compile without committing secrets. Runtime values are read from `.env.production` by default.
+If production is also routed through Nginx Proxy Manager, attach it to `proxy-network` and use the container name and port `3000` as the upstream target.
 
-To run with stage settings:
+The Docker build uses placeholder build-time environment variables only so Next.js can compile without committing secrets. Runtime values are read from the compose `env_file`.
 
-```bash
+## 4. AWS EC2 Security Group
-ENV_FILE=.env.stage docker compose up -d --build
-```
-
-## 3. AWS EC2 Security Group
 
 Allow MariaDB only from the Synology NAS public IP.
 
@@ -49,7 +113,7 @@ Allow MariaDB only from the Synology NAS public IP.
 
 Do not open `3306` to `0.0.0.0/0`.
 
-## 4. Read-Only Rehearsal
+## 5. Read-Only Rehearsal
 
 Before enabling approval/rejection operations against production DB:
 
@@ -59,13 +123,13 @@ Before enabling approval/rejection operations against production DB:
 4. Verify login, maestro list, extension request list, and upgrade request list.
 5. Switch to the production write-capable chocoadmin DB account only after read screens work.
 
-## 5. Smoke Checks
+## 6. Smoke Checks
 
-After container start:
+After stage container start:
 
 ```bash
-docker compose ps
+docker compose -f docker-compose.stage.yml ps
-docker compose logs -f chocoadmin
+docker compose -f docker-compose.stage.yml logs -f
 ```
 
 Verify these routes in the browser:
@@ -74,3 +138,10 @@ Verify these routes in the browser:
 - `/maestros`
 - `/extension-requests`
 - `/upgrade-requests`
+
+If the browser reports too many redirects after login:
+
+1. Confirm `AUTH_URL` and `NEXTAUTH_URL` exactly match the public URL and scheme.
+2. Confirm Nginx Proxy Manager forwards to `stage-chocoadmin:3000` with scheme `http`.
+3. Recreate the container after changing `.env.stage`.
+4. Clear cookies for the stage domain.