Skip to content

INSTALL.md

Latest commit

聽

History

History
117 lines (85 loc) 路 3.83 KB

INSTALL.md

File metadata and controls

117 lines (85 loc) 路 3.83 KB
Raw

Beatnik Hardware API: Installation & Updating Guide

This guide covers the necessary steps to install, configure, and maintain the Beatnik Hardware API on your Raspberry Pi.

There are two primary ways to install the service. Method 1 (Production Release) is the most robust and professional choice, as it keeps your Raspberry Pi free of development dependencies and compiling overhead. Method 2 (Source Script) is better suited for active development.

馃搵 Prerequisites

Before you begin, ensure your Raspberry Pi meets the following requirements:

  • OS: Raspberry Pi OS (Bookworm or newer recommended)
  • Privileges: Root access (sudo) is required to modify system configuration files and manage systemd services.
  • Node.js: Version 22 is required.

Installing Node.js (via NVM)

If you don't have Node.js installed, we recommend using NVM (Node Version Manager):

# Install NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc

# Install and activate Node.js 22
nvm install 22
nvm use 22

馃殌 Installation

Method 1: Production Setup Script (Recommended)

We provide an automated setup script that downloads the latest pre-built release artifact, installs dependencies, and configures the systemd service. This is the cleanest way to run the service in production.

wget https://raw.githubusercontent.com/byrdsandbytes/beatnik-hardware-api/master/setup.sh
chmod +x setup.sh
./setup.sh

What the script does:

  1. Creates the /opt/beatnik-hardware-api directory.
  2. Downloads and extracts the latest release artifact from GitHub.
  3. Installs Node.js v22 via NVM (if not present).
  4. Installs production dependencies (npm install --omit=dev).
  5. Automatically patches and installs beatnik-hardware.service to systemd and starts it.

Method 2: Manual Source Installation (Development)

If you want to build the project directly from source on the Pi itself:

1. Clone Repository

sudo mkdir -p /opt/beatnik-hardware-api
sudo chown -R $USER:$USER /opt/beatnik-hardware-api
cd /opt/beatnik-hardware-api
git clone https://github.com/byrdsandbytes/beatnik-hardware-api.git .

2. Install Dependencies & Build

npm install
npm run build

3. Set up the System Service

# Copy the service file
sudo cp beatnik-hardware.service /etc/systemd/system/

# IMPORTANT: Edit the service file to ensure ExecStart points to your Node.js executable
# You can find your node path by running: which node
sudo nano /etc/systemd/system/beatnik-hardware.service

# Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable beatnik-hardware.service
sudo systemctl start beatnik-hardware.service

馃攧 Updating the Service

To make future updates completely seamless, the setup.sh script is designed to also act as an updater.

Whenever a new version (vX.X.X) is tagged and pushed to GitHub, an automated CI/CD pipeline (GitHub Actions) instantly builds a new release artifact. You can easily pull this update onto your Raspberry Pi by running the local setup script again:

cd /opt/beatnik-hardware-api
./setup.sh

What the updater does:

  1. Checks if the service is currently running, and smoothly stops it.
  2. Queries the GitHub API for the latest release of byrdsandbytes/beatnik-hardware-api.
  3. Downloads & extracts the new beatnik-hardware-api.tar.gz artifact over the existing installation.
  4. Runs npm install --omit=dev to sync any new dependencies.
  5. Restarts the system service and cleans up.

馃洜 Checking Service Status

Regardless of which method you chose, you can always check if the API is running smoothly via:

sudo systemctl status beatnik-hardware.service

You can also test the hardware status endpoint:

curl http://localhost:3000/api/hardware/status