232 lines
4.3 KiB
Markdown
232 lines
4.3 KiB
Markdown
# Platform Agent Runbook
|
|
|
|
This runbook covers running the Platform Agent on a remote device and connecting a KasmVNC-based remote desktop.
|
|
|
|
## Role
|
|
|
|
The agent provides these capabilities on the remote platform:
|
|
|
|
- Start, stop, and inspect a KasmVNC XFCE remote desktop
|
|
- Browse, read, and save workspace files
|
|
- List, start, stop, log, and connect terminals to Docker modules
|
|
- Start and stop the camera WebRTC sender
|
|
- List `/dev/video*` camera devices
|
|
|
|
## Recommended Runtime
|
|
|
|
Host execution is currently recommended over Docker.
|
|
|
|
Reasons:
|
|
|
|
- KasmVNC/XFCE is simpler when attached to the host desktop environment
|
|
- Camera and GStreamer stacks are commonly validated on the host
|
|
- Adding GStreamer and desktop packages to the Docker image increases image size
|
|
|
|
## Required Host Environment
|
|
|
|
```text
|
|
bun
|
|
KasmVNC
|
|
XFCE
|
|
python3
|
|
python3-gi
|
|
websockets
|
|
GStreamer webrtcbin
|
|
v4l-utils
|
|
Docker
|
|
```
|
|
|
|
Check commands:
|
|
|
|
```bash
|
|
bun --version
|
|
command -v vncserver || command -v kasmvncserver
|
|
python3 -c "import websockets, gi"
|
|
gst-inspect-1.0 webrtcbin
|
|
v4l2-ctl --list-devices
|
|
docker ps
|
|
```
|
|
|
|
## Install
|
|
|
|
```bash
|
|
cd /home/chyoo/tmp/agent_v2
|
|
bun install
|
|
```
|
|
|
|
`bun install` installs only JavaScript dependencies. System packages such as KasmVNC, XFCE, and GStreamer must be installed separately.
|
|
|
|
## Run
|
|
|
|
```bash
|
|
cd /home/chyoo/tmp/agent_v2
|
|
HOST=0.0.0.0 PORT=3100 bun run start
|
|
```
|
|
|
|
Development run:
|
|
|
|
```bash
|
|
cd /home/chyoo/tmp/agent_v2
|
|
HOST=0.0.0.0 PORT=3100 bun run dev
|
|
```
|
|
|
|
Use this URL from the Electron app or browser:
|
|
|
|
```text
|
|
http://<platform-ip>:3100
|
|
```
|
|
|
|
## Main Environment Values
|
|
|
|
```bash
|
|
HOST=0.0.0.0
|
|
PORT=3100
|
|
WORKSPACE_ROOT=/home/ubuntu/.caches
|
|
|
|
KASMVNC_DISPLAY=:1
|
|
KASMVNC_WEB_PORT=6901
|
|
KASMVNC_PROTOCOL=http
|
|
KASMVNC_INTERFACE=0.0.0.0
|
|
KASMVNC_GEOMETRY=1600x900
|
|
KASMVNC_DESKTOP=XFCE
|
|
|
|
CAMERA_ENABLED=true
|
|
CAMERA_SIGNALING_URL=ws://SIGNALING_HOST:3000
|
|
CAMERA_ROOM_ID=jetson-1
|
|
CAMERA_VIDEO_DEVICE=/dev/video0
|
|
```
|
|
|
|
## KasmVNC API
|
|
|
|
```bash
|
|
curl http://127.0.0.1:3100/api/kasmvnc/status
|
|
curl -X POST http://127.0.0.1:3100/api/kasmvnc/start
|
|
curl -X POST http://127.0.0.1:3100/api/kasmvnc/stop
|
|
```
|
|
|
|
Default command run by the agent:
|
|
|
|
```bash
|
|
vncserver :1 -select-de XFCE -geometry 1600x900 -depth 24 -websocketPort 6901 -interface 0.0.0.0
|
|
```
|
|
|
|
Default KasmVNC web URL:
|
|
|
|
```text
|
|
http://<platform-ip>:6901
|
|
```
|
|
|
|
## API Checks
|
|
|
|
Health and config:
|
|
|
|
```bash
|
|
curl http://127.0.0.1:3100/health
|
|
curl http://127.0.0.1:3100/api/config
|
|
```
|
|
|
|
Workspace:
|
|
|
|
```bash
|
|
curl http://127.0.0.1:3100/api/workspace/summary
|
|
curl http://127.0.0.1:3100/api/workspace/tree
|
|
```
|
|
|
|
Camera:
|
|
|
|
```bash
|
|
curl http://127.0.0.1:3100/api/camera/devices
|
|
curl http://127.0.0.1:3100/api/camera/status
|
|
curl -X POST http://127.0.0.1:3100/api/camera/start
|
|
curl -X POST http://127.0.0.1:3100/api/camera/stop
|
|
```
|
|
|
|
## systemd Example
|
|
|
|
```ini
|
|
[Unit]
|
|
Description=Platform Agent
|
|
After=network-online.target
|
|
|
|
[Service]
|
|
WorkingDirectory=/home/ubuntu/tmp/agent_v2
|
|
ExecStart=/home/ubuntu/.bun/bin/bun run start
|
|
Restart=always
|
|
Environment=HOST=0.0.0.0
|
|
Environment=PORT=3100
|
|
Environment=WORKSPACE_ROOT=/home/ubuntu/.caches
|
|
Environment=KASMVNC_DISPLAY=:1
|
|
Environment=KASMVNC_WEB_PORT=6901
|
|
Environment=KASMVNC_PROTOCOL=http
|
|
Environment=KASMVNC_INTERFACE=0.0.0.0
|
|
Environment=KASMVNC_GEOMETRY=1600x900
|
|
Environment=KASMVNC_DESKTOP=XFCE
|
|
Environment=CAMERA_ENABLED=true
|
|
Environment=CAMERA_SIGNALING_URL=ws://SIGNALING_HOST:3000
|
|
Environment=CAMERA_ROOM_ID=jetson-1
|
|
Environment=CAMERA_VIDEO_DEVICE=/dev/video0
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
```
|
|
|
|
Register the service:
|
|
|
|
```bash
|
|
sudo cp platform-agent.service /etc/systemd/system/platform-agent.service
|
|
sudo systemctl daemon-reload
|
|
sudo systemctl enable platform-agent
|
|
sudo systemctl start platform-agent
|
|
sudo systemctl status platform-agent
|
|
```
|
|
|
|
Logs:
|
|
|
|
```bash
|
|
journalctl -u platform-agent -f
|
|
```
|
|
|
|
## Docker Run
|
|
|
|
Docker compose is available but optional.
|
|
|
|
```bash
|
|
cd /home/chyoo/tmp/agent_v2
|
|
cp .env.example .env
|
|
docker compose up -d --build
|
|
```
|
|
|
|
Notes:
|
|
|
|
- Running KasmVNC/XFCE inside a container requires separate desktop session setup
|
|
- If KasmVNC and camera integration are already validated on the host, host execution is usually lighter
|
|
|
|
## Troubleshooting
|
|
|
|
Check ports:
|
|
|
|
```bash
|
|
ss -ltnp | grep -E '3100|6901'
|
|
```
|
|
|
|
Check KasmVNC:
|
|
|
|
```bash
|
|
command -v vncserver || command -v kasmvncserver
|
|
vncserver -list
|
|
```
|
|
|
|
Check camera devices:
|
|
|
|
```bash
|
|
ls -l /dev/video*
|
|
v4l2-ctl --list-devices
|
|
```
|
|
|
|
Check GStreamer:
|
|
|
|
```bash
|
|
gst-inspect-1.0 webrtcbin
|
|
gst-inspect-1.0 nvv4l2h264enc
|
|
```
|