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.

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

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	Public developer docs and manual
AI Playground	http://localhost:3000/playground	AI debugging (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

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.

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
• Mouse drag, wheel zoom, and zoom percent feedback work correctly
• Settings panel can switch cruise mode, day/night mode, satellite display style

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
• /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.

If access fails, check from the shell running Planet:

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

9. Stop Services

./planet.sh stop

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

Next Steps

• Full usage guide: manual.md
• Console structure: frontend-admin-frontend-context.md
• Earth structure: earth-frontend-context.md
• Backend collectors: backend-collectors.md