362 lines
16 KiB
Markdown
362 lines
16 KiB
Markdown
# FAQ
|
|
|
|
This page collects common troubleshooting paths for local startup, Windows / WSL, dependencies, motion capture, credentials, and Docs permissions. Deeper background stays in the topic-specific docs; this page focuses on what to check first and which command to run.
|
|
|
|
## Startup and Ports
|
|
|
|
### What should I do when the backend port is already in use?
|
|
|
|
The error usually looks like:
|
|
|
|
```text
|
|
Backend address is already in use: 0.0.0.0:8000 / 127.0.0.1:8000 / [::1]:8000
|
|
Address already in use
|
|
```
|
|
|
|
First try:
|
|
|
|
```bash
|
|
./planet.sh restart -b
|
|
```
|
|
|
|
If the port remains occupied, start on a different backend port:
|
|
|
|
```bash
|
|
./planet.sh start -b 8001
|
|
```
|
|
|
|
In WSL, the listener may be on the Windows side rather than a Linux process. A common diagnostic line looks like:
|
|
|
|
```text
|
|
Windows listener: 0.0.0.0:8000 pid=4700 process=svchost.exe services=iphlpsvc
|
|
```
|
|
|
|
`iphlpsvc` is the Windows IP Helper service. It often hosts IPv6, tunneling, proxying, port forwarding, WSL, or developer-tool networking features. Do not start by killing that `svchost.exe`; first check whether an old portproxy rule owns the port.
|
|
|
|
From Administrator PowerShell, inspect portproxy rules:
|
|
|
|
```powershell
|
|
netsh interface portproxy show all
|
|
```
|
|
|
|
If you see `0.0.0.0:8000` or `listenport=8000`, delete that rule:
|
|
|
|
```powershell
|
|
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
|
|
```
|
|
|
|
If there is no portproxy rule, confirm which services are hosted by that PID:
|
|
|
|
```powershell
|
|
netstat -ano | findstr :8000
|
|
tasklist /svc /fi "PID eq 4700"
|
|
```
|
|
|
|
For temporary troubleshooting, you can stop IP Helper from Administrator PowerShell:
|
|
|
|
```powershell
|
|
Stop-Service iphlpsvc -Force
|
|
```
|
|
|
|
This may affect networking, proxying, or forwarding features. Do not disable it long-term unless you know why it is safe. `--allow-lan` now binds `3000` / `8000` / `8010` directly, so persistent portproxy is no longer required.
|
|
|
|
If the script prints `Windows 侧端口 ... 存在监听者`, or Vite reports `Port 3000 is already in use` followed by `Windows listener ... services=iphlpsvc`, an old Windows listener still owns the port. The script requests Administrator PowerShell cleanup for that port. If the automatic cleanup is canceled, inspect `netsh interface portproxy show all`, delete the matching `listenport` rule, confirm the PID and services with `netstat` / `tasklist` if no portproxy rule exists, and temporarily run `Stop-Service iphlpsvc -Force` when appropriate. After old rules are gone, rerun `./planet.sh restart --allow-lan`; LAN devices still use `3000` / `8000` / `8010`.
|
|
|
|
### Which startup flags change default ports?
|
|
|
|
| Service | Default port | Flag |
|
|
| --- | --- | --- |
|
|
| Frontend | `3000` | `-f <port>` |
|
|
| Backend | `8000` | `-b <port>` |
|
|
| AI Provider | `8010` | `-a <port>` |
|
|
| Motion Agent | `8765` | `--motion-agent-port <port>` |
|
|
|
|
Example:
|
|
|
|
```bash
|
|
./planet.sh start -f 3001 -b 8001 -a 8101
|
|
```
|
|
|
|
## Windows / WSL / LAN
|
|
|
|
### LAN access does not work on Windows / WSL. What should I check?
|
|
|
|
Check in this order before changing firewall rules:
|
|
|
|
```bash
|
|
# In WSL or the shell running Planet
|
|
curl http://localhost:3000
|
|
curl http://localhost:8000/health
|
|
curl http://localhost:8010/health
|
|
```
|
|
|
|
Then verify from Windows PowerShell:
|
|
|
|
```powershell
|
|
curl http://localhost:3000
|
|
curl http://localhost:8000/health
|
|
curl http://localhost:8010/health
|
|
```
|
|
|
|
If both localhost checks pass but a phone or another computer cannot connect, start with LAN enabled:
|
|
|
|
```bash
|
|
./planet.sh start --allow-lan
|
|
```
|
|
|
|
The flag must be written as `--allow-lan`. `allowlan` or `--allowlan` is not recognized by the startup script. If Planet is already running and you only need to reopen the frontend on the LAN, restart the frontend explicitly:
|
|
|
|
```bash
|
|
./planet.sh restart -f 3000 --allow-lan
|
|
```
|
|
|
|
If `ss -ltnp` shows the frontend listening on `0.0.0.0:3000`, but `Test-NetConnection <Windows LAN IP> -Port 3000` still fails from Windows PowerShell, the problem is usually Windows-side port ownership, stale `portproxy`, or firewall policy rather than Vite or `.zshrc`.
|
|
|
|
`./planet.sh start --allow-lan` directly exposes `3000` / `8000` / `8010` and checks port availability, stale `portproxy`, and Windows Firewall before startup. If a Windows-side listener owns a port, the script requests Administrator PowerShell cleanup. When inbound allow rules are missing, it also triggers a UAC Administrator PowerShell request to create them. If the automatic request is canceled, clean up manually:
|
|
|
|
```powershell
|
|
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
|
|
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000
|
|
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8010
|
|
|
|
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
|
|
New-NetFirewallRule -DisplayName "WSL Planet 8010" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8010
|
|
```
|
|
|
|
LAN devices should use the Windows external port, for example `http://<Windows LAN IP>:3000/earth`.
|
|
|
|
If `wslinfo --networking-mode` prints `mirrored`, also check Hyper-V firewall. Even when ordinary Windows Firewall rules exist, Hyper-V firewall can still block external devices from reaching WSL. From Administrator PowerShell, allow the required ports:
|
|
|
|
```powershell
|
|
New-NetFirewallHyperVRule -Name "Planet-Frontend-3000" -DisplayName "Planet Frontend 3000" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 3000 -Action Allow
|
|
New-NetFirewallHyperVRule -Name "Planet-Backend-8000" -DisplayName "Planet Backend 8000" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 8000 -Action Allow
|
|
New-NetFirewallHyperVRule -Name "Planet-AIProvider-8010" -DisplayName "Planet AI Provider 8010" -Direction Inbound -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}" -Protocol TCP -LocalPorts 8010 -Action Allow
|
|
```
|
|
|
|
Use these commands to inspect the current Hyper-V firewall state:
|
|
|
|
```powershell
|
|
Get-NetFirewallHyperVVMSetting -Name "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}"
|
|
Get-NetFirewallHyperVRule -VMCreatorId "{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}"
|
|
```
|
|
|
|
LAN devices should open the Windows LAN IP, for example `http://<Windows LAN IP>:3000/earth`, not the internal WSL IP.
|
|
|
|
### How do `--allow-lan` and the Motion Agent LAN URL fit together?
|
|
|
|
`--allow-lan` binds the frontend, backend, and optional Motion Agent to `0.0.0.0`. If a remote browser needs to connect to the display machine's Motion Agent, pass the Agent URL explicitly:
|
|
|
|
```text
|
|
http://<LAN_IP>:3000/earth?motion=1&motionProvider=agent&motionAgent=ws://<LAN_IP>:8765/ws/gestures
|
|
```
|
|
|
|
Browser Camera mode does not need a `motionAgent` URL.
|
|
|
|
## Dependencies and Environment Variables
|
|
|
|
### Why should I use `uv` instead of `pip`?
|
|
|
|
Planet manages Python dependencies through `uv` and `pyproject.toml`. Avoid `pip install` in the project environment, because it can diverge from the lock file and startup scripts.
|
|
|
|
For Motion Agent live dependencies, use:
|
|
|
|
```bash
|
|
uv add mediapipe opencv-python
|
|
```
|
|
|
|
`planet.sh start --motion-agent` checks and installs those live dependencies automatically. To disable auto-install:
|
|
|
|
```bash
|
|
PLANET_MOTION_AGENT_AUTO_INSTALL=0 ./planet.sh start --motion-agent
|
|
```
|
|
|
|
### Why should I use `bun` instead of `npm run`?
|
|
|
|
The frontend runtime is Bun. This avoids WSL / Windows mixed-path issues that can happen when npm invokes `cmd.exe`.
|
|
|
|
Common commands:
|
|
|
|
```bash
|
|
bun install
|
|
bun run dev
|
|
bun run build
|
|
```
|
|
|
|
If a non-interactive shell cannot find `bun`, `planet.sh` searches the current PATH, `~/.bun/bin`, zsh config, and PowerShell command resolution.
|
|
|
|
### When does `planet.sh` read environment variables from `.zshrc`?
|
|
|
|
By default, `planet.sh` statically parses simple lines in `~/.zshrc`:
|
|
|
|
```bash
|
|
export KEY=value
|
|
KEY=value
|
|
```
|
|
|
|
This avoids slow shell themes, plugins, and interactive initialization. For complex shell expansion, opt in to source mode:
|
|
|
|
```bash
|
|
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
|
|
```
|
|
|
|
To ignore `~/.zshrc` while troubleshooting:
|
|
|
|
```bash
|
|
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
|
|
```
|
|
|
|
Never put real secret values in docs or commits; documentation should only mention variable names and purposes.
|
|
|
|
## Motion Capture / Cameras
|
|
|
|
### Does Browser Camera mode need the `motionAgent` parameter?
|
|
|
|
No. Browser Camera mode uses webpage `getUserMedia` and runs recognition locally in the browser.
|
|
|
|
Recommended URL:
|
|
|
|
```text
|
|
/earth?motion=1&motionProvider=browser
|
|
```
|
|
|
|
You can also open Earth settings, enable Motion Debug Mode, and select Browser Camera as the input source. The page must run on HTTPS or localhost, and the user must grant browser camera permission.
|
|
|
|
### When do I need Motion Agent?
|
|
|
|
Use Motion Agent for:
|
|
|
|
- dual USB cameras
|
|
- RTSP / HTTP camera streams
|
|
- edge devices or client integration
|
|
- a standalone local recognition service
|
|
|
|
Common commands:
|
|
|
|
```bash
|
|
./planet.sh start --motion-agent
|
|
./planet.sh start --motion-agent --motion-agent-camera-indexes 0,1
|
|
./planet.sh start --motion-agent --motion-agent-camera-urls rtsp://example/live
|
|
./planet.sh start --motion-agent --motion-agent-dry-run
|
|
```
|
|
|
|
`--motion-agent-dry-run` is only for protocol and frontend connection testing; it does not open cameras.
|
|
|
|
### Why does WSL not find my camera?
|
|
|
|
Windows cameras usually do not appear inside WSL as `/dev/video*`. Check first:
|
|
|
|
```bash
|
|
ls /dev/video*
|
|
```
|
|
|
|
If no device appears, use Browser Camera for ordinary web demos. For Agent live mode, use an RTSP / HTTP camera URL:
|
|
|
|
```bash
|
|
./planet.sh start --motion-agent --motion-agent-camera-urls http://192.168.1.20:8080/video
|
|
```
|
|
|
|
USB passthrough into WSL is an advanced path. The script does not silently downgrade missing-camera live mode to dry-run.
|
|
|
|
## Docker / AI Provider
|
|
|
|
### Why does changing the AI key, base URL, or model not rebuild the image?
|
|
|
|
Keys, base URLs, and model names are runtime configuration. They do not require a Docker image rebuild. Restart AI Provider:
|
|
|
|
```bash
|
|
./planet.sh restart -a
|
|
```
|
|
|
|
The first Docker build may be slow because of image layers or `uv sync` dependency downloads. Later builds reuse `.dockerignore`, BuildKit, and uv cache.
|
|
|
|
### What should I do when Docker health checks fail?
|
|
|
|
Start with:
|
|
|
|
```bash
|
|
./planet.sh health
|
|
```
|
|
|
|
Then inspect logs:
|
|
|
|
```bash
|
|
./planet.sh log
|
|
```
|
|
|
|
If only AI Provider is unhealthy, restart just that service:
|
|
|
|
```bash
|
|
./planet.sh restart -a
|
|
```
|
|
|
|
## Datasource and Collector Credentials
|
|
|
|
### Connectivity validation passes, but collection cannot read credentials. Why?
|
|
|
|
Connectivity validation can read saved console settings, environment variables, and some credentials from `~/.zshrc`. For actual collection, prefer saving credentials in Collection Management -> Collectors, especially for AISStream's long-lived WebSocket collector.
|
|
|
|
If `AISSTREAM_API_KEY` only lives in `~/.zshrc`, confirm the backend process actually inherited it. Otherwise validation may pass while the collector runtime has no key.
|
|
|
|
### Where should BarentsWatch / AISStream credentials live?
|
|
|
|
For temporary debugging, environment variables or `~/.zshrc` are fine:
|
|
|
|
```bash
|
|
export AISSTREAM_API_KEY="..."
|
|
export BARENTSWATCH_CLIENT_ID="..."
|
|
export BARENTSWATCH_CLIENT_SECRET="..."
|
|
```
|
|
|
|
For stable operation, save credentials in Collectors so connectivity validation, collection jobs, and Earth realtime aggregation use the same configuration.
|
|
|
|
## Docs / Permissions
|
|
|
|
### Why can I not see some Docs pages?
|
|
|
|
Docs visibility is controlled by Gatekeeper groups:
|
|
|
|
- Quickstart, Manual, FAQ, and other basic docs are public.
|
|
- Development docs usually require `docs_developer`.
|
|
- Operations and service-control docs usually require `docs_admin`.
|
|
- `admin` and `super_admin` have Docs access by default; ordinary users need groups assigned from the Users page.
|
|
|
|
## Earth Common Tasks
|
|
|
|
### Why does Earth say the boundary endpoint is not configured, or only show low precision boundaries?
|
|
|
|
Country boundaries have moved out of the collector system. They are no longer generated by datasource collection tasks. The low-precision boundary file is bundled with the frontend and is the expected fallback when no local high-precision PMTiles artifact exists.
|
|
|
|
There are two high-precision entry points:
|
|
|
|
- Earth page settings gear -> Boundary Precision: switching to High Precision starts the first background download/build, shows percentage progress, and applies the result automatically.
|
|
- Console `Operations and Configuration -> Earth Content -> Boundary Precision`: use this to inspect provider, manifest, PMTiles, fallback state, edit source JSON, or rebuild manually.
|
|
|
|
If the UI says the update source is incomplete, save the source configuration from `Earth Content -> Boundary Precision`. The private local config is written to `config/earth-boundary-sources.local.json`; do not commit it. Falling back to low precision is normal when no high-precision artifact has been built.
|
|
|
|
### Why did collecting a location candidate not write anything?
|
|
|
|
Collecting and saving are two separate actions. Candidates can be previewed on Earth first. A candidate is written only after clicking Save or using the unresolved list's one-click adopt flow.
|
|
|
|
Compute-center saves write to `compute_center_locations` and refresh the layer. Records with no candidate stay in the unresolved list; Planet does not fabricate a location from a country center or hard-coded hint.
|
|
|
|
### Why did the Earth logo or title not return to the default after I edited it?
|
|
|
|
Earth brand assets are managed from `Operations and Configuration -> Earth Content -> Brand Assets`. Uploaded images are stored as Earth brand asset URLs. If text fields such as title or ARIA label are cleared, Planet falls back to default text so the HUD never renders an empty brand.
|
|
|
|
Use `Reset Brand Assets` to restore the shipped logo, title image, and copy. Refreshing Earth does not delete the saved runtime brand configuration.
|
|
|
|
### Why are satellites no longer on one sphere?
|
|
|
|
Earth enables "Real Satellite Altitude" by default. Satellite positions still come from TLE/SGP4, but altitude is compressed for display: LEO satellites stay close to the globe, while higher-orbit satellites render farther out without leaving the normal view. The maximum display offset is `25`, about one quarter of the current globe radius; this is a readability compromise that separates GEO / MEO / LEO without drawing real kilometers to scale. This setting also affects satellite trails and the predicted orbit shown after locking a satellite.
|
|
|
|
Turn off "Real Satellite Altitude" in Earth Settings to restore the legacy same-sphere satellite display. Satellites with missing TLE data or failed propagation still fall back to the legacy fixed height, so they do not disappear just because a real altitude cannot be computed.
|
|
|
|
Low-inclination high-orbit satellites should stay near the equator or a fixed longitude band, not form a near north-south ring. Earth converts the SGP4 inertial position to Earth-fixed coordinates for the current dot; the locked predicted orbit fixes the current globe pose and draws one inertial orbit, so it should close and preserve the correct inclination. If a future details card shows inclination near `0°` but the predicted orbit looks polar, check the ECI/TEME-to-ECF conversion and whether the predicted orbit accidentally uses per-sample `gstime`.
|
|
|
|
### Why does Motion Debug not show camera video?
|
|
|
|
With the Browser Camera source, the debug panel shows the local browser camera preview and draws the skeleton over it. If `Skeleton Only` is enabled, the video preview is hidden and the panel keeps only the dark canvas plus red/green skeleton.
|
|
|
|
With the Motion Agent source, the Agent WebSocket sends normalized joints, bones, and matched gestures only. It does not stream raw camera frames to Earth, which keeps privacy risk, bandwidth, and latency lower. In that mode the panel is a skeleton debug view rather than a video stream.
|