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: backend Gatekeeper-controlled documentation; basic usage docs are public, while developer and operations docs require permission groups

For the shortest path to getting started, see Quickstart. For common troubleshooting, see the FAQ.

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	Partly	Usage docs are public; developer, backend, and operations docs require Gatekeeper groups
FAQ	http://localhost:3000/docs/faq	No	Windows / WSL, ports, dependencies, motion capture, credentials, and permission troubleshooting
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

--allow-lan only makes the frontend and backend listen on 0.0.0.0. When Planet runs in WSL, Windows can usually reach it through localhost, but access from a phone or another computer through http://<Windows LAN IP>:3000 still depends on Windows port forwarding and firewall rules.

Use this order to diagnose:

# From WSL or the shell running Planet
curl http://localhost:3000
curl http://localhost:8000/health
ss -ltnp | grep -E ':3000|:8000'

If this shows 0.0.0.0:3000 and 0.0.0.0:8000, but the LAN IP still fails, configure Windows from an elevated 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

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
• Border lines, 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
• Border lines
• 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
• Border lines
• 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.

Location Candidate Collection

Compute-center and BGP collector detail cards can collect candidate coordinates automatically. After clicking an object, use 自动采集坐标候选 or 重新自动采集坐标; the backend ranks source coordinates, open organization lookups, and Nominatim online search results. If those regular sources return no candidates, the current default AI Provider is used once as an LLM factcheck fallback. Stored BGP collector locations are used as query context only and are not emitted as candidates.

Candidates can be previewed directly on Earth. Compute-center candidates can be saved into the compute_center_locations dimension table from the detail card, then the layer refreshes immediately. The notification badge on the compute-center layer row shows unresolved records that cannot be rendered; clicking it opens the queue, where users can collect individual candidates or use 一键采用 to save the highest-confidence candidate top-to-bottom. Records without candidates stay in the queue and are not replaced by country centroids or hard-coded hints. See Earth Location Candidate Collection User Guide for the full workflow.

Settings

The settings panel contains:

• Rotation mode / cruise mode / motion mode
• Cruise modules: BGP, News, Compute Centers, Vessels, Cables, Satellites
• View settings: satellite display style, day/night mode, panel visibility
• Motion Debug Mode, Motion Input Source, skeleton-only debug view
• 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.

Motion Capture Controls

Earth has a motion-capture control entry point for large-screen and future 3D displays. There are two realtime input sources: the default Browser Camera source uses webpage getUserMedia and recognizes gestures locally in the browser; the advanced Motion Agent source uses camera/RTSP/HTTP -> local Agent -> local WebSocket -> Earth page. Neither path sends camera frames or realtime gesture decisions to the cloud, and neither path reuses the news/RSS aggregation APIs.

It is disabled by default. Enable Motion Debug Mode in settings, open Earth with ?motion=1, or set planet-earth-motion-control-enabled=true in browser local storage to start the selected source. The default source is Browser Camera; it requires HTTPS or localhost and a granted browser camera permission, but does not require installing an app. For dual cameras, USB indexes, phone/network camera streams, client integration, or edge devices, switch the setting to Motion Agent. The default Agent URL is ws://127.0.0.1:8765/ws/gestures; the motionAgent URL parameter can override it.

URL parameters can also force the source: ?motion=1&motionProvider=browser uses the browser camera, ?motion=1&motionProvider=agent uses Motion Agent, and providing motionAgent=ws://... automatically selects Motion Agent.

Current gesture semantics:

Gesture event	Result
rotate_left	Rotates the globe left
rotate_right	Rotates the globe right
rotate_up	Rotates the globe upward
rotate_down	Rotates the globe downward
zoom_in	Zooms in
zoom_out	Zooms out
focus_prev / focus_next	Switches targets within the current motion layer
layer_prev / layer_next	Switches the motion candidate layer and cruises to the nearest target in that layer
confirm	Confirms the currently selected target; browser recognition currently keeps the two-hands-up confirm gesture disabled

The settings panel also includes Motion Debug Mode, which opens the debug panel. With the Browser Camera source, the panel shows a local live preview and draws joints and bones over it. With the Motion Agent source, the Agent sends normalized skeleton events only and does not send raw video frames. The Skeleton Only switch hides the video preview and keeps the dark canvas plus skeleton; Stop Matching Gestures pauses gesture execution while preview and skeleton drawing can continue for debugging. Unmatched skeletons are red; once a gesture matches, the skeleton turns green and the matched gesture name is shown. Both this entry and the Motion Input Source control already carry Gatekeeper permission markers for future authorization control.

Cruise Mode

Cruise mode makes Earth automatically cycle through focus targets.

Current cruise modules:

• BGP
• News
• Compute Centers
• Vessels
• Cables
• Satellites

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

Documentation site:

http://localhost:3000/docs

Docs content is read through backend APIs by permission. The frontend no longer bundles all Markdown files directly. Source files still live in:

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

Anonymous visitors only see public docs such as the overview, quickstart, and manual. Logged-in users can see more technical docs when assigned Gatekeeper groups:

• docs_user: user-operation docs.
• docs_developer: Earth, frontend, backend, collector, and AI Provider development docs.
• docs_admin: service control, operations, environment variable, and sensitive-operation docs.

admin receives admin-doc access by default, and super_admin can read all Docs content. Gatekeeper groups are configured in the console Users page.

Docs supports:

• Category navigation
• Markdown rendering
• Tables and code blocks
• In-document table of contents
• Search across currently visible docs
• 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 backend Docs metadata for category and ordering
• Should it be classified as public, docs_user, docs_developer, or docs_admin

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
• Earth Location Candidate Collection User Guide
• System Service Control
• Backend Collectors