Service Deployment

This guide covers deploying aranet-service as a persistent background service on various platforms.

Deployment Options

Platform	Service Manager	Config Location
macOS	launchd	~/Library/LaunchAgents/
Linux	systemd	/etc/systemd/system/
Docker	docker-compose	Container orchestration
Windows	NSSM	Windows Service

macOS (launchd)

User-Level Service

1. Install aranet-service

   cargo install aranet-service --features full

2. Install as user service

   aranet-service service install --user

3. Start the service

   aranet-service service start --user

4. Check status

   aranet-service service status --user

Manual Configuration

Create ~/Library/LaunchAgents/dev.rye.aranet.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>dev.rye.aranet</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/aranet-service</string>
        <string>run</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/usr/local/var/log/aranet.log</string>
    <key>StandardErrorPath</key>
    <string>/usr/local/var/log/aranet.err</string>
    <key>WorkingDirectory</key>
    <string>/usr/local/var/aranet</string>
</dict>
</plist>

Load the service:

launchctl load ~/Library/LaunchAgents/dev.rye.aranet.plist

Linux (systemd)

System-Level Service

1. Build and install

   cargo build --release -p aranet-service --features full
   sudo cp target/release/aranet-service /usr/local/bin/

2. Create service user

   sudo useradd -r -s /bin/false aranet
   sudo mkdir -p /var/lib/aranet
   sudo chown aranet:aranet /var/lib/aranet

3. Install the service file

   aranet-service service install
   # Or manually: sudo cp distribution/systemd/aranet.service /etc/systemd/system/

4. Enable and start

   sudo systemctl daemon-reload
   sudo systemctl enable --now dev.rye.aranet

Service File

Create /etc/systemd/system/aranet.service:

[Unit]
Description=Aranet Sensor Collector Service
Documentation=https://github.com/cameronrye/aranet
After=network-online.target bluetooth.target
Wants=network-online.target

[Service]
Type=simple
User=aranet
Group=aranet
ExecStart=/usr/local/bin/aranet-service run
Restart=on-failure
RestartSec=5
StartLimitIntervalSec=60
StartLimitBurst=3

# Paths
WorkingDirectory=/var/lib/aranet
ReadWritePaths=/var/lib/aranet

# Security hardening
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
NoNewPrivileges=true

# Bluetooth access
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW

[Install]
WantedBy=multi-user.target

User-Level Service

# Create user service directory
mkdir -p ~/.config/systemd/user

# Copy service file
cp distribution/systemd/aranet.service ~/.config/systemd/user/

# Edit to remove User/Group and adjust paths
# Then enable
systemctl --user daemon-reload
systemctl --user enable --now dev.rye.aranet

Docker

A multi-stage Dockerfile and docker-compose.yml are provided at the repository root. BLE access requires privileged mode and D-Bus passthrough.

Quick Start

8080/dashboard

# Standalone service with BLE
docker compose up -d

Full Monitoring Stack

Use the docker/ directory for a Prometheus + Grafana stack:

docker compose -f docker/docker-compose.yml up -d

Build from Source

docker build -t aranet-service .
docker run -d --name aranet-service \
  --privileged --network host \
  -v /var/run/dbus:/var/run/dbus \
  -v aranet-data:/data \
  -v ./server.toml:/app/server.toml:ro \
  -e RUST_LOG=aranet_service=info \
  aranet-service

Production Deployment

docker-compose.prod.yml

services:
  aranet-service:
    build: .
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - aranet-data:/data
      - ./server.toml:/app/server.toml:ro
      - /var/run/dbus:/var/run/dbus
    privileged: true
    network_mode: host
    environment:
      - RUST_LOG=aranet_service=info
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s

volumes:
  aranet-data:

Caution

Docker containers cannot access Bluetooth by default. BLE support requires privileged mode with D-Bus socket passthrough (/var/run/dbus) and host networking.

Configuration

Server Configuration

Create ~/.config/aranet/server.toml:

[server]
bind = "127.0.0.1:8080"

[storage]
path = "~/.local/share/aranet/data.db"

[prometheus]
enabled = true

[[devices]]
address = "Aranet4 XXXXX"
alias = "office"
poll_interval = 60

Security Configuration

For production deployments, enable API authentication and rate limiting:

[security]
api_key_enabled = true
api_key = "your-secure-random-key-at-least-32-chars"
rate_limit_enabled = true
rate_limit_requests = 100
rate_limit_window_secs = 60

See API Security for detailed configuration.

Webhook Notifications

Configure HTTP POST alerts when sensor thresholds are exceeded:

[webhooks]
enabled = true
co2_threshold = 1000        # ppm
radon_threshold = 300       # Bq/m³
battery_threshold = 10      # percent
cooldown_secs = 300         # seconds between repeat alerts per device

[[webhooks.endpoints]]
url = "https://hooks.slack.com/services/T00/B00/xxx"
events = ["co2_high", "radon_high", "battery_low"]

[[webhooks.endpoints]]
url = "https://ntfy.sh/my-aranet-alerts"
events = ["co2_high"]
headers = { "Authorization" = "Bearer tk_xxx" }

Each webhook POST sends a JSON payload:

{
  "event": "co2_high",
  "device_id": "Aranet4 AAAAA",
  "alias": "office",
  "value": 1200.0,
  "threshold": 1000.0,
  "unit": "ppm",
  "reading": { ... },
  "timestamp": "2026-03-28T12:00:00Z"
}

Valid event types: co2_high, radon_high, battery_low.

InfluxDB Export

Export sensor readings to InfluxDB v2 in real time:

[influxdb]
enabled = true
url = "http://localhost:8086"
token = "your-influxdb-token"
org = "my-org"
bucket = "aranet"
measurement = "aranet"
precision = "s"             # s, ms, us, or ns

Data is written using the InfluxDB v2 line protocol: aranet,device=office,address=Aranet4+AAAAA co2=450i,temperature=22.50,humidity=45i,pressure=1013.50,battery=85i.

mDNS Service Discovery

When running, aranet-service automatically advertises itself on the local network via mDNS:

• Service type: _aranet._tcp.local.
• HTTP service: _http._tcp.local.
• Properties: version, path (/api), dashboard (/dashboard)

Clients can discover the service without manual IP configuration:

# macOS
dns-sd -B _aranet._tcp local.

# Linux (avahi)
avahi-browse -r _aranet._tcp

Grafana Dashboard

A pre-built Grafana dashboard is included at grafana/aranet-dashboard.json. To import:

1. Open Grafana and navigate to Dashboards > Import
2. Click Upload JSON file and select grafana/aranet-dashboard.json
3. Select your Prometheus data source and click Import

The dashboard includes panels for:

• CO₂ gauges with threshold coloring
• Environment time series (temperature, humidity, pressure)
• Radon and radiation displays
• Battery levels per device
• Collector statistics (poll success/failure, duration)

Environment Variables

# Log level
export RUST_LOG=aranet_service=info

# Config file location
export ARANET_CONFIG=/path/to/server.toml

Prometheus Integration

Scrape Configuration

Add to prometheus.yml:

scrape_configs:
  - job_name: 'aranet'
    static_configs:
      - targets: ['localhost:8080']
    metrics_path: /metrics
    scrape_interval: 60s

Available Metrics

Metric	Type	Description
aranet_co2_ppm	gauge	CO₂ concentration
aranet_temperature_celsius	gauge	Temperature
aranet_humidity_percent	gauge	Relative humidity
aranet_pressure_hpa	gauge	Atmospheric pressure
aranet_battery_percent	gauge	Battery level
aranet_reading_age_seconds	gauge	Time since last reading
aranet_collector_running	gauge	Collector status (1/0)
aranet_collector_uptime_seconds	gauge	Collector uptime
aranet_device_poll_success_total	counter	Successful polls
aranet_device_poll_failure_total	counter	Failed polls
aranet_device_poll_duration_ms	gauge	Per-device poll duration

Multi-Device Setup

Multiple Sensors

Configure multiple devices in server.toml:

[[devices]]
address = "Aranet4 AAAAA"
alias = "office"
poll_interval = 60

[[devices]]
address = "Aranet4 BBBBB"
alias = "bedroom"
poll_interval = 120

[[devices]]
address = "Aranet4 CCCCC"
alias = "kitchen"
poll_interval = 60

[[devices]]
address = "AranetRn+ DDDDD"
alias = "basement"
poll_interval = 300  # Radon updates slowly

Multi-Location Deployment

For sensors spread across multiple locations:

1. Option A: Central collector - One aranet-service with MQTT forwarding
2. Option B: Distributed collectors - Multiple aranet-service instances pushing to central Prometheus

┌─────────────────┐     ┌─────────────────┐
│ Location A      │     │ Location B      │
│ aranet-service  │────▶│ aranet-service  │
│ :8080           │     │ :8080           │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └──────────┬────────────┘
                    ▼
           ┌────────────────┐
           │   Prometheus   │
           │   (Central)    │
           └───────┬────────┘
                   │
                   ▼
           ┌────────────────┐
           │    Grafana     │
           └────────────────┘

Monitoring & Logging

View Logs

# systemd
journalctl -u aranet -f

# launchd
tail -f /usr/local/var/log/aranet.log

# Docker
docker logs -f aranet-service

Health Check

# Basic health check
curl http://localhost:8080/api/health
# {"status":"ok","version":"0.2.0","timestamp":"2026-03-28T10:30:00Z"}

# Detailed health check with diagnostics
curl http://localhost:8080/api/health/detailed
# Returns database, collector, and platform diagnostics

Prometheus Metrics

curl http://localhost:8080/metrics

Troubleshooting

Service Won’t Start

1. Check logs for errors
2. Verify configuration file syntax: toml-cli check server.toml
3. Ensure Bluetooth permissions (Linux: CAP_NET_ADMIN)

No Bluetooth Access

• Linux: Add user to bluetooth group: sudo usermod -aG bluetooth $USER
• macOS: Grant Bluetooth permission in System Preferences
• Docker: Run with --privileged or mount /var/run/dbus

Connection Timeouts

1. Check device is powered on and in range
2. Increase poll_interval (device may be busy)
3. Verify no other app is connected to the device