/
VibCloud Edge Service - installation, update & uninstallation guide

VibCloud Edge Service - installation, update & uninstallation guide

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

Overview

The VibCloud Edge Service is a lightweight daemon that runs on a Raspberry Pi and acts as the bridge between the BluVib local sensor gateway and the VibCloud cloud platform. It handles:

  • Sensor configuration sync - pulls the latest sensor settings from VibCloud

  • Continuous data upload - compresses and uploads sensor readings with automatic retry

  • Health monitoring - watchdog integration with automatic thread and service recovery

  • Web management UI - browser-based dashboard at http://<pi-ip>:5000

  • CLI control - manage the service from the terminal with vibcloud-ctl

Prerequisites

Before running the installer, confirm the following:

Requirement

Notes

Requirement

Notes

Raspberry Pi running Raspberry Pi OS

Bookworm or later recommended

Python 3.7 or newer

Check with python3 --version

Internet connectivity

Required to download the package and reach the VibCloud API

Local sensor gateway

Reachable on the network (default: http://localhost:8080/)

VibCloud account

You will need your API key and Client ID

GitHub personal access token

Must have repo scope - used to download the private package

Note: Do not run the installer as root. Run it as the user who will own the service (typically pi).

Installation

Step 1 - Run the installer

Replace YOUR_TOKEN with GitHub token (iTnnovate provided) and YOUR_CLIENT_ID with the Client ID provided by VibCloud:

VIBCLOUD_GITHUB_TOKEN=YOUR_TOKEN VIBCLOUD_CLIENT_ID=YOUR_CLIENT_ID \ bash <(curl -sSL -H "Authorization: token YOUR_TOKEN" \ 'https://raw.githubusercontent.com/iTnnovate/vibcloud-edge-gateway/main/install.sh')

The installer will:

  1. Verify Python 3.7+ is present

  2. Install system packages: python3-pip, python3-venv, git

  3. Create the installation directory at ~/vibcloud-service/

  4. Create a Python virtual environment

  5. Download and install the vibcloud-edge-gateway package from GitHub

  6. Create systemd service files (vibcloud.service and optionally vibcloud-web.service)

  7. Symlink CLI tools to /usr/local/bin/vibcloud-ctl and /usr/local/bin/vibcloud-web

  8. Save your GitHub token securely at ~/.config/vibcloud/github_token for future upgrades

Step 2 - Configure your .env file

The installer creates ~/vibcloud-service/.env. Open it and verify the following required settings:

nano ~/vibcloud-service/.env

Setting

Description

Example

Setting

Description

Example

CLIENT_ID

Your unique gateway identifier (set by installer)

207

SENSOR_API_URL

Local sensor gateway URL

http://localhost:8080/

CLOUD_API_URL

VibCloud cloud API endpoint

Provided by VibCloud

CLOUD_API_KEY

Your VibCloud API key

Provided by VibCloud

SENSOR_SCHEDULE_MIN

How often to collect sensor data (minutes)

10

Optional tuning settings:

Setting

Default

Description

Setting

Default

Description

UPLOAD_INTERVAL_SECONDS

60

How often to upload data

UPLOAD_BATCH_SIZE

10

Sensors uploaded per batch

LOG_LEVEL

INFO

Logging verbosity (DEBUG, INFO, WARNING)

SSL_VERIFY

true

Enable SSL certificate verification

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

Step 3 - Sync sensors and start the service

# Pull sensor list from VibCloud vibcloud-ctl sync # Enable auto-start on boot sudo systemctl enable vibcloud # Start the service sudo systemctl start vibcloud # Confirm it is running vibcloud-ctl status

Step 4 - (Optional) Start the web interface

If you installed the vibcloud-web service during setup:

sudo systemctl enable vibcloud-web sudo systemctl start vibcloud-web

Then open a browser and navigate to http://<raspberry-pi-ip>:5000.

If the web service was not installed, you can start it manually:

vibcloud-web

Verifying the Installation

# Check overall status and last sync/upload times vibcloud-ctl status # View per-component health vibcloud-ctl health # List discovered sensors vibcloud-ctl sensors # Monitor live logs vibcloud-ctl logs # or via systemd journal: sudo journalctl -u vibcloud -f

A healthy output from vibcloud-ctl health looks like:

============================================================ VibCloud Service Health Check ============================================================ āœ… Overall: HEALTHY Uptime: 2:14:03 Last heartbeat: 2026-04-17T10:30:00 šŸ“‹ Components (3): āœ… main_loop: healthy āœ… upload_worker: healthy āœ… database: healthy

Updating

When a new version of the VibCloud Edge Service is released, run the installer again. It will detect the installed version, back up your data, upgrade the package, and restart the service.

Run the upgrade

Your GitHub token is saved from the initial install, so no manual token entry is required:

bash <(curl -sSL -H "Authorization: token $(cat ~/.config/vibcloud/github_token)" \ 'https://raw.githubusercontent.com/iTnnovate/vibcloud-edge-gateway/main/install.sh')

What the upgrade does

  1. Detects the currently installed version

  2. Prompts for confirmation before proceeding

  3. Stops the running services

  4. Creates a timestamped backup at ~/vibcloud-service/.backup-<timestamp>/ containing:

    • .env (your configuration)

    • vibcloud.db (sensor database)

    • service_state.json

    • healthcheck.json

  5. Downloads and installs the new package version

  6. Preserves your .env ā€” no re-configuration needed

  7. Restarts services that were enabled

After upgrading

vibcloud-ctl status vibcloud-ctl health

Confirm the new version is shown and all components report healthy.

Uninstallation

Automated uninstall

bash <(curl -sSL -H "Authorization: token $(cat ~/.config/vibcloud/github_token)" \ 'https://raw.githubusercontent.com/iTnnovate/vibcloud-edge-gateway/main/uninstall.sh')

The uninstall script will:

  1. Stop and disable the vibcloud and vibcloud-web services

  2. Remove systemd service files from /etc/systemd/system/

  3. Remove CLI tools from /usr/local/bin/

  4. Remove the saved GitHub token from ~/.config/vibcloud/

  5. Create a final backup at ~/vibcloud-backup-<timestamp>/ containing your configuration and data

  6. Prompt you to confirm deletion of the ~/vibcloud-service/ directory

Manual uninstall

If the script is not available, these commands perform a complete removal:

# Stop and disable services sudo systemctl stop vibcloud vibcloud-web sudo systemctl disable vibcloud vibcloud-web # Remove service files sudo rm -f /etc/systemd/system/vibcloud.service sudo rm -f /etc/systemd/system/vibcloud-web.service sudo systemctl daemon-reload # Remove CLI tools sudo rm -f /usr/local/bin/vibcloud-ctl sudo rm -f /usr/local/bin/vibcloud-web # Remove installation directory (this deletes all data ā€” back up first) rm -rf ~/vibcloud-service # Remove saved token rm -rf ~/.config/vibcloud

File & Directory Reference

~/vibcloud-service/ ā€” Installation root ā”œā”€ā”€ venv/ ā€” Python virtual environment ā”œā”€ā”€ logs/ ā€” Rotating log files (max ~45 MB total) ā”‚ ā”œā”€ā”€ vibcloud_service.log ā”‚ ā”œā”€ā”€ vibcloud_upload.log ā”‚ ā””ā”€ā”€ vibcloud_edge_service.log ā”œā”€ā”€ .env ā€” Configuration file (chmod 600) ā”œā”€ā”€ .env.example ā€” Configuration template ā”œā”€ā”€ .version ā€” Version marker ā”œā”€ā”€ vibcloud.db ā€” SQLite sensor database ā”œā”€ā”€ service_state.json ā€” Persistent service state ā””ā”€ā”€ healthcheck.json ā€” Watchdog heartbeat file /etc/systemd/system/ ā”œā”€ā”€ vibcloud.service ā€” Main daemon service ā””ā”€ā”€ vibcloud-web.service ā€” Web interface service (optional) /usr/local/bin/ ā”œā”€ā”€ vibcloud-ctl ā€” CLI management tool ā””ā”€ā”€ vibcloud-web ā€” Web server launcher ~/.config/vibcloud/github_token ā€” Saved GitHub token (chmod 600)

CLI Quick Reference

Command

Description

Command

Description

vibcloud-ctl status

Show service status, last sync, last upload

vibcloud-ctl health

Detailed per-component health check

vibcloud-ctl sensors

List all sensors and their state

vibcloud-ctl sync

Pull latest sensor configuration from VibCloud

vibcloud-ctl upload

Trigger an immediate upload cycle

vibcloud-ctl logs

View recent log output

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

vibcloud-ctl clean-db

Reset the sensor database (data loss ā€” use with caution)

Troubleshooting

Service not starting

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

Look for errors related to missing .env values or network connectivity.

Sensors not appearing after sync

  • Confirm SENSOR_API_URL points to a reachable gateway: curl http://localhost:8080/

  • Confirm CLOUD_API_KEY and CLIENT_ID in .env are correct

  • Re-run vibcloud-ctl sync and check vibcloud-ctl sensors

Uploads stalled

vibcloud-ctl health

If upload_worker shows degraded or unhealthy, check internet connectivity and cloud API URL.

Web interface not accessible

  • Confirm the service is running: sudo systemctl status vibcloud-web

  • Check that port 5000 is not blocked by a firewall: sudo ufw allow 5000/tcp

Log disk usage growing unexpectedly Logs rotate automatically at 5 MB with 3 backups (~45 MB total). If usage is higher, check for third-party log shippers duplicating the logs.