Server Configuration — ControlFloor Docs

Overview

The ControlFloor Server is the central coordination component. Written in Go with an embedded SQLite database, it manages authentication, device inventory, provider registration, session state, and serves the web dashboard. No external database server or additional services are required.

config.json Reference

The Server is configured via ~/cf/server/config.json.

Field	Type	Description
listen	string	Listen address and port (e.g., `":8080"` for all interfaces)
https	bool	Enable HTTPS (TLS encryption)
crt	string	Path to TLS certificate file (optional; auto-generates self-signed if omitted)
key	string	Path to TLS private key file
sessionTimeout	int	Session timeout in minutes (default: 60)
exclusiveTimeout	int	Exclusive access timeout in minutes
videoDisplay	string	Video display mode (`"vidstream"` or `"screenshot"`)
zabbix.enabled	bool	Enable Zabbix monitoring integration
zabbix.server	string	Zabbix server address
zabbix.host	string	Host name as registered in Zabbix
logLevel	string	Logging verbosity (`"debug"`, `"info"`, `"warn"`, `"error"`)

Example Configuration

{
  "listen": ":8080",
  "https": true,
  "crt": "/etc/letsencrypt/live/cf.example.com/fullchain.pem",
  "key": "/etc/letsencrypt/live/cf.example.com/privkey.pem",
  "sessionTimeout": 120,
  "videoDisplay": "vidstream",
  "logLevel": "info"
}

HTTPS Setup

Self-Signed Certificate (Default)

With "https": true and no crt/key paths, the server generates a self-signed certificate on first run. The certificate files are saved to ~/cf/server/server.crt and ~/cf/server/server.key.

Clients and Providers connecting to the server will need to accept the self-signed certificate (set selfSigned: true in Provider config).

Custom Certificate

Provide paths to your own certificate and key:

{
  "https": true,
  "crt": "/path/to/fullchain.pem",
  "key": "/path/to/privkey.pem"
}

Let's Encrypt

Point to your Let's Encrypt certificate files. Set up a cron job or certbot timer to handle renewal, and restart the server when certificates are updated.

User Management

Manage users via the server CLI. The admin account is created during initial setup.

# Create a new user
$ ./cfserver create-user -username alice

# Change a user's password
$ ./cfserver modify-user -username alice -change-password

# Delete a user
$ ./cfserver delete-user -username alice

# Change the admin password
$ ./cfserver modify-user -username admin -change-password

Bearer Token Authentication

Bearer tokens enable stateless API access, ideal for CI/CD pipelines and automation scripts that need to authenticate without interactive login.

# Generate a bearer token
$ ./cfserver generate-token -username admin

Use the token in API requests:

$ curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://server:8080/api/devices

Session Configuration

Sessions control how users interact with devices through the web dashboard.

Session timeout — How long a session persists after the last activity
Exclusive access — Prevents other users from controlling a device while one user has it claimed
Exclusive timeout — Automatically releases exclusive access after inactivity

Video Display Options

The videoDisplay setting controls how device screens are shown in the web dashboard:

"vidstream" — Uses the VidStream broadcast extension for high-quality, low-latency video. Recommended for most use cases.
"screenshot" — Uses XCTest screenshot-based streaming. Simpler setup (no VidStream app needed) but lower frame rate.

Zabbix Integration

ControlFloor integrates with Zabbix for enterprise-grade monitoring. Enable it in config.json:

{
  "zabbix": {
    "enabled": true,
    "server": "zabbix.internal:10051",
    "host": "controlfloor-prod"
  }
}

The server sends device health metrics, session counts, and alert data to Zabbix for dashboarding and alerting.

Monitoring and Metrics

The Server provides JSON API endpoints for monitoring:

/api/devices — List all devices with status
/api/providers — List all registered providers
/api/sessions — Active session information

These endpoints can be used with bearer token authentication for integration with custom monitoring dashboards, CI/CD systems, or alerting tools.