# oncall-v2 MySQL dev deployment/runbook

This runbook explains how to run oncall-v2 with MySQL in local dev and deploy the same setup to dev k8s with auth bypass.

## 1) What changed

Backend now supports both SQLite and MySQL via env vars:

- `ONCALL_DB_DIALECT=sqlite|mysql` (default sqlite)
- `ONCALL_DB_DSN=...` (required for mysql)
- `ONCALL_DB_PATH=...` (sqlite fallback)

Auth bypass in dev remains:

- `APP_ENV=dev`
- `AUTHING_ENABLED=false`
- `DEV_BYPASS_USER_EMAIL=admin@example.com`

## 2) Local MySQL quick start

### 2.1 Start MySQL container

If your 3306 is free:

```bash
docker run -d --name oncall-mysql \
  -e MYSQL_ROOT_PASSWORD=root \
  -e MYSQL_DATABASE=oncall_v2 \
  -e MYSQL_USER=oncall \
  -e MYSQL_PASSWORD=oncall \
  -p 3306:3306 \
  mysql:8.0
```

If 3306 is occupied, map host 3307:

```bash
docker run -d --name oncall-mysql \
  -e MYSQL_ROOT_PASSWORD=root \
  -e MYSQL_DATABASE=oncall_v2 \
  -e MYSQL_USER=oncall \
  -e MYSQL_PASSWORD=oncall \
  -p 3307:3306 \
  mysql:8.0
```

Check readiness:

```bash
docker logs --tail 50 oncall-mysql
```

Look for: `ready for connections`.

### 2.2 Configure backend env

Create `services/oncall-v2/.env.dev` from example and set:

```bash
APP_ENV=dev
AUTHING_ENABLED=false
DEV_BYPASS_USER_EMAIL=admin@example.com

ONCALL_DB_DIALECT=mysql
ONCALL_DB_DSN=oncall:oncall@tcp(127.0.0.1:3307)/oncall_v2?charset=utf8mb4&parseTime=True&loc=Local
# if you used host 3306, replace 3307 with 3306

ONCALL_LISTEN_ADDR=:18080
ONCALL_FRONTEND_URL=http://localhost:3000
```

### 2.3 Start backend

```bash
bash scripts/bootstrap/run-oncall-v2-backend-dev.sh
```

Expected in logs:

- `Connecting to database...` with `dialect=mysql`
- `Backend started` on `:18080`

### 2.4 Start frontend

```bash
bash scripts/bootstrap/run-oncall-v2-web-dev.sh
```

Open `http://localhost:3000`.

## 3) Dev k8s deployment (MySQL + bypass auth)

## 3.1 Current dev manifests

The following are already updated:

- `infra/kustomize/envs/dev/oncall-v2/configmap.yml`
  - `ONCALL_DB_DIALECT: "mysql"`
  - `AUTHING_ENABLED: "false"`
- `infra/kustomize/base/oncall-v2/deployment.yml`
  - reads `ONCALL_DB_DSN` from secret `oncall-v2-secret`
- `infra/kustomize/envs/dev/oncall-v2/oncall-v2-external-secret.yml`
  - maps remote secret property `ONCALL_DB_DSN`

## 3.2 Set secret in secret manager

Secret key path (existing convention):

- `aisupport-dev/oncall-v2`

Required property:

- `ONCALL_DB_DSN`

Example value:

```text
oncall:<password>@tcp(<mysql-host>:3306)/oncall_v2?charset=utf8mb4&parseTime=True&loc=UTC
```

(Optional existing properties remain supported: `FEISHU_APP_ID`, `FEISHU_APP_SECRET`.)

## 3.3 Deploy

### Via GitHub Actions (recommended)

Push branch to main changes touching oncall-v2 deployment paths, or run workflow manually:

- `.github/workflows/deploy-oncall-v2-dev.yml`

### Manual apply

```bash
cd infra/kustomize/envs/dev/oncall-v2
kubectl apply -k .
kubectl rollout status deployment/oncall-v2 -n aisupport-dev --timeout=180s
```

## 3.4 Verify in cluster

```bash
kubectl get pods -n aisupport-dev -l app=oncall-v2
kubectl logs -n aisupport-dev deploy/oncall-v2 --tail=100
```

Expect backend starts with auth bypass and MySQL connection.

## 4) Troubleshooting

### `missing ONCALL_DB_DSN for dialect=mysql`

- You set `ONCALL_DB_DIALECT=mysql` but did not provide `ONCALL_DB_DSN`.
- Fix env or ExternalSecret property.

### `unsupported ONCALL_DB_DIALECT=...`

- Use only `sqlite` or `mysql`.

### MySQL network/auth failures

- Validate hostname/port reachability from pod.
- Validate DB user grants.
- Check DSN flags: `charset=utf8mb4&parseTime=True&loc=UTC`.

### Local `go test`/`go run` toolchain mismatch

- Known local issue: Go tool mismatch can fail compile (`go1.23.x` vs `go1.25.x`).
- Fix local Go toolchain consistency, then rerun.

## 5) Security notes

- Do not place raw `ONCALL_DB_DSN` with password in ConfigMap.
- Keep DSN in secret manager + ExternalSecret only.
- In logs, DSN password is masked for mysql.