chocoadmin/docs/deployment.md

chocoadmin Deployment

1. Production Environment

Create .env.production on the production host. Do not commit it.

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:3001"

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

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:3001/login.

Equivalent CLI command:

docker compose up -d --build

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.

To run with stage settings:

ENV_FILE=.env.stage docker compose up -d --build

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

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

5. Smoke Checks

After container start:

docker compose ps
docker compose logs -f chocoadmin

Verify these routes in the browser:

• /login
• /maestros
• /extension-requests
• /upgrade-requests