chocoadmin, stage-chocoadmin 서비스를 Synology 도커 배포 환경 작업 내용을 문서에 반영

2026-07-05 13:06:50 +09:00
parent fcab1c83b7
commit c635d64141
3 changed files with 130 additions and 20 deletions
@@ -7,7 +7,7 @@ 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
+/volume1/docker/service/jinaju/chocoadmin/.env.stage
 ```

 Stage example:
@@ -20,19 +20,27 @@ AUTH_URL="https://stage-chocoadmin.jinaju.com"
 NEXTAUTH_URL="https://stage-chocoadmin.jinaju.com"
 ```

+Production file path:
+
+```bash
+/volume1/docker/service/jinaju/chocoadmin/.env.production
+```
+
 Production example:

 ```bash
-DATABASE_URL="mysql://CHCOCO_ADMIN_USER:PASSWORD@AWS_EC2_HOST:3306/chocomae"
+DATABASE_URL="mysql://CHCOCO_ADMIN_USER:PASSWORD@chocomae.jinaju.com:3306/chocomae"
 AUTH_SECRET="replace-with-production-secret"
 NEXTAUTH_SECRET="replace-with-production-secret"
-AUTH_URL="https://NAS_HOST_OR_DOMAIN"
-NEXTAUTH_URL="https://NAS_HOST_OR_DOMAIN"
+AUTH_URL="https://chocoadmin.jinaju.com"
+NEXTAUTH_URL="https://chocoadmin.jinaju.com"
 ```

-`AUTH_SECRET` and `NEXTAUTH_SECRET` should use the same strong random value per environment for Auth.js compatibility.
+`AUTH_SECRET` and `NEXTAUTH_SECRET` must be the same strong random value within each environment for Auth.js compatibility. Use different values between production and stage.

-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.
+`APP_ENV` (`production` / `stage`) is set by the `docker-compose*.yml` `environment` block — do **not** put it in the env file. It drives the session cookie name (`${APP_ENV}-chocoadmin.session-token`), which keeps production and stage cookies separate even if they share a browser.
+
+When the public URL uses HTTPS, both `AUTH_URL` and `NEXTAUTH_URL` must use the exact external HTTPS URL.

 Generate a secret on the NAS:

@@ -42,7 +50,7 @@ openssl rand -base64 32

 ## 2. Synology Stage Deployment

-The stage source is deployed by pulling Git on the NAS:
+Both production and stage share the same Git checkout at `/volume1/docker/service/jinaju/chocoadmin`. Pull from there:

 ```bash
 cd /volume1/docker/service/jinaju/stage-chocoadmin
@@ -60,12 +68,19 @@ docker network inspect proxy-network >/dev/null 2>&1 || docker network create pr
 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
 ```

+If a service was renamed in the compose file, add `--remove-orphans` once to remove the stale container.
+
+After redeployment, reload NPM to flush its upstream DNS cache:
+
+```bash
+docker exec npm nginx -s reload
+```
+
 `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:
@@ -97,7 +112,26 @@ docker compose ps
 docker compose logs -f chocoadmin
 ```

-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.
+After redeployment, reload NPM:
+
+```bash
+docker exec npm nginx -s reload
+```
+
+Nginx Proxy Manager settings:
+
+- Scheme: `http`
+- Forward Hostname / IP: `chocoadmin`
+- Forward Port: `3000`
+- Websockets Support: enabled
+- SSL: enabled
+- Force SSL: enabled
+
+Production URL:
+
+```text
+https://chocoadmin.jinaju.com
+```

 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`.

@@ -125,11 +159,11 @@ Before enabling approval/rejection operations against production DB:

 ## 6. Smoke Checks

-After stage container start:
+After each deployment:

 ```bash
-docker compose -f docker-compose.stage.yml ps
-docker compose -f docker-compose.stage.yml logs -f
+docker compose -f docker-compose.stage.yml ps      # stage
+docker compose ps                                   # production
 ```

 Verify these routes in the browser:
@@ -139,9 +173,51 @@ Verify these routes in the browser:
 - `/extension-requests`
 - `/upgrade-requests`

-If the browser reports too many redirects after login:
+## 7. Troubleshooting

-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.
+### ERR_TOO_MANY_REDIRECTS after login
+
+Middleware redirects to `/login`, login page redirects back to `/` — infinite loop. Work through this checklist in order:
+
+1. **Check `AUTH_URL` / `NEXTAUTH_URL`** — must exactly match the public HTTPS URL including scheme.
+2. **Check NPM scheme** — NPM must forward with scheme `http` (not `https`) to the container. The app detects HTTPS from `AUTH_URL`, not from the incoming request.
+3. **Check cookie name consistency** — `auth.ts` (`cookies.sessionToken.name`) and `proxy.ts` (`getToken({ cookieName })`) must both use the same `${APP_ENV}-chocoadmin.session-token` value. If `proxy.ts` uses the default name while `auth.ts` uses a custom one, middleware never finds the session.
+4. **Check for `__Secure-` prefix** — do not add it. Middleware runs in Node.js runtime and receives HTTP from Nginx. `__Secure-` cookies are silently rejected over HTTP.
+5. **Clear browser cookies** for the domain, then test in a private window.
+6. **Recreate the container** after changing `.env.*`.
+
+### Production and stage traffic mixing
+
+Symptom: logging into `chocoadmin.jinaju.com` shows the stage UI, or requests hit both containers interchangeably.
+
+Cause: Docker registers each `services:` key as a DNS alias in `proxy-network`. If stage and production share the same service name, NPM's upstream resolves to both containers via round-robin.
+
+Check the network:
+
+```bash
+docker network inspect proxy-network --format '{{range .Containers}}{{.Name}} {{.IPv4Address}}{{"\n"}}{{end}}'
+```
+
+Expected: `chocoadmin` and `stage-chocoadmin` appear with different IPs. If `chocoadmin` appears twice, a stale container is using that alias.
+
+Fix: ensure `docker-compose.stage.yml` has `services: stage-chocoadmin:` (not `chocoadmin`), redeploy stage once with `--remove-orphans` to clean up the stale container, then reload NPM.
+
+### Failed to find Server Action after redeployment
+
+Symptom: clicking a button (e.g. logout) returns a 404 or `Failed to find Server Action` error after deploying a new build.
+
+Cause: the action was defined as an inline `"use server"` closure. Closures get a new action ID on every build. The browser cached the old ID.
+
+Fix: force-reload the page (`Cmd+Shift+R` / `Ctrl+Shift+R`) to discard the cached page with stale action IDs. If the problem recurs after every deployment, the action must be extracted to a module-level named export in a separate `actions.ts` file.
+
+### Container starts but immediately exits
+
+```bash
+docker compose logs chocoadmin
+```
+
+Common causes:
+
+- Missing `DATABASE_URL` or malformed connection string.
+- `AUTH_SECRET` not set — NextAuth throws on startup.
+- Port already allocated — check if another service uses host port 3000. Both compose files use `expose` (not `ports`) for port 3000, so this should not happen unless the compose file was modified.