Skip to content

Getting Started

Jump to bottom
Larry K. Aycock edited this page Aug 4, 2026 · 1 revision

Getting Started

Installation

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

curl -fsSL -H "Cache-Control: no-cache" https://raw.githubusercontent.com/N6LKA/ASL3-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/ASL3-Herald/archive/refs/heads/develop.tar.gz" \
  | tar -xzO ASL3-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 asl3-herald.py to /usr/local/bin/asl3-herald/
  4. Installs the herald management command to /usr/local/bin/herald
  5. Creates /etc/asterisk/scripts/asl3-herald/ with an example config (if no config exists)
  6. Installs and enables the asl3-herald systemd service, and starts it automatically
  7. Installs the web UI to /var/www/html/asl3-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

After installation

  1. Edit the config: sudo nano /etc/asterisk/scripts/asl3-herald/asl3-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/ASL3-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/ASL3-Herald/main/uninstall.sh | sudo bash -s -- --purge-all

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

Service Commands

sudo systemctl start asl3-herald      # Start the daemon
sudo systemctl stop asl3-herald       # Stop the daemon
sudo systemctl restart asl3-herald    # Restart the daemon
sudo systemctl status asl3-herald     # Show service status
journalctl -u asl3-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/asl3-herald/, but the actual entry points are installed inside Allmon3's and Supermon's own directories:

  • Allmon3: install.sh installs asl3-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 asl3-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/asl3-herald-web).

Home

README

Clone this wiki locally