Install Excubius
Excubius runs on one Linux server that you control, in your cloud subscription or your data centre. The interactive installer checks the server, asks a short list of questions, installs the containers and obtains the certificate. This article lists what you need, what the installer asks and does, and where to go for each task that follows.
Before you begin
| Item | Requirement |
|---|---|
| Server | Rocky Linux 9 or 10 (or another RHEL-family system), x86-64, systemd. At least 2 vCPU, 4 GiB of memory and 20 GiB of free disk; in Azure, Standard_B2ms (2 vCPU, 8 GiB) is a good start and can be resized later. If your cloud team creates servers, see Request the Azure server |
| Access | An account with sudo on the server, reachable over SSH from your workstation |
| Network to users | Ports 80 and 443 free on the server and open from where people will use Excubius |
| Outbound | HTTPS to ghcr.io and docker.io to pull images, unless you use the offline package |
| Network to what you monitor | From the server, the SQL port of every instance, replica and listener IP (and UDP 1434 for named instances without a fixed port), plus HTTPS to the web endpoints you test. Nothing connects to the collector |
| Installer package | excubius-installer-<version>.tar.gz, or the offline package with the images inside. Signed-in users get both from Downloads |
| Sign-in | A Microsoft Entra ID app registration, a Google OAuth client, or both. See Set up sign-in providers |
| Monitoring logins | Read-only logins for what you will monitor, for example the SQL Server login in Prerequisites for availability groups |
| Certificate | For Let's Encrypt, a public DNS name pointing at the server, or API access to its DNS zone. Not needed for your own certificate, a self-signed one, or a gateway that terminates TLS |
How the installation works
The preflight checks cover the operating system and its version, the architecture, systemd and dnf, memory, CPUs, disk, free ports 80 and 443, SELinux, access to the registries or the images archive, and clock synchronisation.
The server receives the release package, a configuration file and the container images. It never receives source code and never contacts a code repository.
Install
-
Copy the installer package to the server and unpack it:
tar -xzf excubius-installer-0.4.0.tar.gzcd excubius-installer-0.4.0 -
Optionally, run only the preflight checks. They change nothing:
sudo ./install.sh --check-only -
Run the installer and answer its questions. Press Enter to accept the value in brackets:
sudo ./install.shThe installer keeps your answers, versioned, so an upgrade asks only the questions that are new in that release.
-
When it finishes, open the public address it prints and sign in as the administrator you named during the installation. Then set up sign-in and invite the people who will use Excubius.
Everything the installer does is logged to /var/log/excubius-install.log, without secrets.
The installer's questions
| Question | Default | Notes |
|---|---|---|
| Install directory | /opt/excubius | Any absolute path |
| Service account | excubius | Created if missing. It runs the containers without root privileges |
| Public URL | https://monitoring.example.com | The address people will open. Its host is the server's primary name |
| Aliases | None | Other names people may open, separated by spaces, for example an alias in a domain you control |
| TLS | letsencrypt | letsencrypt (over HTTP), letsencrypt-dns (over DNS), selfsigned, custom (your PEM files), gateway (TLS ends in front) or later (plain HTTP for now) |
| Names in the certificate | all | Asked when there are aliases: leave out the names a certificate cannot cover |
| E-mail for Let's Encrypt | — | Both Let's Encrypt modes |
| DNS provider and credentials | — | letsencrypt-dns only: the acme.sh dnsapi id, such as dns_cf, dns_dreamhost or dns_azure, and its variables, typed one by one without echo |
| Certificate and key files | — | custom only: the PEM chain, server certificate first, and an unencrypted key |
| Administrator username and password | A suggested username | The account for the first sign-in, at the address the installer prints when it finishes. The password needs 12 characters or more and is asked twice |
| Base preset | enterprise | enterprise, databases or core; see Configure the instance |
| Registry user and token | — | Given to you with the licence. Not asked with the offline package |
| Slack bot token and channel | — and #alerts | Optional; you can set them later. See Configure Slack notifications |
| Entra ID tenant ID, client ID and secret | — | Optional; you can set them later |
With a Let's Encrypt mode, the installer then checks the names in public DNS and, over HTTP, that they point at this server. When they do not, it explains the alternatives; it never stops for it.
The installer generates the database password, the session signing secret, the key that encrypts stored secrets and the collector token once, and never asks for them. Once the platform has stored the administrator's password, the DNS credentials and a private key, it removes them from the configuration file.
To install without questions, pass the answers in a file with --answers; see the installer reference.
Names and TLS
| Mode | Use it when |
|---|---|
| Let's Encrypt, HTTP validation | The name resolves publicly to the server and port 80 is reachable from the internet |
| Let's Encrypt, DNS validation | The server is private, but you can create DNS records through an API |
| Your own certificate | Your organisation issues certificates |
| Self-signed | A lab or a first test |
| Gateway | A load balancer or reverse proxy in front terminates TLS |
| Plain HTTP | A first test, or a network you fully trust |
You can change names and the certificate later from Settings without reinstalling, and renewal is automatic. See Set up names and TLS.
Upgrade, reinstall or uninstall
| Command | What it does |
|---|---|
sudo ./install.sh on an installed server | Offers Upgrade (keeps data and asks only new questions), Reinstall, Purge and install fresh or Cancel |
sudo ./install.sh --uninstall | Takes a final database backup, then removes services and images. Keeps the data, the backups and the configuration |
sudo ./install.sh --uninstall --purge | Also deletes the data, the backups and the service account. Asks you to type purge |
Upgrade in a change window. The services restart for a few seconds and database migrations run. Read the known issues of the version before you start.
--dry-run works with every command and only prints what would happen. The steps for upgrading, rolling back, backing up and restoring are in Upgrade, back up and restore, for signed-in users.
Watch Excubius from outside
Excubius must not be the only thing watching itself. Register https://<your server>/heartbeat with an external watcher, such as an Azure Monitor availability test, Uptime Kuma running elsewhere, or a healthchecks-style service, and have it alert you when the address stops answering ok. If the server stops, that watcher is what tells you.
/heartbeat and /healthz answer over plain HTTP in every TLS mode. /healthz also returns the version that is running.