# Planet Ops Runbook

This runbook is for deployment, on-call, and maintenance engineers. End-user UI flows live in the [Planet Manual](/home/ray/dev/linkong/planet/docs/technical/en/manual.md); this document only covers shell, Docker, logs, environment variables, and troubleshooting.

## First Startup

```bash
./planet.sh start
```

Default behavior:

- Starts PostgreSQL and Redis
- Starts AI Provider
- Starts the backend API
- Starts the frontend Vite dev server
- Prints Earth, console, Playground, and backend API doc URLs

First startup seeds two default accounts (see `DEFAULT_LOGIN_USERS` in `backend/app/db/session.py`):

| Username | Password | Role |
| --- | --- | --- |
| `admin` | `admin123` | `super_admin` |
| `linkong` | `12345678` | `super_admin` |

Both seed accounts are created with `email_verified = TRUE` and can log into the console immediately. Any other account must either go through the public registration flow described in the Manual, or be created via `./planet.sh createuser`.

Specify custom ports:

```bash
./planet.sh start -b 8001 -f 3001 -a 8101
```

| Flag | Meaning |
| --- | --- |
| `-b <port>` | Backend port |
| `-f <port>` | Frontend port |
| `-a <port>` | AI Provider port |
| `--allow-lan` | Enable LAN access |
| `--verbose` | Show extra command output |

## Stop and Per-Module Restart

Stop everything:

```bash
./planet.sh stop
```

Stops backend, AI Provider, frontend, PostgreSQL, Redis.

Per-module restart:

```bash
./planet.sh restart        # full
./planet.sh restart -b     # backend
./planet.sh restart -f     # frontend
./planet.sh restart -a     # AI Provider
./planet.sh restart -d     # database
```

Per-module restart is preferred during development to avoid interrupting unrelated services.

## Health Check

```bash
./planet.sh health
```

Checks:

- `planet_*` container status
- Backend `/health`
- AI Provider `/health`
- Frontend reachability

If anything reports offline, check the corresponding logs first.

## Logs

Recent logs:

```bash
./planet.sh log
```

Follow:

```bash
./planet.sh log -f   # frontend: /tmp/planet_frontend.log
./planet.sh log -b   # backend:  /tmp/planet_backend.log
./planet.sh log -a   # AI Provider: planet_aiprovider container logs
```

## CLI User Creation

```bash
./planet.sh createuser
```

Interactively prompts for username, password, and role; writes the user with `email_verified = TRUE` directly.

Use when:

- SMTP is not yet configured but an admin account is needed now
- Pre-seeding internal test accounts
- Public registration is unavailable for any reason and a fallback is required

For ordinary user onboarding, configure SMTP at `/settings -> SMTP Email` first and let users self-register at `/register`.

## LAN / WSL Access

```bash
./planet.sh start --allow-lan
```

Useful for:

- Starting in WSL, accessing from Windows browser
- Demoing Earth from a phone or tablet
- Other LAN machines reaching the same dev instance

`--allow-lan` only makes the frontend and backend listen on `0.0.0.0`. When Planet runs in WSL, Windows can usually reach it through `localhost`, but other LAN machines hitting `http://<Windows LAN IP>:3000` still need Windows port forwarding and firewall rules.

Diagnose in this order:

```bash
# From the shell running Planet
curl http://localhost:3000
curl http://localhost:8000/health
ss -ltnp | grep -E ':3000|:8000'
```

If WSL shows `0.0.0.0:3000` / `0.0.0.0:8000` but the LAN IP still fails, configure Windows from an elevated PowerShell:

```powershell
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000

New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000
```

## AI Provider Environment and Builds

AI Provider runtime configuration lives in two places:

| Location | Best for | Notes |
| --- | --- | --- |
| `aiprovider/.env` | Team-shared local defaults | Read by Docker Compose as `env_file` |
| `~/.zshrc` | Personal provider/model/key/proxy | `planet.sh` reads common `AI_*`, `SERVICE_*`, `PYTHON_IMAGE`, `UV_IMAGE` lines |

Recommended form:

```bash
export AI_PROVIDER=minimax
export AI_PROVIDER_API=anthropic-messages
export AI_BASE_URL=https://api.example.com/anthropic
export AI_API_KEY=sk-change-me
export AI_MODEL=MiniMax-M2.7
export AI_PROVIDER_SERVICE_TOKEN=change_me
```

By default `planet.sh` only statically parses simple `export KEY=value` lines from `~/.zshrc`. When complex shell expansion is required, opt in explicitly:

```bash
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
```

To ignore `~/.zshrc` entirely:

```bash
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
```

The AI Provider image only rebuilds when code, Dockerfile, Compose config, or Python dependencies change. After changing keys or base URL, restarting the container is enough:

```bash
./planet.sh restart -a
```

Diagnose slow builds:

| Symptom | Common cause | Fix |
| --- | --- | --- |
| Large `transferring context` | build context includes unrelated frontend / data files | `.dockerignore` ships only required files |
| `uv sync` is slow | first build or cold cache | wait for the first build; later runs reuse BuildKit cache |
| Old keys still in effect after edit | container not restarted | `./planet.sh restart -a` |

## SMTP Email (Required for Public Registration)

Public registration and email verification depend on SMTP. Administrators configure host, port, username, password, from-address, and TLS mode at `/settings -> SMTP Email` in the console, then use the "Send Test Email" button to verify. Settings are persisted in the `system_settings.smtp` row.

When SMTP is unset, `POST /api/v1/auth/register` returns `503 EMAIL_PROVIDER_NOT_CONFIGURED` and the frontend surfaces a clear error. The operational fallback is `./planet.sh createuser`.

One-time codes are stored in Redis under `otp:{purpose}:{email}` with a 600-second TTL. The key is invalidated after 5 invalid attempts. Resend cooldown is 60 seconds, enforced via `otp_rate:{purpose}:{email}`.

## Troubleshooting Order

```bash
./planet.sh health        # 1. service state
./planet.sh log           # 2. recent logs
./planet.sh log -f        # 3. per-module logs
./planet.sh log -b
./planet.sh log -a
./planet.sh restart -f    # 4. restart only the affected module
./planet.sh restart -b
./planet.sh restart -a
./planet.sh restart -d    # 5. database / cache issues
./planet.sh restart       # 6. full restart if still broken
```

## Development Command Conventions

Frontend must use Bun:

```bash
cd frontend
bun install
bun run dev
bun run build
```

Do not use `npm run ...`. In the WSL / Windows mixed environment Bun avoids Node/npm path inconsistencies.

Validate the frontend build:

```bash
source ~/.zshrc && bun run build
```

Backend dependencies are managed with uv:

```bash
uv sync
uv run pytest backend/tests/test_otp_service.py
```

## Related Docs

- [planet.sh Startup Mechanism](/home/ray/dev/linkong/planet/docs/technical/en/ops-planet-sh-startup.md)
- [System Service Control](/home/ray/dev/linkong/planet/docs/technical/en/backend-system-service-control.md)
- [Docker + Compose + Buildx Upgrade](/home/ray/dev/linkong/planet/docs/technical/en/ops-docker-compose-buildx-upgrade.md)
- [Data Collectors](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)