planet/docs/technical/en/manual.md

Planet Manual

This manual is for Planet end users. Starting from the browser, it covers account registration, login, configuring collectors, configuring AI, using Earth and the console, and reading the docs site. Every action happens in a browser.

If you are responsible for deployment or on-call duty, read the Planet Ops Runbook instead — it covers shell commands, log paths, and CLI fallbacks for user creation.

Entry Overview

Name	URL	Login Required	Description
Earth	http://<host>/earth	No	Public 3D situational awareness page
Docs	http://<host>/docs	Partly	Public docs need no login; developer/ops docs need Gatekeeper groups
Register / Login / Forgot Password	/register, /login, /forgot-password	No	Self-serve account creation and recovery
Console	http://<host>/admin	Yes	Data, collectors, alerts, AI, users, settings
AI	http://<host>/ai	Yes	Model providers, tools, testbench
Backend API Docs	http://<host>:8000/docs	Depends	FastAPI / OpenAPI

URLs below use the local default http://localhost:3000. Replace the prefix with your deployment URL in production.

Register an Account

1. Open http://localhost:3000/login and click "Register" under the form.
2. On /register, fill in:
   • Username: 3–50 characters, used to log in
   • Email: receives the verification code; editable later in account settings
   • Password: at least 8 characters
3. After submission you are taken to the verify page. A 6-digit code is sent to your email. It expires in 10 minutes.
4. Enter the code and click "Verify and Sign In". On success the system stores a session and sends you to the console.

If no email arrives within 60 seconds:

• Check spam, promotions, and any enterprise mail gateway
• The "Resend Code" button shows a 60-second countdown; you can resend after it ends
• After 5 wrong attempts the code is invalidated; you must resend a new one

If you see "Email service not configured", the administrator has not yet set up SMTP. Ask the administrator to fill SMTP at /settings -> SMTP Email.

The default role for a self-registered user is viewer, which can sign in and view public content. To see collector / user / settings pages, ask an admin or super_admin to promote your role at /users.

Sign In and Recover Password

Sign In

Open /login, enter username and password. On success you are taken to /admin.

If you see "Email not verified", the page automatically redirects to /verify-email — follow the prompts to enter the code.

Forgot Password

1. On /login, click "Forgot Password?", or open /forgot-password directly.
2. Enter your registered email and click "Send Code". The same confirmation is shown regardless of whether the email is registered (to avoid enumeration).
3. After receiving the code, enter it together with a new password (≥ 8 characters) and click "Reset Password".
4. The system sends you back to /login — sign in with the new password.

Account Settings

Click your username at the top-right of the console to open account settings:

• Change password: enter current password + new password
• Change email: the system sends a verification code to the new address; the change applies only after verification
• View Gatekeeper groups: lists current groups (docs_user / docs_developer / docs_admin)
• Log out: clears the current session

Console Overview

The console at http://localhost:3000/admin is built with React + Ant Design. The left menu is organized by work domain.

Page	Route	Purpose
Dashboard	/admin	System overview
Earth	/earth	Open the public Earth page
Datasources	/datasources	Source directory and collection triggers
Collected Data	/data	Data already ingested
BGP	/bgp	BGP situational view
System Alerts	/alerts/system	System-level alerts
BGP Alerts	/alerts/bgp	BGP-related alerts
Situational Alerts	/alerts/situational	Situational analysis alerts
AI	/ai	Model providers, tools, testbench
Earth Content	/earth-content	TV livestreams, boundary precision, base-map and layer-resource entry points
Collection Management	/collection-management	Collectors, scheduling, collection history entry points
Logs	/logs	Usually visible only to super admin
Users	/users	Create/delete users, change roles/groups
System Settings	/settings	Display, notification, security, SMTP

Menu items hide automatically when you lack permission. If a menu is missing, check your role and Gatekeeper groups.

Configure Data Collectors

/collection-management?tab=collector_credentials is the "Collectors" page. It manages connection configuration for every collector, not just credentials. Legacy /settings?tab=collector_credentials redirects here; the datasource directory remains at /datasources.

Steps:

1. Pick a collector in the dropdown.
2. Inspect status tags:
   • No credentials / Credentials required
   • Owning module
   • Enabled / Disabled
   • Unchecked / Reachable / Unreachable
3. Click the plug icon next to the dropdown to run a health check. On success the status becomes Reachable.
4. Edit endpoint, headers, timeout, retries; click save.

For free collectors without credentials, the health check hits the endpoint directly. For credential-bearing collectors it runs the credential flow. If credentials or endpoint changed since the last successful check, click connect again.

"Connected" means either: data was successfully collected with the current config, or the connect button passed validation with the current config.

BarentsWatch AIS Credentials

BarentsWatch AIS is a credential-required built-in collector. Selecting it surfaces the credential section above the base configuration:

• Client ID
• Client Secret
• Endpoint

If a secret was saved previously, the input shows a masked preview. Saving while keeping the preview unchanged preserves the original secret; entering a new secret overwrites it.

When the connection fails, the page opens a credential guide. You can:

• View the default guide
• Click "Guide not helpful" to ask AI Provider to regenerate from the default prompt
• Click "Reset" to restore the default guide

The default guide follows the BarentsWatch official tutorial and reminds you to choose AIS - API for Live AIS.

AISStream Realtime Vessels

AISStream Realtime Vessels is the global AIS WebSocket collector. A passing connection test only confirms API key + endpoint format. Actual global vessel data requires the backend aisstream_vessels collector to stay connected and write to ais_raw_observations.

Steps:

1. Open /collection-management?tab=collector_credentials and select AISStream Realtime Vessels : aisstream_vessels
2. Fill the AISStream API Key
3. Keep the default endpoint wss://stream.aisstream.io/v0/stream
4. Click the plug icon to test; confirm it reports Reachable
5. Save collector settings
6. Open the Realtime Streams tab on /datasources and find AISStream Realtime Vessels
7. Use Start, Stop, or Reconnect there. The normal Collection Tasks tab does not count AISStream in one-click collection or percentage progress
8. Watch the realtime stream panel:
   • streaming / connected means the live stream is being consumed
   • total stored, last 24h, last 1h, and unique MMSI show historical collection volume
   • disconnected with a recent error means the upstream or network dropped; click Reconnect

Configure AI Credentials

/ai?tab=providers is the AI management entry. Three key sub-tabs:

• Model Providers: default LLM provider, model, base URL, API key, local aiprovider proxy, connection test
• Tools: a dropdown for specific tools — currently WebSearch and OCR
• Prompts: a task dropdown for news localization, alert analysis, BGP briefs, and other LLM tasks. Operators can edit the prompt or reset it to the default

Model Providers

Providers and models accept presets or arbitrary custom IDs. Common fields:

• Provider: e.g. minimax, openai, anthropic, ollama
• Protocol: OpenAI Chat Completions / Anthropic Messages / Ollama Generate
• Base URL: model API URL
• Default Model: e.g. gpt-5.1, MiniMax-M2.7
• API Key: stored on save; displayed masked afterwards
• Max Tokens, Anthropic Version: keep defaults if unsure
• Timeout / Retry: timeout and retry attempts

The plug icon at the end of the Base URL input runs a connection test. A passing test echoes the model's short reply.

Tools

• WebSearch: provider, API key, base URL, max results, timeout, advanced provider parameters. While disabled, all fields except the enable switch are greyed out
• OCR: provider, base URL, API key, model/engine, recognition languages, timeout, max file size, output format

Prompts

After selecting a task, the page shows the effective prompt, whether it is customized, the shipped default version, and a reset button. Saving affects only that task. Reset restores the default prompt from the current release package. Business facts, context, and output schemas are still assembled by the backend for each task.

The legacy link /settings?tab=ai redirects to /ai?tab=providers.

System Settings

/settings manages system-level configuration. Sub-tabs:

• System Display: name, refresh interval, retention, max concurrent tasks
• Notifications: alert email switch, recipient, critical/warning/daily summary
• Security: session timeout, max login attempts, password policy
• SMTP Email: outgoing email used by registration and password reset (visible to admin / super_admin only)

TV livestreams and boundary precision moved to /earth-content; collectors and scheduling moved to /collection-management; AI Provider / WebSearch / OCR live at /ai.

Earth Content

/earth-content is under the console's Operations and Configuration group and owns resources used by the Earth frontend:

• TV Livestream: manages sources shown in the Earth media panel.
• Boundary Precision: shows the current provider, low-precision fallback, high-precision PMTiles/manifest status, local source JSON, and manual build action.
• Base Map, Layer Resources, 3D Assets, and News Anchor Strategy: placeholder tabs for future configuration. They do not display fake data.

The Earth page settings gear also includes Boundary Precision. Switching to High Precision starts a local background download/build, like a game update package, when no high-precision asset exists yet. Progress is shown as a percentage, and the result applies automatically after success without a page reload. Switching back to Low Precision only changes the local display preference.

Collection Management

/collection-management is also under Operations and Configuration and owns the collection lifecycle:

• Collectors: endpoint, headers, credentials, timeout, retry, and connection checks.
• Collection Scheduling: the existing scheduling configuration.
• Collection History / Snapshots: a placeholder for future collection task, snapshot, and collected-data browsing.

SMTP Email Settings

Public registration and verification codes depend on this section. An admin or super_admin opens /settings -> SMTP Email and fills:

• SMTP host, port
• Username, password
• From address (required), from name
• STARTTLS (typical for port 587) or implicit TLS (port 465)
• Timeout in seconds

Save, then click "Send Test Email" and enter a recipient address to verify delivery. Once that works, regular users can self-register at /register.

Leaving the masked password preview unchanged keeps the original password. Enter a new value to replace it.

User Management (Admins)

/users is super_admin-only for create/delete. The page supports:

• Listing users (username, email, role, active, email verified)
• Creating users (equivalent to public registration but skips email verification — administrator vouching)
• Changing roles: viewer / operator / admin / super_admin
• Editing Gatekeeper groups: docs_user / docs_developer / docs_admin, controlling which docs are visible
• Disabling / enabling accounts

To let a regular user read developer or operations docs, add docs_developer or docs_admin at /users.

Data Exploration

• /datasources: source directory. The Collection Tasks tab is for one-shot, scheduled, and finite collectors; it can be filtered by product domain, layer/module, enabled state, last run status, whether collected records exist, and search text. Selecting rows triggers only those sources; with no selected rows, Collect current filter triggers the filtered scope. The Realtime Streams tab is for AISStream / WebSocket long connections and shows connection health, stored totals, time-window counters, and Start / Stop / Reconnect actions. Clicking a name opens an info drawer showing endpoint, headers, base config, and built-in flag; endpoint/credentials editing happens at /collection-management -> Collectors. The Collecting N tag under the overall progress can be clicked to expand the current collection task list
• /data: collected data table — used to verify "did data arrive", "is the freshness right", "does a source emit valid records"
• /bgp: BGP detail page with list + detail + analysis; complements the BGP layer on Earth
• /alerts/system, /alerts/bgp, /alerts/situational: system, BGP, and situational alerts

AI Testbench

/ai?tab=playground is for real-pipeline debugging:

• Pick the active provider
• Run preset requests or custom prompts
• Watch AI Provider status and response

The legacy link /playground redirects here.

Earth Public Page

Earth at http://localhost:3000/earth is the public 3D situational page; no login required. The React route /earth wraps a standalone frontend (in frontend/public/earth/) via iframe.

Primary Uses

A single globe view of: BGP events and observations, satellites and tracks, cables and landing points, compute centers, country boundaries / graticules / high-res tiles / clouds / terrain, news live streams and situational news, search and focus details.

Layer Control

The right-side layer panel toggles layers. Common layers: graticule, country boundaries, high-res tiles, atmospheric clouds, cables, compute centers, BGP, satellites, AIS vessels, terrain. Satellite tracks are no longer listed as a standalone layer; they are controlled from Settings.

Dependencies:

• Terrain depends on high-res tiles
• Tracks depend on satellites
• With high-res tiles disabled, the globe shows the base map with edge highlighting

Legend

The bottom-left legend follows the focused or enabled layer. Covered: cables, satellites, country boundaries, compute centers, BGP, AIS vessels.

AIS vessel legend colors by type: cargo, tanker, passenger, fishing, military, moored/slow, other. Triangles indicate moving vessels; dots indicate moored or slow targets.

Search

Search finds cables, landing points, satellites, compute centers, BGP events, BGP observers. Results jump to and focus the object.

Coordinate Candidate Collection

Compute center and BGP observer detail cards support automatic coordinate-candidate collection. Click the object then use "Collect Coordinate Candidates" or "Re-collect Coordinates". The backend assembles candidates from source coordinates, public-org registry APIs, and online geocoders. When regular sources have no candidate, the current default AI Provider runs one LLM factcheck fallback. BGP observers' stored coordinates only fill query context; they are not returned as candidates.

Candidates preview on Earth directly. Saving a compute-center candidate writes to the compute_center_locations dimension table and refreshes the layer immediately. The notification badge at the top-left of the compute-center layer shows the unresolved count; clicking it opens the queue, supports single collection, or "Adopt All" to save the top-confidence candidates from top to bottom. Records without candidates stay in the queue rather than being faked to country centroids. See Earth Location Candidate Collection User Guide.

Settings

The settings panel covers: rotate / cruise / motion mode, cruise modules (BGP/news/compute centers/vessels/cables/satellites), view (satellite display style, hover tooltip, satellite idle breathing, real satellite altitude, track display, compact dots, day-night mode, panel toggles), motion debug mode / input source / skeleton-only, default globe size, terrain opacity, reset.

"Real Satellite Altitude" is enabled by default: satellite positions use a compressed display height based on TLE/SGP4 orbital altitude. LEO satellites remain close to the globe, while high-orbit satellites render farther out without leaving the normal view. The high-orbit display height is capped at about one quarter of the globe radius, so GEO / MEO objects remain visually separated from LEO without spreading trails and selection targets too far apart. Turning it off restores the legacy same-sphere satellite display. "Track Display" controls satellite trail visibility; trails are unavailable while the satellite layer is hidden.

"Hover Tooltip" controls the tooltip shown when the pointer hovers over the globe surface: Country shows country details only when land matches a country, and stays silent over oceans such as the Pacific; Position shows latitude, longitude, and elevation over land and ocean; Full is the default and shows country + position over land and position over ocean.

These settings live in browser local storage; switching browsers or clearing site data resets them.

View Controls

Action	Effect
Mouse drag	Rotate the globe
Single-finger drag	Touch rotate
Mouse wheel	Zoom in/out
Pinch	Touch zoom
Zoom button	Stepped zoom
Click zoom percentage	Reset to default zoom

A small pill at the top briefly shows the current zoom while zooming. This is not a data loading indicator; if data is loading, the loading state takes precedence.

Drag sensitivity adjusts to zoom: near the default it is normal; zoomed in it is finer for targeted inspection; zoomed out it is slightly faster for global browsing.

Motion Capture

Earth supports motion capture. Two live inputs:

• Browser Camera (default): uses getUserMedia in the page. No install needed but the page must run on HTTPS or localhost, and the user must grant camera permission
• Motion Agent: camera/RTSP/HTTP → local agent → local WebSocket → Earth. Used for dual cameras, USB index, phone/IP camera streams

Enable via the settings toggle "Motion Debug Mode", or with URL parameter ?motion=1. Motion Agent defaults to ws://127.0.0.1:8765/ws/gestures; override with motionAgent. You can also pin the input with ?motion=1&motionProvider=browser or ?motion=1&motionProvider=agent.

Neither mode uploads camera frames or live gestures; neither reuses the news/RSS aggregation API.

Gesture semantics:

Event	Effect
rotate_left/right/up/down	Rotate accordingly
zoom_in/out	Zoom
focus_prev/next	Cycle focusable targets within the current layer
layer_prev/next	Switch layer and pan to nearest target
confirm	Confirm the current selection

In the debug panel: the browser camera input shows the live preview with skeleton overlay; Motion Agent sends only normalized skeleton events, never raw frames. "Skeleton Only" hides the video and keeps just the skeleton; "Stop Matching" pauses gesture firing while keeping preview and skeleton. Unmatched skeleton is red; matched turns green and shows the action name.

Cruise Mode

Cruise mode auto-rotates focused targets. Current modules: BGP, news, compute centers, vessels, cables, satellites. Suitable for demos, control rooms, and unattended displays.

Mobile

Mobile uses a drawer layout: layer control moves into a drawer; search/settings/details use mobile panels. Main interaction is still object tap, search, and layer toggles.

Common Issues

• Earth does not open: confirm the frontend is online; if not on port 3000, use the port printed by the startup log
• Layers have no data: open /datasources to check source status, collected-record state, and the latest run result; then /data or /bgp for records
• Satellites / BGP / cables load slowly: those layers depend on backend APIs and external data sources; the first load waits for startup tasks
• Satellites are not all on one shell: this is the default compressed real-altitude display. Disable "Real Satellite Altitude" in Settings to return to the legacy same-sphere view

Docs Site

Docs at http://localhost:3000/docs are served by the backend with access control, not bundled into the frontend build.

Anonymous visitors see only public docs: README, Quickstart, Manual, FAQ, Earth Location Candidate Collection User Guide. Authenticated users with Gatekeeper groups see more:

• docs_user: end-user operational docs
• docs_developer: Earth, frontend, backend, collectors, AI Provider development docs
• docs_admin: service control, operations, environment variables, sensitive operations (including the Ops Runbook)

admin has docs_admin by default; super_admin has all docs permissions. Gatekeeper groups are managed at /users.

Docs supports: category navigation, Markdown rendering, tables and code blocks, in-doc table of contents, search across currently visible docs, internal links between technical docs.

Related Docs

• Quickstart
• FAQ
• Earth Location Candidate Collection User Guide
• Planet Ops Runbook