7.4 KiB
Planet Ops Runbook
This runbook is for deployment, on-call, and maintenance engineers. End-user UI flows live in the Planet Manual; this document only covers shell, Docker, logs, environment variables, and troubleshooting.
First Startup
./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:
./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:
./planet.sh stop
Stops backend, AI Provider, frontend, PostgreSQL, Redis.
Per-module restart:
./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
./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:
./planet.sh log
Follow:
./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
./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
./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:
# 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:
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:
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:
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
To ignore ~/.zshrc entirely:
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:
./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
./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:
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:
source ~/.zshrc && bun run build
Backend dependencies are managed with uv:
uv sync
uv run pytest backend/tests/test_otp_service.py