planet/docs/technical/en/ops-runbook.md

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: ~/.local/state/planet/frontend.log
./planet.sh log -b   # backend:  ~/.local/state/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 directly exposes the frontend, backend, and AI Provider from the development machine: frontend 3000, backend 8000, and AI Provider 8010. Before startup, the script checks all three ports. If WSL/Linux cannot release a port and a Windows-side listener or stale portproxy rule owns it, the script requests Administrator PowerShell cleanup. When Planet runs in WSL, Windows can usually reach it through localhost; other LAN machines reaching the Windows LAN IP still need Windows Firewall allow rules.

Diagnose in this order:

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

If the services are running but the LAN IP still fails, first remove stale portproxy rules and confirm Windows Firewall allows the ports. The script checks this automatically and requests Administrator PowerShell when needed. 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
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8010

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
New-NetFirewallRule -DisplayName "WSL Planet 8010" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8010

LAN devices should use the Windows external ports, for example http://<Windows LAN IP>:3000/earth, http://<Windows LAN IP>:8000/health, and http://<Windows LAN IP>:8010/health.

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

Use bun run dev during development; Vite HMR refreshes the browser after source saves. bun run build only writes the dist artifact and does not refresh an already-open dev page.

To inspect the production bundle with automatic reload after successful builds:

bun run preview:auto

To watch sources and rebuild continuously without starting the preview server:

bun run build:watch

Backend dependencies are managed with uv:

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

Earth Boundary PMTiles Operations

1. In the console, open Operations and Configuration -> Earth Content -> Boundary Precision to save boundary source configuration. The local config is written to config/earth-boundary-sources.local.json; do not commit it.
2. Click "Build high precision boundaries", or switch the Earth toolbar settings gear to High Precision for the first build. The backend downloads the three source packages to data/earth-boundary-sources/, writes the source manifest, and invokes the PMTiles build script.
3. The builder requires tippecanoe and pmtiles on PATH. Missing tools return a clear API error and do not write data-source collection records.
4. A successful production build outputs frontend/public/earth/data/boundaries/earth-boundaries-china-pov-v1.pmtiles and its manifest.
5. After deployment, open Earth, enable "Border Lines", and inspect China's southeast coast, Taiwan, Hainan, the South China Sea, Zangnan, Kosovo, and Gaza for hover behavior and boundary policy.
6. If no high-precision manifest/PMTiles exists locally, Earth uses the bundled frontend/public/earth/data/countries-admin0.min.geojson fallback. If high-precision assets exist but tile requests fail, troubleshoot PMTiles range requests, manifest provider, Nginx .pmtiles static serving, and sha256 consistency.

Related Docs

• planet.sh Startup Mechanism
• System Service Control
• Docker + Compose + Buildx Upgrade
• Data Collectors