installation

fleetd

Warning

This is very early work in progress.

Manage your fleet of edge devices; provision, update, monitor, and secure.

The fleet daemon, fleetd, is a long-running service that monitors and manages the lifecycle of devices and deployed software in the fleet.

The fleet services are RPC services that are used by the fleet daemon to manage the fleet. These can be run centrally or distributed.

Architecture

graph TD
    A[Device Agent] -->|mDNS| B[Discovery]
    A -->|Connect RPC| C[Fleet Server]
    C --> D[SQLite]
    C --> E[Binary Storage]
    C --> V[Valkey/Redis]
    F[Web UI] -->|Connect RPC| C
    G[Third-party Apps] -->|Public API| C

Loading

Configuration

Server Configuration

The fleet server can be configured using environment variables or command-line flags:

# Using environment variables
VALKEY_ADDR=localhost:6379 ./fleets server

# Using command-line flags
./fleets server --valkey localhost:6379 --rate-limit-requests 100

Rate Limiting

Rate limiting is implemented using Valkey (Redis-compatible) when configured:

# Start Valkey for local development
docker-compose -f docker-compose.dev.yml up -d valkey

# Run server with rate limiting
./fleets server --valkey localhost:6379

CORS Configuration

By default, the server runs with same-origin policy (no CORS). This is recommended for production deployments where the web UI and API server run on the same domain.

For development with separate frontend/backend ports, configure CORS:

# Allow specific origin
API_CORS_ORIGINS=http://localhost:3000 ./fleets server

# Note: Empty or unset = same-origin only (production recommended)

Device Provisioning

The fleet provision command is used to provision devices with the fleetd agent and optional components.

Prerequisites

• SD card reader connected to your computer
• Raspberry Pi SD card (8GB minimum recommended)
• WiFi credentials (if not using Ethernet)

List Available Devices

# List all connected block devices suitable for provisioning
fleet provision --list

Basic Provisioning (Raspberry Pi OS)

Provision a Raspberry Pi with the standard Raspberry Pi OS and fleetd agent:

# Basic provisioning with WiFi
fleet provision --device /dev/disk2 --wifi-ssid "MyNetwork" --wifi-pass "password"

# With SSH access enabled
fleet provision --device /dev/disk2 --wifi-ssid "MyNetwork" --wifi-pass "password" \
  --ssh-key-file ~/.ssh/id_rsa.pub

# With custom device name
fleet provision --device /dev/disk2 --wifi-ssid "MyNetwork" --wifi-pass "password" \
  --name "rpi-workshop-01"

# With specific fleet server
fleet provision --device /dev/disk2 --wifi-ssid "MyNetwork" --wifi-pass "password" \
  --fleet-server https://fleet.example.com:8080

DietPi Provisioning

For a minimal, optimized installation using DietPi:

# DietPi with fleetd agent
fleet provision --device /dev/disk2 --wifi-ssid "MyNetwork" --wifi-pass "password" \
  --os-type dietpi

# DietPi with SSH and custom configuration
fleet provision --device /dev/disk2 --wifi-ssid "MyNetwork" --wifi-pass "password" \
  --os-type dietpi --ssh-key-file ~/.ssh/id_rsa.pub \
  --name "dietpi-node-01"

Provisioning with k3s

Deploy Raspberry Pi devices as k3s nodes:

# k3s server node
fleet provision --device /dev/disk2 --wifi-ssid "MyNetwork" --wifi-pass "password" \
  --plugin k3s --plugin-opt k3s.role=server

# k3s agent node (worker)
fleet provision --device /dev/disk2 --wifi-ssid "MyNetwork" --wifi-pass "password" \
  --plugin k3s --plugin-opt k3s.role=agent \
  --plugin-opt k3s.server=https://192.168.1.100:6443 \
  --plugin-opt k3s.token=K10abc...xyz::server:abc...

# k3s with custom configuration
fleet provision --device /dev/disk2 --wifi-ssid "MyNetwork" --wifi-pass "password" \
  --plugin k3s --plugin-opt k3s.role=server \
  --plugin-opt k3s.cluster-init=true \
  --plugin-opt k3s.disable=traefik

Multiple Plugins

You can combine multiple plugins during provisioning:

# k3s with Docker
fleet provision --device /dev/disk2 --wifi-ssid "MyNetwork" --wifi-pass "password" \
  --plugin k3s --plugin-opt k3s.role=agent \
  --plugin-opt k3s.server=https://192.168.1.100:6443 \
  --plugin docker

# Full stack with monitoring
fleet provision --device /dev/disk2 --wifi-ssid "MyNetwork" --wifi-pass "password" \
  --plugin k3s --plugin-opt k3s.role=server \
  --plugin docker \
  --plugin prometheus \
  --plugin grafana

Provisioning Options

Flag	Description	Example
-device	Target device path	/dev/disk2, /dev/sdb
-device-type	Device type (auto-detected if omitted)	rpi, dietpi, esp32
-name	Device hostname	rpi-node-01
-wifi-ssid	WiFi network name	MyNetwork
-wifi-pass	WiFi password	password123
-ssh-key	SSH public key file	~/.ssh/id_rsa.pub
-fleet-server	Fleet server URL	https://fleet.local:8080
-plugin	Enable plugin	k3s, docker
-plugin-opt	Plugin configuration	k3s.role=server
-verbose	Verbose output	-
-dry-run	Preview without writing	-

After Provisioning

1. Insert the SD card into your Raspberry Pi and power it on

2. Wait for boot (typically 2-3 minutes for first boot)

3. Device discovery: The device will automatically:

   • Connect to WiFi (if configured)
   • Start the fleetd agent
   • Register with the fleet server via mDNS discovery
   • Begin reporting telemetry

4. Access the device (if SSH was enabled):

   ssh pi@<device-ip>
   # or if you set a custom name
   ssh pi@rpi-workshop-01.local

5. Verify k3s (if installed):

   ssh pi@<device-ip>
   sudo k3s kubectl get nodes

Troubleshooting

• Device not listed: Ensure the SD card is properly connected and unmounted
• Permission denied: Run with sudo on Linux/macOS
• WiFi not connecting: Verify SSID and password, check 2.4GHz compatibility
• k3s issues: Check logs with sudo journalctl -u k3s
• mDNS discovery: Ensure devices are on the same network segment