chocoadmin/docs/deployment.md

chocoadmin Deployment

1. Environment Files

Create environment files on the Synology NAS. Do not commit real .env.* files.

Stage file path:

/volume1/docker/service/jinaju/stage-chocoadmin/.env.stage

Stage example:

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:

DATABASE_URL="mysql://CHCOCO_ADMIN_USER:PASSWORD@AWS_EC2_HOST: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_SECRET and NEXTAUTH_SECRET should use the same strong random value per environment for Auth.js compatibility.

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.

Generate a secret on the NAS:

openssl rand -base64 32

2. Synology Stage Deployment

The stage source is deployed by pulling Git on the NAS:

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:

docker network inspect proxy-network >/dev/null 2>&1 || docker network create proxy-network

Start or update stage:

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:

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:

cd /volume1/docker/service/jinaju/chocoadmin
git pull --ff-only
docker compose up -d --build
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.

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.

4. AWS EC2 Security Group

Allow MariaDB only from the Synology NAS public IP.

• Type: MYSQL/Aurora
• Protocol: TCP
• Port: 3306
• Source: NAS_PUBLIC_IP/32
• Description: chocoadmin Synology NAS

Do not open 3306 to 0.0.0.0/0.

5. Read-Only Rehearsal

Before enabling approval/rejection operations against production DB:

1. Create or use a DB account with read-only permissions.
2. Set DATABASE_URL in .env.production to that read-only account.
3. Start the container.
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.

6. Smoke Checks

After stage container start:

docker compose -f docker-compose.stage.yml ps
docker compose -f docker-compose.stage.yml logs -f

Verify these routes in the browser:

• /login
• /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.