Initial commit
This commit is contained in:
@@ -0,0 +1,231 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user