# chocoadmin Deployment

## 1. Environment Files

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

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

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:

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