Skip to content

Getting Started

Jump to bottom
Larry K. Aycock edited this page Aug 10, 2026 · 3 revisions

Getting Started

Installation

Stable (recommended): installs from main — the tested, working release.

curl -fsSL -H "Cache-Control: no-cache" https://raw.githubusercontent.com/N6LKA/AllStar-Herald/main/install.sh | sudo bash

Development (testing only): installs from develop — whatever's currently being worked on ahead of the next release.

⚠️ Warning: develop may contain incomplete, untested, or broken features at any given time. Only use this on a system where you can tolerate things breaking (or reinstall from main to recover). Don't use it on a repeater or node you depend on for daily use.

curl -fsSL "https://github.com/N6LKA/AllStar-Herald/archive/refs/heads/develop.tar.gz" \
  | tar -xzO AllStar-Herald-develop/install.sh \
  | sudo bash -s -- --branch develop

This tarball form is used instead of the raw GitHub URL because raw.githubusercontent.com is CDN-cached and can serve a stale install.sh for an extended period — the tarball download goes through GitHub's codeload service, which always returns the current commit.

What the installer does

  1. Installs python3-yaml, sox, and libsox-fmt-mp3 if not already present
  2. Installs Piper TTS 1.2.0 (binary + the default en_US-amy-medium voice) into the shared /var/lib/piper-tts — more voices can be installed later from the web UI's Voices tab
  3. Copies herald.py to /etc/asterisk/scripts/herald/
  4. Installs the herald management command to /usr/local/bin/herald
  5. Creates an example config in the same /etc/asterisk/scripts/herald/ directory (if no config exists)
  6. Installs and enables the herald systemd service, and starts it automatically
  7. Installs the web UI to /var/www/html/herald/ — installs apache2 + php first if neither Allmon3 nor Supermon is already present, then installs a dedicated page directly into Allmon3's and/or Supermon's own directory (with a sidebar/footer link to it) for whichever is detected, and a standalone version at http://<node-ip>/herald/ with its own login, reachable either way

After installation

  1. Log into the web UI at http://<node-ip>/herald/ (shown at the end of the install output) — username admin, password admin — and do your initial setup from there (Node number, Tail Messages, etc.). Change the default password on the Global Settings tab under Login Settings before exposing this beyond your own LAN — see Standalone Web UI. Prefer editing the config file directly? sudo nano /etc/asterisk/scripts/herald/herald.conf — see Configuration Reference for every field
  2. Check it's running: herald status

Uninstalling

curl -fsSL -H "Cache-Control: no-cache" https://raw.githubusercontent.com/N6LKA/AllStar-Herald/main/uninstall.sh | sudo bash

By default this removes the daemon, herald CLI, systemd service, web UI, sudoers rule, and the Allmon3/Supermon integration lines it added — while preserving your config, announcements, state, and Piper TTS install so a future reinstall picks up where you left off. To also remove those:

curl -fsSL -H "Cache-Control: no-cache" https://raw.githubusercontent.com/N6LKA/AllStar-Herald/main/uninstall.sh | sudo bash -s -- --purge-all

(--purge-config and --purge-piper are available individually too.)

Service Commands

sudo systemctl start herald      # Start the daemon
sudo systemctl stop herald       # Stop the daemon
sudo systemctl restart herald    # Restart the daemon
sudo systemctl status herald     # Show service status
journalctl -u herald -f          # Follow live log output

Web UI Overview

An optional browser-based UI for managing everything Herald does. The shared UI and JSON API live at /var/www/html/herald/, but the actual entry points are installed inside Allmon3's and Supermon's own directories:

  • Allmon3: install.sh installs herald.html directly into Allmon3's own web root (/usr/share/allmon3/) and appends a [Herald] entry to /etc/allmon3/menu.ini pointing at it. The page loads Allmon3's real functions.js/index.js unmodified — same header/sidebar chrome as any other Allmon3 page, gated on Allmon3's own login.
  • Supermon (v7.4+ and v8+): install.sh installs herald.php directly into Supermon's own directory (/var/www/html/supermon/) and adds a link at the bottom of the page after logging in. It includes Supermon's real session.inc/header.inc/footer.inc unmodified — same nav, login dialog, and session cookie Supermon itself uses.
  • If neither Allmon3 nor Supermon is detected at install time, install.sh installs apache2 + php on its own so the shared UI still has somewhere to run.

Tabs:

  • How It Works — a plain-language overview of Tail Messages, Scheduled Announcements, and Time & Weather Announcements, useful for anyone new to the system or sharing access with others
  • Tail Messages, Scheduled Announcements, Time & Weather — see their own pages
  • Node ID Generator — see Node ID Generator
  • Playback History — the last 200 plays (rotation, WX, scheduled, manual test) with timestamp, node, and play mode
  • Global Settings — daemon status/enable-disable, version + update check/Updating Herald, voices (Voices & TTS Engines), and Backup & Restore

Both Tail Messages and Scheduled Announcements support adding announcements via typed text (with Piper voice selection) or by uploading an existing .wav/.mp3 file (auto-converted to 8kHz mono).

All mutations go through the same herald CLI used at the command line — the web UI never edits the YAML config directly. www-data is granted narrow, passwordless sudo access to run herald only (see /etc/sudoers.d/herald-web).

Home

README

Clone this wiki locally