planet/docs/technical/en/manual.md

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.

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

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

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

AI Provider Environment and Builds

AI Provider runtime configuration can live in aiprovider/.env or in matching variables in ~/.zshrc. planet.sh reads simple export AI_...=... / AI_...=... lines and passes them to the container at startup.

Changing model, API key, or base URL does not rebuild the image. Restart only AI Provider to pick up runtime configuration changes:

./planet.sh restart -a

For complex shell expansion in ~/.zshrc, opt in explicitly:

PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a

To ignore ~/.zshrc during troubleshooting:

PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a

The AI Provider Docker build context is intentionally limited to the files required by the service, and uv sync uses a BuildKit cache mount so dependency downloads are reused after the first build.

Stop

./planet.sh stop

Stops:

• Backend
• AI Provider
• Frontend
• PostgreSQL
• Redis

Restart

Full restart:

./planet.sh restart

Per-module restart:

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

./planet.sh createuser

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

Health Check

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

./planet.sh log

Follow logs:

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

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

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
• AIS vessels
• 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
• AIS vessels
• 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

Legend

The lower-left legend follows the currently focused or enabled layer.

Current legend modes include:

• Cables
• Satellites
• Country borders
• Compute centers
• BGP
• AIS vessels

AIS vessel legend entries are grouped by vessel type: cargo, tanker, passenger, fishing, military, anchored/slow, and other. Triangle markers represent moving vessels; dots represent anchored or slow vessels.

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.

View Controls

Earth supports mouse, touchpad, and touchscreen interaction.

Common controls:

Action	Result
Left-button drag	Rotates the globe
One-finger drag	Rotates the globe on touch devices
Mouse wheel	Zooms the view in or out
Two-finger pinch	Zooms the view on touch devices
Zoom buttons	Adjust zoom in fixed steps
Click the zoom percent	Resets to the default zoom

When zooming, the top capsule briefly shows the current zoom level, for example Zoom 180%. This indicates view zoom only, not data loading progress. Loading status takes priority and will not be interrupted by zoom feedback.

Drag sensitivity adjusts automatically based on the current zoom. Around the default view it keeps the normal rotation feel; when zoomed in, dragging becomes progressively finer for inspecting a region, vessel, satellite, or BGP event; when zoomed out, dragging is slightly faster for global browsing.

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:

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

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

http://localhost:3000/admin

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

./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	View 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 collection sources and triggers collection. It is now a data source directory that lists built-in and custom sources in one table.

Common operations:

• View data source status
• Trigger collection
• View recent collection tasks
• Open the read-only detail drawer for endpoint, headers, runtime config, and built-in/custom source type

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

The data source name opens an information drawer only. Endpoint, credentials, headers, and custom source configuration are maintained under /settings collector settings.

When collection tasks are running, the progress area shows a clickable Collecting N pill. Clicking it opens a modal with each running task's phase, progress, and processed count.

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
• Collector settings
• External integrations and AI Provider configuration

Available configuration depends on the current user's role.

Collector Settings

/settings?tab=collector_credentials is currently displayed as Collector Settings. It manages connection settings for all collectors, not only credentials.

Use it to:

1. Select a collector from the dropdown.
2. Review tags such as Requires credentials, module, enabled state, and Unchecked / Available / Unavailable.
3. Click the plug icon next to the selector to run a health check.
4. Edit endpoint, request headers, timeout, and retry settings.
5. Save the collector settings.

Free collectors are checked by requesting their endpoint directly. Credentialed collectors use their credential provider. If endpoint or credential fingerprint changes after the last successful validation, the collector must be checked again.

The system treats a collector as connected when the current configuration has either collected data successfully or passed the manual connection check.

BarentsWatch AIS Credentials

BarentsWatch AIS is a credentialed built-in collector. Its credential card appears above the basic configuration card.

Configured fields:

• Client ID
• Client Secret
• Endpoint

If a secret is already configured, the input shows a masked preview. Keeping that preview unchanged preserves the stored secret; entering a new value replaces it.

BarentsWatch AIS credentials can be read from:

1. Collector settings saved in the console.
2. Backend environment variables:
   • BARENTSWATCH_CLIENT_ID
   • BARENTSWATCH_CLIENT_SECRET
   • historical spellings: BARRENTSWATCH_CLIENT_ID, BARRENTSWATCH_CLIENT_SECRET
3. matching export lines in ~/.zshrc.

If connection fails, the page opens the credential guide. The guide can be regenerated through AI Provider or reset to the default guide. The default guide points users to the official BarentsWatch tutorial and emphasizes selecting AIS - API, not the regular BarentsWatch - API.

System Logs

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

Common troubleshooting sequence:

./planet.sh health
./planet.sh log

Then open /logs for more structured runtime information.

Docs

Public documentation site:

http://localhost:3000/docs

Current public content comes from:

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:

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:

source ~/.zshrc && bun run build

Troubleshooting Order

When something goes wrong, follow this sequence:

1. Check service status:

./planet.sh health

2. Check recent logs:

./planet.sh log

3. Check per-module logs:

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

4. Restart only the affected module:

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

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

./planet.sh restart -d

6. If still unrecovered, do a full restart:

./planet.sh restart

Related Docs

• Quickstart
• Admin Frontend Context
• Earth Frontend Context
• Earth Layer Style Reference
• System Service Control
• Backend Collectors