# Planet Manual

This manual is for daily use, demos, development integration, and local operations. It covers four core entry points:

- `planet.sh`: local start, stop, restart, health check, and log access
- Earth: public 3D situational awareness page
- Console: admin backend (login required)
- Docs: public developer documentation and manual

For the shortest path to getting started, see [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md).

## Entry Overview

After a default startup, the common URLs are:

| Name | URL | Login Required | Description |
| --- | --- | --- | --- |
| Earth | `http://localhost:3000/earth` | No | 3D globe, layers, BGP, satellites, cables, news situational awareness |
| Docs | `http://localhost:3000/docs` | No | Developer docs, technical reference, usage manual |
| Console | `http://localhost:3000/admin` | Yes | Data, config, alerts, logs, and situational observation |
| AI Playground | `http://localhost:3000/playground` | Yes | AI Provider status and debugging |
| Backend API Docs | `http://localhost:8000/docs` | Depends on endpoint | FastAPI / OpenAPI documentation |

## planet.sh

`planet.sh` is the main control script for local development and demos. Use it to manage services rather than manually starting frontend, backend, database, and AI Provider separately.

### Start

```bash
./planet.sh start
```

Default behavior:

- Starts PostgreSQL and Redis
- Starts AI Provider
- Starts the backend API
- Starts the frontend Vite dev server
- Outputs Earth, console, Playground, and backend API doc URLs

Specify custom ports:

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

Parameters:

| Flag | Meaning |
| --- | --- |
| `-b <port>` | Backend port |
| `-f <port>` | Frontend port |
| `-a <port>` | AI Provider port |
| `--allow-lan` | Enable LAN access |
| `--verbose` | Show more command output during execution |

### Stop

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

Stops:

- Backend
- AI Provider
- Frontend
- PostgreSQL
- Redis

### Restart

Full restart:

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

Per-module restart:

```bash
./planet.sh restart -b
./planet.sh restart -f
./planet.sh restart -a
./planet.sh restart -d
```

| Flag | Effect |
| --- | --- |
| `-b` | Backend only |
| `-f` | Frontend only |
| `-a` | AI Provider only |
| `-d` | Database only |

Per-module restarts are preferred during development — they avoid interrupting unrelated services.

### Create User

```bash
./planet.sh createuser
```

Used to create a console login account before first use. The script interactively prompts for username, password, and role.

### Health Check

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

Checks:

- `planet_*` container status
- Backend `/health`
- AI Provider `/health`
- Frontend reachability

If something shows offline, check the corresponding logs first.

### Logs

Recent logs:

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

Follow logs:

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

| Flag | Log source |
| --- | --- |
| `-f` / `--frontend` | `/tmp/planet_frontend.log` |
| `-b` / `--backend` | `/tmp/planet_backend.log` |
| `-a` / `--ai-provider` | `planet_aiprovider` container logs |

### LAN Access

```bash
./planet.sh start --allow-lan
```

Useful for:

- Starting in WSL, accessing from Windows browser
- Demos on phone or tablet
- Another machine on the same LAN accessing the same dev instance

After starting, check your firewall and WSL network forwarding if access fails.

## Earth

Earth is the public 3D situational awareness page, accessed at:

```text
http://localhost:3000/earth
```

It is a standalone frontend. The actual page lives at:

- `frontend/public/earth/index.html`
- `frontend/public/earth/js/`
- `frontend/public/earth/css/`

The React route `/earth` simply hosts it in an iframe.

### Main Uses

Earth is used to observe in a single globe view:

- BGP events, anomalies, and situational posture
- Satellites and orbital trails
- Submarine cables and landing points
- Compute centers
- Country borders, grid lines, HD texture, cloud layer, terrain
- Live news streams and situational news
- Search and focused object details

### Layer Control

The right-side layer panel toggles visualization layers on or off.

Common layers include:

- Grid lines
- Country borders
- HD texture
- Atmospheric cloud layer
- Submarine cables
- Compute centers
- BGP observation
- Satellites
- Orbital trails
- Terrain

Some layers have dependencies:

- Terrain requires HD texture
- Trails require Satellites
- When HD texture is off, the globe shows the base map and edge glow effect

### Search

Earth search finds current globe objects, such as:

- Submarine cables
- Landing points
- Satellites
- Compute centers
- BGP events
- BGP collectors

Search results can be used to quickly locate objects and open their details.

### Settings

The settings panel contains:

- Rotation mode / cruise mode
- Cruise modules: BGP, News
- Satellite display style: self-glow, real ground footprint
- Day/night mode
- Panel visibility toggles
- Globe default size
- Terrain opacity
- Reset settings

These settings are stored in browser local storage. They revert to defaults if you switch browsers or clear site data.

### Cruise Mode

Cruise mode makes Earth automatically cycle through focus targets.

Current cruise modules:

- BGP
- News

Suitable for demos, monitoring displays, or unattended presentations.

### Mobile

Earth has a mobile drawer layout. On small screens:

- Layer controls open in a mobile drawer
- Search, settings, and details use mobile panels
- Main interactions remain centered on globe object clicks, search, and layer toggles

### Common Issues

#### Earth Won't Open

Check whether the frontend is online:

```bash
./planet.sh health
./planet.sh log -f
```

If the frontend port is not `3000`, use the actual port shown at startup.

#### Layer Has No Data

Check the backend and data sources:

```bash
./planet.sh health
./planet.sh log -b
```

Then open the console and check:

- `/datasources`
- `/data`
- `/bgp`

#### Satellites, BGP, or Cables Load Slowly

These layers may depend on backend APIs, external data sources, or first-run collection tasks. Wait for startup tasks to finish before checking logs and console data source status.

## Console

Console entry point:

```text
http://localhost:3000/admin
```

The console requires login. Create a user first if this is your first time:

```bash
./planet.sh createuser
```

### Page Structure

The console uses React + Ant Design, with a left-side menu organized by work domain.

Common pages:

| Page | Route | Purpose |
| --- | --- | --- |
| Dashboard | `/admin` | System overview |
| Earth | `/earth` | Opens the public Earth page |
| Data Sources | `/datasources` | Manage data sources and trigger collection |
| Collected Data | `/data` | View collected data |
| BGP Observation | `/bgp` | BGP situational data |
| System Alerts | `/alerts/system` | System-level alerts |
| BGP Alerts | `/alerts/bgp` | BGP-related alerts |
| Situational Alerts | `/alerts/situational` | Situational assessment alerts |
| AI Playground | `/playground` | AI Provider debugging |
| System Logs | `/logs` | View system logs (typically super admin only) |
| Users | `/users` | User management |
| Settings | `/settings` | System config and TV live stream sources |

### Data Sources

`/datasources` shows and manages collection sources.

Common operations:

- View data source status
- Trigger collection
- View recent collection tasks
- Adjust configuration

If a category of objects is missing on Earth, start here to confirm the data source is available.

### Collected Data

`/data` shows the collected data table.

Useful for diagnosing:

- Whether data has entered the system
- Whether data update times match expectations
- Whether a data source produced valid records

### BGP Observation

`/bgp` is the BGP-focused page.

It complements the BGP layer on Earth:

- Earth emphasizes spatial posture and visual focus
- The console BGP page emphasizes lists, status, details, and assessment

### Alerts

Alert entry points:

- `/alerts/system`
- `/alerts/bgp`
- `/alerts/situational`

Used to view system, network, and situational alerts.

### System Settings

`/settings` manages system-level configuration.

Current common uses:

- System settings
- TV live stream source configuration
- Data source configuration entry points

Available configuration depends on the current user's role.

### System Logs

`/logs` views system logs. If the menu item is not visible, the current user likely lacks the required role.

Common troubleshooting sequence:

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

Then open `/logs` for more structured runtime information.

## Docs

Public documentation site:

```text
http://localhost:3000/docs
```

Current public content comes from:

```text
docs/technical/zh/   (Chinese)
docs/technical/en/   (English)
```

Docs supports:

- Category navigation
- Markdown rendering
- Tables and code blocks
- In-document table of contents
- Local search
- Internal links between technical documents

When adding a new technical document, check:

- Does it have a clear top-level heading
- Does it need to be added to the `/docs` manual category and ordering
- Does it contain information that should not be publicly displayed

## Development Command Conventions

Frontend commands must use Bun:

```bash
cd frontend
bun install
bun run dev
bun run build
```

Do not use `npm run ...`. The project uses Bun in WSL / Windows mixed environments to avoid Node/npm path compatibility issues.

Verify the frontend build:

```bash
source ~/.zshrc && bun run build
```

## Troubleshooting Order

When something goes wrong, follow this sequence:

1. Check service status:

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

2. Check recent logs:

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

3. Check per-module logs:

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

4. Restart only the affected module:

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

5. If database or cache is abnormal, restart the database:

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

6. If still unrecovered, do a full restart:

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

## Related Docs

- [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md)
- [frontend-admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
- [earth-layer-style-reference.md](/home/ray/dev/linkong/planet/docs/technical/en/earth-layer-style-reference.md)
- [backend-system-service-control.md](/home/ray/dev/linkong/planet/docs/technical/en/backend-system-service-control.md)
- [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)