From 0481ffb1a85b235f1a1963d77d6f6da8c3122585 Mon Sep 17 00:00:00 2001 From: jisangs Date: Thu, 11 Jun 2026 14:55:37 +0900 Subject: [PATCH] =?UTF-8?q?stage-chocoadmin=20=EB=82=B4=EC=9A=A9=EC=9D=84?= =?UTF-8?q?=20deployment.md=20=EB=AC=B8=EC=84=9C=EC=97=90=20=EB=B0=98?= =?UTF-8?q?=EC=98=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/deployment.md | 121 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 96 insertions(+), 25 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index 30ca84c..2b89cd2 100644 --- a/docs/deployment.md +++ b/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. -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: +Generate a secret on the NAS: ```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 -ENV_FILE=.env.stage docker compose up -d --build -``` - -## 3. AWS EC2 Security Group +## 4. 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 logs -f chocoadmin +docker compose -f docker-compose.stage.yml ps +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.