11 KiB
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.
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 |
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.htmlfrontend/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:
./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 |
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:
./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
/docsmanual 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:
- Check service status:
./planet.sh health
- Check recent logs:
./planet.sh log
- Check per-module logs:
./planet.sh log -f
./planet.sh log -b
./planet.sh log -a
- Restart only the affected module:
./planet.sh restart -f
./planet.sh restart -b
./planet.sh restart -a
- If database or cache is abnormal, restart the database:
./planet.sh restart -d
- If still unrecovered, do a full restart:
./planet.sh restart