Skip to content

INSTALLATION.md

Latest commit

 

History

History
287 lines (208 loc) · 8.76 KB

INSTALLATION.md

File metadata and controls

287 lines (208 loc) · 8.76 KB
Raw

Installation guide

OwnNode Agent supports Raspberry Pi OS and other Debian-based systems with Python 3.11 or newer. Installing from the OwnNode APT repository is recommended: APT verifies signed repository metadata and provides normal upgrades through apt upgrade.

The product was previously named PiStats. The package, service, configuration directory, and environment variables retain their existing pistats identifiers. The repository rename changes only the APT URL; existing users can migrate it with the command below without reinstalling the service.

Before you install

You need:

  • a Raspberry Pi running a supported Debian-based OS;
  • a non-root account with sudo access;
  • network access to GitHub Pages and Debian package mirrors; and
  • Tailscale on the Pi and Android device if the app will connect remotely.

The service is private by default: it binds to 127.0.0.1:8787, generates a unique bearer token, and enables no Docker services, media paths, backup drives, or Wake-on-LAN hardware automatically.

Recommended: install with APT

Install the public archive key:

curl -fsSL https://zendeveloper7.github.io/OwnNode-Agent/apt/pistats-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/pistats-archive-keyring.gpg >/dev/null

The expected signing-key fingerprint is:

B2E8 ED59 05E0 ECDF 7D46 7224 DCA1 E5E6 984B 664E

You can verify the downloaded key before trusting it:

gpg --show-keys --with-fingerprint \
  /usr/share/keyrings/pistats-archive-keyring.gpg

Add the repository and install OwnNode Agent:

echo "deb [signed-by=/usr/share/keyrings/pistats-archive-keyring.gpg] https://zendeveloper7.github.io/OwnNode-Agent/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/pistats.list >/dev/null

sudo apt update
sudo apt install pistats-backend

The package starts pistats-backend.service and creates a configuration file at /etc/pistats/pistats.env.

Migrate an existing APT installation

If /etc/apt/sources.list.d/pistats.list uses the previous PiStats-Backend URL, update it once:

sudo sed -i 's|zendeveloper7.github.io/PiStats-Backend/apt|zendeveloper7.github.io/OwnNode-Agent/apt|' \
  /etc/apt/sources.list.d/pistats.list
sudo apt update
sudo apt install --only-upgrade pistats-backend

This changes only the package source URL. It does not replace the token, configuration, transaction state, or media-backup database.

Alternative: install a downloaded .deb

Download pistats-backend_1.4.3_all.deb and SHA256SUMS from the v1.4.3 release, verify the package, and install it:

sha256sum --check --ignore-missing SHA256SUMS
sudo apt install ./pistats-backend_1.4.3_all.deb

This installs the same package, but future releases are not discovered automatically unless you also configure the APT repository.

Configure the service

Read the generated token:

sudo sed -n 's/^PISTATS_TOKEN=//p' /etc/pistats/pistats.env

Edit the configuration:

sudoedit /etc/pistats/pistats.env

For Android access over Tailscale, set:

PISTATS_BIND_MODE=tailscale
PISTATS_PORT=8787

If automatic Tailscale address discovery is unavailable, also set:

PISTATS_TAILSCALE_IP=100.x.y.z

Apply configuration changes:

sudo systemctl restart pistats-backend
sudo systemctl status pistats-backend --no-pager

Enter the resulting http://100.x.y.z:8787 base URL and generated token in the OwnNode Android app. Do not expose this HTTP service directly to the public internet; use Tailscale or another trusted private network.

Verify the installation

Load the token without printing it and call the API locally:

PISTATS_TOKEN="$(sudo sed -n 's/^PISTATS_TOKEN=//p' /etc/pistats/pistats.env)"
curl -H "Authorization: Bearer ${PISTATS_TOKEN}" \
  http://127.0.0.1:8787/api/health

For a Tailscale-bound service, replace 127.0.0.1 with the Pi's Tailscale IP. View service logs with:

sudo journalctl -u pistats-backend -n 100 --no-pager

Optional Docker monitoring

Allow the dedicated service account to inspect Docker, then restart it. The Android app will discover the containers and let each user select which ones to monitor:

sudo usermod -aG docker pistats
sudo systemctl restart pistats-backend

Membership in the Docker group is effectively root-level access. Enable it only when Docker monitoring is required.

PISTATS_SERVICES remains available only as a compatibility fallback for older clients. New installations should make monitoring selections in the app.

Optional Wake-on-LAN

Add the target computer's settings:

PISTATS_WAKE_MAC=00:11:22:33:44:55
PISTATS_WAKE_BROADCAST=192.168.1.255
PISTATS_WAKE_PORT=9

The package and install script also configure a private, service-writable PISTATS_WAKE_STATE_FILE. The Android app uses it through the authenticated settings API, so enable/disable changes survive backend restarts. Keep the MAC, broadcast address, and port in this Pi-side environment file.

Restart the service and test it:

sudo systemctl restart pistats-backend
PISTATS_TOKEN="$(sudo sed -n 's/^PISTATS_TOKEN=//p' /etc/pistats/pistats.env)"
curl -X POST -H "X-Wake-Token: ${PISTATS_TOKEN}" \
  http://127.0.0.1:8787/api/wakeonlan/wake
curl -X PUT -H "Authorization: Bearer ${PISTATS_TOKEN}" \
  -H 'Content-Type: application/json' -d '{"enabled":false}' \
  http://127.0.0.1:8787/api/wakeonlan/settings

Optional media backup

Create a group shared by OwnNode Agent and Samba, then create the library and private state parent on the same filesystem:

sudo groupadd --force media-backup
sudo usermod -aG media-backup pistats
sudo install -d -o root -g media-backup -m 2770 /srv/media/mobile-backups
sudo install -d -o pistats -g media-backup -m 0750 \
  /srv/media/.pistats-media-state

Enable the endpoint in /etc/pistats/pistats.env:

PISTATS_MEDIA_BACKUP_ROOT=/srv/media/mobile-backups
PISTATS_MEDIA_BACKUP_MAX_BYTES=1073741824
PISTATS_MEDIA_BACKUP_READ_TIMEOUT_SECONDS=300

The default temporary files and SQLite database are kept in a root-specific subdirectory under /srv/media/.pistats-media-state. Incomplete uploads remain outside the shared library and are removed periodically. Custom media, database, and temporary paths may use any writable absolute location accessible to the pistats service account. See the media backup API for the complete protocol.

Optional Actual Budget transaction sync

Install the matching official Actual API client, create explicit sender/account mappings, and add the private integration settings described in Actual Budget transaction sync. OwnNode Agent only imports approved normalized transactions; it never starts or stops Actual Budget.

Upgrade

APT installations upgrade normally:

sudo apt update
sudo apt upgrade

To upgrade only OwnNode Agent:

sudo apt install --only-upgrade pistats-backend

Package upgrades preserve /etc/pistats/pistats.env, including the token and site-specific settings, and restart the systemd service when required.

Remove or purge

Remove the application while retaining configuration and media/state data:

sudo apt remove pistats-backend

Remove the application and /etc/pistats/pistats.env:

sudo apt purge pistats-backend

OwnNode Agent deliberately retains /var/lib/pistats and media libraries even on purge. Remove those only after confirming they contain nothing you need.

Remove the APT source and archive key if you no longer want updates:

sudo rm /etc/apt/sources.list.d/pistats.list
sudo rm /usr/share/keyrings/pistats-archive-keyring.gpg
sudo apt update

Source installation

The source installer remains available for development and custom deployments. Do not run it alongside the Debian package on the same port. See the source deployment guide for that workflow.

Troubleshooting

  • 401 unauthorized: confirm the app token exactly matches PISTATS_TOKEN.
  • Connection refused: check systemctl status, the configured bind mode, and the address used by the client.
  • Tailscale startup failure: ensure tailscale0 exists or configure PISTATS_TAILSCALE_IP explicitly.
  • Empty service list: confirm Docker has containers and the pistats account is in the Docker group, then retry discovery in the app.
  • Media endpoint returns 404: configure PISTATS_MEDIA_BACKUP_ROOT and restart.
  • Media startup failure: ensure the root exists, is writable by pistats, and its state/temp paths are on the same filesystem.
  • Actual Budget remains hidden: complete the opt-in setup in Actual Budget transaction sync, then verify Node, the API package version, credentials, Sync ID, and every mapped account.