VibCloud Edge Service - usage & maintenance guide

Product: VibCloud Edge Service Platform: Raspberry Pi OS (Debian-based) Current Version: 1.2.1 Audience: System administrators / site technicians

Overview

This guide covers the day-to-day operation and ongoing maintenance of the VibCloud Edge Service once it is installed. For installation, update, and uninstallation steps, see the VibCloud Edge Service - usage & maintenance guide.

VibCloud data flow

How the service works

Understanding the service lifecycle helps with troubleshooting and maintenance.

Boot
 └─ systemd starts vibcloud.service
      └─ Daemon loads .env configuration
           ├─ Initialises SQLite database
           ├─ Registers health components
           ├─ Starts config file watcher (.env hot-reload)
           ├─ Triggers first sensor sync from VibCloud
           ├─ Starts upload worker (once sensors are configured)
           └─ Main loop (every ~5 s)
                ├─ Sends watchdog ping to systemd
                ├─ Checks per-component health
                ├─ Restarts stalled threads automatically
                └─ Sends error batch report (per ERROR_REPORT_INTERVAL_MINUTES)

Key automatic behaviours:

Behaviour	Trigger	Interval

Behaviour	Trigger	Interval
Sensor configuration sync	Startup + timer	Every `SENSOR_SYNC_INTERVAL_HOURS` (default: 6 h)
Data upload	Continuous after sensors are configured	Every `UPLOAD_INTERVAL_SECONDS` (default: 60 s)
Error batch report	Automatic	Every `ERROR_REPORT_INTERVAL_MINUTES` (default: 30 min)
Upload thread restart	Upload stalls for > 10 min	Automatic
Full service restart	Watchdog ping missing for > 90 s	Automatic (systemd)
Log rotation	Log file reaches 5 MB	Automatic (3 backups kept, ~45 MB total)
Config reload	`.env` file changes on disk	Automatic (no restart needed)

Service control

Using `vibcloud-ctl` (recommended)

vibcloud-ctl start        # Start the service
vibcloud-ctl stop         # Stop the service
vibcloud-ctl restart      # Restart the service
vibcloud-ctl enable       # Enable auto-start on boot
vibcloud-ctl disable      # Disable auto-start on boot

Using `systemctl` directly

sudo systemctl start vibcloud
sudo systemctl stop vibcloud
sudo systemctl restart vibcloud
sudo systemctl enable vibcloud
sudo systemctl disable vibcloud
sudo systemctl status vibcloud

Web interface service (if installed)

sudo systemctl start vibcloud-web
sudo systemctl stop vibcloud-web
sudo systemctl restart vibcloud-web
sudo systemctl status vibcloud-web

Checking service status

Quick status

vibcloud-ctl status

Example output:

VibCloud Edge Service — Status
──────────────────────────────
Service:        running (PID 1234)
Uptime:         3h 22m 10s
Upload worker:  Active
Last sync:      2026-04-17 08:00:01
Last upload:    2026-04-17 11:21:45
Sensors:        12 configured, 0 pending, 0 failed

Detailed health check

vibcloud-ctl health

Example output:

============================================================
VibCloud Service Health Check
============================================================
✅ Overall: HEALTHY
   Uptime: 3:22:10
   Last heartbeat: 2026-04-17T11:22:00

📋 Components (3):
   ✅ main_loop: healthy
      Last seen: 4.2s ago | Failures: 0
   ✅ upload_worker: healthy
      Last seen: 12.1s ago | Failures: 0
   ✅ database: healthy
      Last seen: 4.2s ago | Failures: 0

Health levels:

Level	Meaning

Level	Meaning
`HEALTHY`	All components operating normally
`DEGRADED`	A non-critical issue is present; service continues
`UNHEALTHY`	A critical component has failed; action required

HTTP health endpoint

Useful for monitoring tools, load balancers, or uptime checkers:

curl -s http://localhost:5000/api/health
# Returns HTTP 200 if healthy, HTTP 503 if unhealthy

Managing sensors

View all sensors

vibcloud-ctl sensors

Shows each sensor with its current state: configured, pending, or failed.

Sync sensor configuration from VibCloud

Pulls the latest sensor list and settings from the VibCloud cloud API:

vibcloud-ctl sync

Sync also runs automatically at startup and every SENSOR_SYNC_INTERVAL_HOURS (default: 6 hours). Run it manually after adding or changing sensors in the VibCloud portal.

Trigger an immediate upload

Forces an upload cycle without waiting for the next scheduled interval:

vibcloud-ctl upload

This runs independently of the background service and can be used to verify connectivity.

Web management interface

If the vibcloud-web service is installed, open a browser and navigate to:

http://<raspberry-pi-ip>:5000

Pages

Page	Description

Page	Description
Dashboard	Service status, upload worker state, sensor list with status badges, action buttons (sync, upload, restart)
Settings	Edit configuration values, toggle auto-start
Logs	Real-time log viewer with level filtering and search

Dashboard

Settings

Logs

API endpoints

These can be called by external scripts or monitoring tools:

Method	Path	Description

Method	Path	Description
`GET`	`/api/status`	Service status and statistics
`GET`	`/api/health`	Health check (200 / 503)
`GET`	`/api/sensors`	Full sensor list
`POST`	`/api/sync`	Trigger sensor sync
`GET`	`/api/logs`	Recent log lines
`GET`	`/api/config`	Read current configuration
`POST`	`/api/config`	Update configuration values
`POST`	`/api/service/<action>`	`start`, `stop`, or `restart` the service
`GET`	`/api/autostart`	Check auto-start status
`POST`	`/api/autostart`	Toggle auto-start

Configuration management

Configuration file location

~/vibcloud-service/.env

Editing configuration

nano ~/vibcloud-service/.env

The service detects .env changes automatically and reloads without a restart. There is no need to run vibcloud-ctl restart after saving the file.

For changes that cannot be hot-reloaded (e.g. changing the database file path), restart the service manually:

vibcloud-ctl restart

Key settings reference

Setting	Default	Description

Setting	Default	Description
`CLIENT_ID`	(set at install)	Unique gateway identifier — do not change
`SENSOR_API_URL`	`http://localhost:8080/`	Local sensor gateway URL
`CLOUD_API_URL`	(provided by VibCloud)	VibCloud cloud API endpoint
`CLOUD_API_KEY`	(provided by VibCloud)	API authentication key
`SENSOR_SCHEDULE_MIN`	`10`	Sensor data collection interval (minutes)
`UPLOAD_INTERVAL_SECONDS`	`60`	Data upload frequency
`UPLOAD_BATCH_SIZE`	`10`	Sensors uploaded per batch
`MAX_UPLOAD_RETRIES`	`3`	Retry attempts per upload
`SENSOR_SYNC_INTERVAL_HOURS`	`6`	Auto-sync interval
`ERROR_REPORT_INTERVAL_MINUTES`	`30`	Error batch report frequency
`LOG_LEVEL`	`INFO`	Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`CONNECTION_TIMEOUT`	`30`	API request timeout (seconds)
`SSL_VERIFY`	`true`	Enable SSL certificate verification

Security note: .env is protected with chmod 600. Do not share it or add it to version control.

Viewing logs

Via CLI (recommended)

vibcloud-ctl logs

Supports level filtering and search within the viewer.

Via systemd journal

# Live tail
sudo journalctl -u vibcloud -f

# Last 100 lines
sudo journalctl -u vibcloud -n 100 --no-pager

# Logs from the last hour
sudo journalctl -u vibcloud --since "1 hour ago"

# Web service logs
sudo journalctl -u vibcloud-web -f

Log files on disk

Located at ~/vibcloud-service/logs/:

File	Contents

File	Contents
`vibcloud_service.log`	Main daemon activity
`vibcloud_upload.log`	Upload worker activity
`vibcloud_edge_service.log`	Sensor manager activity

Logs rotate automatically at 5 MB with 3 backups kept (~45 MB total across all files).

Increasing log verbosity for debugging

In ~/vibcloud-service/.env:

LOG_LEVEL=DEBUG

The service reloads this automatically. Revert to INFO once debugging is complete to avoid excessive disk usage.

Database maintenance

The service uses a SQLite database at ~/vibcloud-service/vibcloud.db to store sensor state, configuration history, and internal application logs.

When to reset the database

After a major sensor reconfiguration where stale records are causing errors
When advised by VibCloud support
Before decommissioning the device

Reset the database

Warning: This wipes all sensor data. The schema is preserved but all records are deleted. Back up the database file first.

# Back up first
cp ~/vibcloud-service/vibcloud.db ~/vibcloud-service/vibcloud.db.bak

# Reset
vibcloud-ctl clean-db

# Re-sync sensors from VibCloud
vibcloud-ctl sync

Backing Up service data

Back up these files before any major change (update, reconfiguration, migration):

# Create a timestamped backup directory
BACKUP_DIR=~/vibcloud-backup-$(date +%Y%m%d-%H%M%S)
mkdir -p "$BACKUP_DIR"

# Copy key files
cp ~/vibcloud-service/.env "$BACKUP_DIR/"
cp ~/vibcloud-service/vibcloud.db "$BACKUP_DIR/"
cp ~/vibcloud-service/service_state.json "$BACKUP_DIR/"
cp ~/vibcloud-service/healthcheck.json "$BACKUP_DIR/"
cp -r ~/vibcloud-service/logs "$BACKUP_DIR/"

echo "Backup saved to $BACKUP_DIR"

The update script creates this backup automatically before upgrading.

Restoring from backup

# Stop the service first
vibcloud-ctl stop

# Restore files
cp /path/to/backup/.env ~/vibcloud-service/.env
cp /path/to/backup/vibcloud.db ~/vibcloud-service/vibcloud.db
cp /path/to/backup/service_state.json ~/vibcloud-service/service_state.json

# Start the service
vibcloud-ctl start
vibcloud-ctl health

Routine maintenance checklist

Recommended actions on a regular schedule:

Weekly

vibcloud-ctl status — confirm service is running and uploads are current
vibcloud-ctl health — confirm all components are healthy
vibcloud-ctl sensors — confirm no sensors are in a persistent failed state
Review vibcloud-ctl logs for recurring warnings or errors

Monthly

Check disk usage: du -sh ~/vibcloud-service/
Check for a new version of the service and apply the update if available
Verify backup files are present and non-empty
Confirm auto-start is still enabled: sudo systemctl is-enabled vibcloud

After any sensor change in the VibCloud portal

vibcloud-ctl sync — pull updated sensor configuration
vibcloud-ctl sensors — confirm the new sensors appear correctly

Troubleshooting

Service is not running

sudo systemctl status vibcloud
sudo journalctl -u vibcloud -n 50 --no-pager

Common causes: invalid .env value, local sensor gateway unreachable, Python environment corrupted.

Upload worker is stalled

vibcloud-ctl health

If upload_worker is degraded or unhealthy:

Check internet connectivity: ping 8.8.8.8
Verify CLOUD_API_URL and CLOUD_API_KEY in .env
Trigger a manual upload to see the error: vibcloud-ctl upload
If the thread does not self-recover within 10 minutes, restart: vibcloud-ctl restart

Sensors stuck in "pending" or "failed" state

vibcloud-ctl sensors
vibcloud-ctl sync

If sensors remain failed after a sync:

Confirm the local gateway is reachable: curl http://localhost:8080/
Check SENSOR_API_URL in .env
Review logs for per-sensor error messages: vibcloud-ctl logs

Web interface not accessible

sudo systemctl status vibcloud-web

If the service is running but the page does not load:

Confirm the port is not blocked: sudo ufw allow 5000/tcp
Confirm you are using the correct IP address of the Raspberry Pi
Try accessing locally on the Pi: curl http://localhost:5000/api/health

Configuration changes not taking effect

The service watches .env and reloads automatically within a few seconds. If changes are not reflected:

Wait 10–15 seconds and re-check
Confirm there are no syntax errors in .env (keys must use KEY=VALUE format, no quotes needed for simple values)
Restart the service manually: vibcloud-ctl restart

Log disk usage is unexpectedly high

Logs rotate at 5 MB with 3 backups. If usage is much higher:

ls -lh ~/vibcloud-service/logs/

Check whether LOG_LEVEL=DEBUG has been left on. Reset it to INFO in .env.

Service auto-recovery behaviour

The service is designed to recover from most failures automatically. This table summarises the recovery mechanisms:

Failure	Recovery mechanism	Time to recovery

Failure	Recovery mechanism	Time to recovery
Upload thread hangs	Daemon restarts the thread	Up to 10 min
Daemon process crashes	systemd `Restart=always`	~10 s
Daemon stops sending watchdog pings	systemd WatchdogSec=90	~90 s
`.env` changed	Config watcher reloads in place	Seconds
Service crashes repeatedly (> 5 times / 200 s)	systemd stops retrying; manual intervention required	N/A

If the service enters the last state, check logs for the root cause before attempting to restart:

sudo journalctl -u vibcloud --since "10 minutes ago"
vibcloud-ctl start