7.8 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 reaching the Windows LAN IP 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 services are running but the LAN IP still fails, let ./planet.sh start --allow-lan launch temporary Windows relays. The relays keep Windows exposed on 3000 / 8000 and exit automatically when the WSL target port goes away. The script checks stale portproxy rules and requests Administrator PowerShell to delete them, then checks Windows Firewall and triggers a UAC Administrator PowerShell request when inbound allow rules are missing. Manual fallback commands:
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=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
LAN devices should use the Windows external port, for example http://<Windows LAN IP>:3000/earth.
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