# CM Bot v2 – Portainer Setup (Gitea Registry)

Brief, copy/paste-ready steps to run the published images from `gitea.04080616.xyz` using Portainer.

## What gets deployed
- `cm-api` (port 3000), `cm-web` (port 8000 → host `CM_WEB_HOST_PORT`), `cm-telegram`, `cm-transfer`
- Container names prefixed with `CM_DEPLOY_NAME` (e.g. `rex-cm-telegram-bot`)
- Docker network: `${CM_DEPLOY_NAME}-network` (bridge)

## Environment configs

Per-deployment templates live in `envs/<name>/.env.example` (committed). Each operator copies the example to a sibling `.env` (gitignored — never committed) and fills in the real secrets:

```
envs/
├── dev/.env.example      # Local development tier — see "Local Development" below
├── rex/.env.example      # Rex deployment (port 8001)
└── siong/.env.example    # Siong deployment (port 8005)
```

For Portainer-hosted deployments (rex/siong):
```bash
cp envs/rex/.env.example envs/rex/.env
# Fill in DB_PASSWORD, CM_AGENT_*, CM_SECURITY_PIN, TELEGRAM_BOT_TOKEN, etc.
# Then load the variables into the Portainer stack environment.
```

For local development, see the dev tier flow:
```bash
cp envs/dev/.env.example .env
bash scripts/dev.sh up
```

## Key variables
| Variable | Description |
|---|---|
| `CM_DEPLOY_NAME` | Unique prefix for containers/network (e.g. `rex-cm`, `siong-cm`) |
| `CM_WEB_HOST_PORT` | Host port for web view (must be unique per deployment) |
| `TELEGRAM_BOT_TOKEN` | Your Telegram bot token |
| `DB_HOST` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` | Database connection |
| `CM_PREFIX_PATTERN` | Username prefix pattern |
| `CM_AGENT_ID` / `CM_AGENT_PASSWORD` / `CM_SECURITY_PIN` | Agent credentials |
| `CM_BOT_BASE_URL` | Bot API base URL |

## One-time: add the registry in Portainer
1) Portainer → **Registries** → **Add registry** → **Custom**.
2) Name: `gitea-prod` (any)
3) Registry URL: `gitea.04080616.xyz`
4) Username: your Gitea username; Password: the PAT. Save.

## Deploy the stack (fast path)
1) Portainer → **Stacks** → **Add stack** → **Web editor**.
2) Paste the contents of `docker-compose.yml` from this repo (not the override).
3) Load all variables from the appropriate `envs/<name>/.env` into the stack environment variables.
4) Click **Deploy the stack**. Portainer will pull `cm-<service>:<tag>` from `gitea.04080616.xyz/yiekheng` and start all four containers.

## Updating to a new image tag
1) Edit the stack → change `DOCKER_IMAGE_TAG` → **Update the stack**.
2) Portainer re-pulls and recreates the services with the new tag.

## Running multiple deployments on same host
Each deployment needs unique values for:
- `CM_DEPLOY_NAME` – avoids container/network name conflicts
- `CM_WEB_HOST_PORT` – avoids port conflicts

## Common issues
- **Pull denied**: PAT missing `read:package` or wrong username/PAT in the registry entry.
- **Port already allocated**: check `CM_WEB_HOST_PORT` is unique across deployments.
- **No port bindings applied**: ensure network driver stays `bridge` (not `host` or `macvlan`).