# 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](/home/ray/dev/linkong/planet/docs/technical/en/faq.md).

## 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:

```bash
./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:

```bash
./planet.sh restart -a
```

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

```bash
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:

```bash
./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:

```bash
./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](/home/ray/dev/linkong/planet/docs/technical/en/faq.md) troubleshooting order.

## 2. Create a Login User

The console requires login. For first-time use:

```bash
./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:

```text
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:

```text
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

```bash
./planet.sh health
```

This shows container status and checks:

- Backend
- AI Provider
- Frontend

## 6. View Logs

Recent logs:

```bash
./planet.sh log
```

Follow a specific service:

```bash
./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:

```bash
./planet.sh restart -f
```

Backend only:

```bash
./planet.sh restart -b
```

AI Provider only:

```bash
./planet.sh restart -a
```

Database only:

```bash
./planet.sh restart -d
```

Full restart:

```bash
./planet.sh restart
```

## 8. LAN Access

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

```bash
./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:

```bash
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:

```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

```bash
./planet.sh stop
```

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

## Next Steps

- Full usage guide: [Planet Manual](/home/ray/dev/linkong/planet/docs/technical/en/manual.md)
- Console structure: [Admin Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
- Earth structure: [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
- Backend collectors: [Backend Collectors](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)