Skip to main content
Version: 0.4 · current

Install Excubius

OverviewReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Installer (Linux administrator)
PlansFree · Core · Pro · EnterpriseDeploymentSelf-hosted

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​

ItemRequirement
ServerRocky 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
AccessAn account with sudo on the server, reachable over SSH from your workstation
Network to usersPorts 80 and 443 free on the server and open from where people will use Excubius
OutboundHTTPS to ghcr.io and docker.io to pull images, unless you use the offline package
Network to what you monitorFrom 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 packageexcubius-installer-<version>.tar.gz, or the offline package with the images inside. Signed-in users get both from Downloads
Sign-inA Microsoft Entra ID app registration, a Google OAuth client, or both. See Set up sign-in providers
Monitoring loginsRead-only logins for what you will monitor, for example the SQL Server login in Prerequisites for availability groups
CertificateFor 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​

  1. Copy the installer package to the server and unpack it:

    tar -xzf excubius-installer-0.4.0.tar.gz
    cd excubius-installer-0.4.0
  2. Optionally, run only the preflight checks. They change nothing:

    sudo ./install.sh --check-only
  3. Run the installer and answer its questions. Press Enter to accept the value in brackets:

    sudo ./install.sh

    The installer keeps your answers, versioned, so an upgrade asks only the questions that are new in that release.

  4. 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​

QuestionDefaultNotes
Install directory/opt/excubiusAny absolute path
Service accountexcubiusCreated if missing. It runs the containers without root privileges
Public URLhttps://monitoring.example.comThe address people will open. Its host is the server's primary name
AliasesNoneOther names people may open, separated by spaces, for example an alias in a domain you control
TLSletsencryptletsencrypt (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 certificateallAsked 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 passwordA suggested usernameThe 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 presetenterpriseenterprise, 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 #alertsOptional; 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​

ModeUse it when
Let's Encrypt, HTTP validationThe name resolves publicly to the server and port 80 is reachable from the internet
Let's Encrypt, DNS validationThe server is private, but you can create DNS records through an API
Your own certificateYour organisation issues certificates
Self-signedA lab or a first test
GatewayA load balancer or reverse proxy in front terminates TLS
Plain HTTPA 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​

CommandWhat it does
sudo ./install.sh on an installed serverOffers Upgrade (keeps data and asks only new questions), Reinstall, Purge and install fresh or Cancel
sudo ./install.sh --uninstallTakes a final database backup, then removes services and images. Keeps the data, the backups and the configuration
sudo ./install.sh --uninstall --purgeAlso deletes the data, the backups and the service account. Asks you to type purge
warning

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.

Next steps​