planet/docs/technical/en/quickstart.md

Quickstart

This guide is for developers or demo operators starting Planet for the first time. The goal is to get services running via the shortest path and know which URLs to open.

If you run into port conflicts, Windows / WSL LAN access, uv / bun, camera, or Docs permission issues, start with the FAQ.

Prerequisites

Recommended: run in a WSL / Linux shell.

You need:

• Docker / Docker Compose available
• uv and bun accessible in the current shell
• Repository cloned locally

On a new machine, run the bootstrap script first:

./scripts/bootstrap-dev.sh

This script checks and syncs common dependencies, and generates if missing:

• backend/.env
• aiprovider/.env
• frontend/.env.local

Personal AI Provider configuration can also live in ~/.zshrc. planet.sh reads simple export AI_...=... / AI_...=... lines and passes them to the AI Provider container. After changing model, key, or base URL, restart only AI Provider:

./planet.sh restart -a

Collector credentials such as AISStream and BarentsWatch can also start in ~/.zshrc for connectivity validation:

export AISSTREAM_API_KEY="..."
export BARENTSWATCH_CLIENT_ID="..."
export BARENTSWATCH_CLIENT_SECRET="..."

For actual collection, prefer saving credentials in Settings -> Collector Settings, especially for AISStream's long-lived WebSocket collector. That keeps connectivity validation, backend collection tasks, and Earth realtime vessel aggregation on the same configuration source.

1. Start Services

From the repository root:

./planet.sh start

After startup, the key URLs are:

Entry	Default URL	Purpose
Earth	http://localhost:3000/earth	Public 3D Earth visualization
Console	http://localhost:3000/admin	Admin console (login required)
Docs	http://localhost:3000/docs	Usage docs are public; developer and operations docs require Gatekeeper groups
AI	http://localhost:3000/ai	Model provider, tool, and testbench entry (login required)
Backend API Docs	http://localhost:8000/docs	FastAPI / OpenAPI interface docs

If the default ports are taken, specify custom ports:

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

If backend port 8000 is occupied by a Windows listener or an old portproxy rule, follow the FAQ troubleshooting order.

2. Create a Login User

The console requires login. For first-time use:

./planet.sh createuser

Follow the prompts to enter username, password, and role.

To read developer or operations docs, log in as super_admin and assign Gatekeeper groups from the Users page. Use docs_developer for development docs and docs_admin for service-control and operations docs.

3. Open Earth

Visit:

http://localhost:3000/earth

Earth is a public page — no login required.

Once in, verify:

• The globe renders correctly
• The right-side layer panel can toggle layers on/off
• Search can find cables, satellites, compute centers, BGP events
• Compute-center and BGP collector detail cards can collect and preview coordinate candidates; when regular sources have no candidate, the current default AI Provider runs one LLM factcheck fallback; the compute-center unresolved badge can open the queue and save candidates
• Mouse drag, wheel zoom, and zoom percent feedback work correctly
• Settings panel can switch rotate / cruise / motion mode, day/night mode, and satellite display style; Motion Debug Mode can show the local Browser Camera preview plus skeleton overlay

4. Open the Console

Visit:

http://localhost:3000/admin

The console manages data sources, collected data, situational observation, alerts, system logs, and configuration.

First-time inspection checklist:

• /datasources: data source directory and collection triggers; endpoint, headers, and credentials are configured under /settings collector settings
• /data: collected data
• /bgp: BGP situational view
• /ai: AI page for model providers, WebSearch-style tools, and the testbench
• /alerts/system: system alerts
• /settings: system configuration

5. Check Service Health

./planet.sh health

This shows container status and checks:

• Backend
• AI Provider
• Frontend

6. View Logs

Recent logs:

./planet.sh log

Follow a specific service:

./planet.sh log -f
./planet.sh log -b
./planet.sh log -a

Flags:

• -f: frontend logs
• -b: backend logs
• -a: AI Provider logs

7. Common Restarts

Frontend only:

./planet.sh restart -f

Backend only:

./planet.sh restart -b

AI Provider only:

./planet.sh restart -a

Database only:

./planet.sh restart -d

Full restart:

./planet.sh restart

8. LAN Access

To allow a Windows browser, phone, or another device on the same network:

./planet.sh start --allow-lan

This makes the frontend and backend listen on a LAN-accessible address.

Note: --allow-lan only makes Planet listen on 0.0.0.0; it does not automatically expose WSL services through the Windows LAN IP. A common pattern is:

• localhost:3000 / localhost:8000 works inside WSL
• localhost:3000 / localhost:8000 works on Windows
• http://<Windows LAN IP>:3000 fails from a phone or another computer

That usually means Windows still needs port forwarding or firewall rules.

If access fails, check from the shell running Planet:

curl http://localhost:3000
curl http://localhost:8000/health
ss -ltnp | grep -E ':3000|:8000'

If WSL is listening on 0.0.0.0:3000 and 0.0.0.0:8000 but the LAN IP still fails, configure Windows forwarding and firewall rules 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

9. Stop Services

./planet.sh stop

This shuts down the frontend, backend, AI Provider, PostgreSQL, and Redis.

Next Steps

• Full usage guide: Planet Manual
• Console structure: Admin Frontend Context
• Earth structure: Earth Frontend Context
• Backend collectors: Backend Collectors