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

```bash
./scripts/bootstrap-dev.sh
```

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

- `backend/.env`
- `aiprovider/.env`
- `frontend/.env.local`

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

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

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

## 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
- Settings panel can switch cruise mode, day/night mode, satellite display style

## 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 configuration and collection status
- `/data`: collected data
- `/bgp`: BGP situational view
- `/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.

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

## 9. Stop Services

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

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

## Next Steps

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