Install MMHotline
Who acts: an administrator with sudo on the Linux server that will
run MMHotline, or that person's coding agent, or the team's deploy tool.
When to use this page: to install MMHotline on a server, by hand or from a deploy tool, from a release or from source. Get started does the same install as part of the first hour, and also sets up Pushover, Cloudflare Access, and a test SOS.
What this page does: you check the server, download and check a release, write the settings file, and install. MMHotline then runs as a systemd service.
Terms: the settings file, /etc/mmhotline/mmhotline_settings.yml,
holds the team's settings: its people, its schedule, and the tools that
send alerts. The install reads it and never changes its contents.
Choose the route
- Install a release by hand: follow Install a release.
- A deploy tool installs it, such as MMX:
the tool does the same steps. It writes the settings file from your
repository, owner
root, groupmmhotlineonce that group exists, mode0640, and runsmmhotline installfrom the unpacked release. - Run a commit that has no release, such as a change you are making: build it first, as Build from source says, then follow the steps from step 4.
- MMHotline is already installed, and you want a newer release: see Upgrade MMHotline.
Before you start
- A Linux server with systemd, such as Debian 12 or 13 or Ubuntu 24.04, which MMHotline is tested on. MMHotline needs systemd for its service and for the restricted units its agents run in.
sudo,curl, and, for the test sender in the other pages, Python 3.- A private network address on the server, such as a WireGuard address,
where your tools will send alerts. If every tool that sends alerts runs
on this server,
127.0.0.1works too. - Outbound internet access, for Cloudflare and the sending services.
Install a release
-
Find the server's processor:
uname -mCheck: it prints
x86_64, which uses theamd64archive, oraarch64, which uses thearm64archive. The examples useamd64and the version0.1.0; use the newest release. -
Download the archive and the checksum file, and check the archive:
curl --fail --location --remote-name-all \ https://github.com/monkeymaxxing/mmhotline/releases/download/v0.1.0/mmhotline-0.1.0-linux-amd64.tar.gz \ https://github.com/monkeymaxxing/mmhotline/releases/download/v0.1.0/SHA256SUMS sha256sum --check --ignore-missing SHA256SUMSCheck: it prints
mmhotline-0.1.0-linux-amd64.tar.gz: OK.--ignore-missingskips the archives you did not download.Reason:
SHA256SUMSholds the checksum of each archive in the release, so the check finds a damaged or replaced download before you run it. -
Unpack the archive:
tar -xzf mmhotline-0.1.0-linux-amd64.tar.gz cd mmhotline-0.1.0-linux-amd64Check:
lsshowsLICENSE,dependency_license_notices, and the programmmhotline. -
Write the settings file, if it does not exist yet. Make the folder and an empty file that only root can read and change, and open it. The install in step 6 then lets MMHotline read it too:
sudo install -d -m 0755 /etc/mmhotline sudo install -m 0640 /dev/null /etc/mmhotline/mmhotline_settings.yml sudoedit /etc/mmhotline/mmhotline_settings.ymlWrite the first settings: the team, its addresses, you as the first administrator, a schedule, and an alert source. Step 3 of Get started has a whole first file and says which values to change; the settings file reference lists every key.
Reason for the owner and mode: the file holds the team's secrets, and its
fleet_view_commandruns as root, so only root may change it, and, after the install, only root and MMHotline may read it. -
Check the settings file:
sudo ./mmhotline settings check --settings-file /etc/mmhotline/mmhotline_settings.ymlCheck: it prints
The settings file /etc/mmhotline/mmhotline_settings.yml has no problems. -
Install:
sudo ./mmhotline installThe install prints one line for each thing it checks or makes. On a new server, the output starts and ends like this:
Checks: Linux, root, and systemd confirmed Unix user: created mmhotline with no login shell Unix user: created mmhotline-triage-agent with no login shell Unix user: created mmhotline-review-agent with no login shell ... Database: created mmhotline.db for Operations Settings file: set owner root, group mmhotline, and mode 0640, so MMHotline can read the settings file and only root can change the settings file: /etc/mmhotline/mmhotline_settings.yml ... Backup: not set up; see https://github.com/monkeymaxxing/mmhotline/blob/main/docs/how-to/back-up-and-restore-the-database.md#set-up MMHotline: https://ops.example.com Next: set up cloudflared and a Cloudflare Access application for https://ops.example.com, add cloudflare_access to /etc/mmhotline/mmhotline_settings.yml, and apply the file, with your deploy tool or with sudo mmhotline settings apply (https://github.com/monkeymaxxing/mmhotline/blob/main/docs/how-to/put-mmhotline-behind-cloudflare-access.md)Check: the command exits 0, and
systemctl is-active mmhotline mmhotline versionprint
activeand the release, such asmmhotline 0.1.0 (COMMIT, linux/amd64, modified=false), with the release's full commit hash in place ofCOMMIT.From now on, run the installed
mmhotline, without./. You can delete the downloaded files. -
Go on with the
Next:line: put MMHotline behind Cloudflare Access, as Put MMHotline behind Cloudflare Access says, so people can open it. Until then, nobody can open MMHotline's pages except with a sign-in link, as Sign in during a Cloudflare outage says.
What the install does
- It copies the program to
/usr/local/bin/mmhotline. - It creates three Unix users with no login:
mmhotline, which runs MMHotline, andmmhotline-triage-agentandmmhotline-review-agent, which the team's coding agents run as, if the team sets them up. - It creates the database
/var/lib/mmhotline/mmhotline.dbfor the team named inteam_name, with thepeopleof the settings file, if the database does not exist yet. One installation serves one team. An existing database stays, with every row. - It gives the settings file the group
mmhotlineand mode0640, so MMHotline can read it and only root can change it. - It writes systemd units and starts them:
mmhotline.service, and the sockets through which MMHotline starts agent runs and the dashboard's server view. Withbackup.envand Litestream in place, it also writes the backup's service, as Back up and restore the database says.
MMHotline then serves its pages only on the server itself, at
web_listen_address (127.0.0.1:8480), and takes alerts at
alert_intake_listen_address. Nothing listens on a public address.
Install files lists each file and its owner
and mode.
Running the install again is safe. It keeps what is already correct
and says so, such as
Binary: already correct (/usr/local/bin/mmhotline) and
Database: mmhotline.db already exists; kept. It restarts MMHotline only
when the program or a unit changed, or MMHotline was stopped. Reason: a
deploy tool can run the install on every deploy.
Build from source
Build on the server, with Go 1.27.4 and Git
installed; go.mod selects that Go toolchain. No C compiler is needed.
git clone https://github.com/monkeymaxxing/mmhotline.git
cd mmhotline
export GOCACHE="${TMPDIR:-/tmp}/go-build"
CGO_ENABLED=0 go build -o "${TMPDIR:-/tmp}/mmhotline" ./cmd/mmhotline
When GitHub is down, clone the mirror,
https://gitlab.com/monkeymaxxing/mmhotline.git, instead. To build a
release, run git checkout v0.1.0 after cd mmhotline, with the release's
version in place of 0.1.0.
Check: "${TMPDIR:-/tmp}/mmhotline" version prints the version. Then
follow Install a release from step 4, with
sudo "${TMPDIR:-/tmp}/mmhotline" in place of sudo ./mmhotline.
Release archives are built by scripts/build-release-archives.py, as
Release archives
describes.
If something is different
sha256sumprintsFAILEDandsha256sum: WARNING: 1 computed checksum did NOT match: the download is damaged or is not the release. Delete it and download again; never run it.- The install says the settings file is missing:
mmhotline: install requires the settings file /etc/mmhotline/mmhotline_settings.yml; ...Do step 4. The install made no change and exits 4. - The install lists settings problems: it checks the file as step 5 does, and also its owner and mode, changes nothing, and names each key with a problem. Fix the file and run the install again.
- The install ends with
systemctl restart mmhotline failed: MMHotline did not start. The install prints the service's last log lines, and the last of them says why, such asMMHotline cannot listen on alert_intake_listen_address 10.20.0.9:8484: listen tcp 10.20.0.9:8484: bind: cannot assign requested address, when the address is not one of the server's own (ip -brief addrlists them). Fix the cause, then run the install again. - The install says
install requires root; run sudo mmhotline install, or that it requires Linux, or running systemd at/run/systemd/system: run it withsudoon the Linux server, which must have booted with systemd. It checks these before it changes anything.
This page is docs/how-to/install.md in the MMHotline repository.