Installer reference
The installer, install.sh, installs, upgrades, reinstalls and uninstalls Excubius on one server. It runs as root from the unpacked installer package. This reference lists its options, its preflight checks, the questions it asks and what it leaves on the server. For the steps of an installation, see Install Excubius.
sudo ./install.sh [options]
Options
| Option | Effect |
|---|---|
| (none) | Install. On a server where Excubius is installed, offers Upgrade (the default: keeps data and settings, asks only the questions new in this version), Reinstall, Purge or Cancel |
--check-only | Run the preflight checks only. Changes nothing |
--images FILE | Install from an images archive, without registry access. An archive in images/ next to the script, as in the offline package, is used automatically |
--answers FILE | Non-interactive: key=value lines, secrets included. See Answers file |
--reconfigure | On an upgrade, ask every question again. TLS answers given then are applied to the running platform |
--reinstall | Remove the installed software keeping the database, then install asking every question |
--purge | Delete everything, the database included, then install fresh |
--uninstall | Remove the software. Writes a final database dump to <dir>/backups/ first, then removes the user units, containers, images, <dir>/releases, <dir>/current, /etc/excubius and the rootless-port setting. Keeps the database and certificate volumes, <dir>/backups, <dir>/.env and the service account, so a later install finds the data |
--uninstall --purge | Also delete every volume, the whole install directory with its backups, the service account the installer created with its container storage, and the firewall services the installation added. Asks you to type purge |
--no-backup | No final database dump on --uninstall or --reinstall |
--yes, -y | Accept every default that exists; required answers must still come from --answers or the keyboard. Means Upgrade on an installed server, and confirms a purge |
--dry-run | Print what would be done and change nothing. An install still writes its configuration files for review; next to an existing .env, as .env.dry-run |
--skip-checks | Continue even when preflight checks fail, on unsupported systems, at your own risk |
--help, -h | Print the options |
These combinations are refused: --uninstall with --reinstall or --reconfigure; --purge with --reinstall; --check-only with --uninstall, --purge or --reinstall; --reconfigure with --purge or --reinstall.
Only the recorded install directory is ever removed, never a system path or a home directory.
Preflight checks
| Check | Requirement | When it is not met |
|---|---|---|
| Operating system | Rocky Linux or another RHEL-family system | Fails |
| Major version | 9 or 10 | Warns |
| Architecture | x86-64 | Fails |
| Init system | systemd | Fails |
| Package manager | dnf | Fails |
| Memory | 4 GiB | Warns |
| CPUs | 2 vCPU | Warns |
| Disk | 20 GiB free under /home, where the service account keeps images and the database | Warns |
| Ports | 80 and 443 free, on a new installation | Fails |
| SELinux | Reported | — |
| Registries | ghcr.io and docker.io reachable over HTTPS, or a readable images archive | Fails |
| Clock | Synchronised | Warns; chrony is enabled |
Questions
Press Enter to accept the value in brackets. On an upgrade, only the questions introduced after the version that wrote your answers are asked; Since says which version introduced each one.
| Key | Question | Default | Asked when | Since |
|---|---|---|---|---|
install_dir | Install directory | /opt/excubius | Always; an absolute path | 0.2.0 |
service_user | Service account that runs the platform | excubius | Always; created if missing, runs the containers rootless | 0.2.0 |
public_url | Public URL users will open | https://monitoring.example.com | Always; its host is the server's primary name | 0.2.0 |
server_aliases | Other names for this server | none | Always; separated by spaces, Enter for none | 0.3.0 |
tls_mode | How HTTPS is provided | letsencrypt | Always: letsencrypt, letsencrypt-dns, selfsigned, custom, gateway or later | 0.2.0 |
tls_cert_names | Names to put in the certificate | all | There are aliases and the mode makes a certificate | 0.3.0 |
tls_email | E-mail for the Let's Encrypt account | — | letsencrypt or letsencrypt-dns | 0.2.0 |
tls_dns_provider | DNS provider of the names' zone | — | letsencrypt-dns; an acme.sh dnsapi ID such as dns_cf, dns_dreamhost or dns_azure | 0.3.0 |
tls_dns_credentials | DNS API credentials | — | letsencrypt-dns; entered one by one without echo | 0.3.0 |
tls_cert_file | Certificate chain file | — | custom; PEM, server certificate first | 0.3.0 |
tls_key_file | Private key file | — | custom; PEM, without passphrase, matching the certificate | 0.3.0 |
default_preset | Base preset | enterprise | Always: enterprise, databases or core | 0.2.0 |
registry_user, registry_token | Registry user and read-only token for the images | — | Without an images archive | 0.2.0 |
slack_bot_token | Slack bot token | — | Always; optional | 0.2.0 |
slack_default_channel | Slack channel for alerts | #alerts | Always | 0.2.0 |
entra_tenant_id | Entra ID tenant ID for sign-in | — | Always; optional | 0.2.0 |
entra_client_id, entra_client_secret | Entra ID application ID and client secret | — | A tenant ID was given | 0.2.0 |
The TLS modes:
| Mode | Use it when |
|---|---|
letsencrypt | Every name is in public DNS pointing at the server and port 80 is reachable from the Internet |
letsencrypt-dns | You have API credentials for the DNS zone of the names. The server need not be reachable from the Internet |
selfsigned | Anywhere. Browsers warn until users trust the certificate |
custom | Your organisation issues the certificate |
gateway | TLS ends on a load balancer or reverse proxy in front |
later | Plain HTTP for now |
With a Let's Encrypt mode, the installer checks the names in public DNS and, over HTTP, that they point at this server. It explains the alternatives when they do not, and never stops for it. TLS answers only seed the platform's settings; afterwards they are managed in Settings › Server.
Generated values
The installer generates these once and never overwrites them: the database password (POSTGRES_PASSWORD), the session signing secret (JWT_SECRET), the key that encrypts stored secrets (EXCUBIUS_DATA_KEY) and the collector token (EXCUBIUS_COLLECTOR_TOKEN). See Environment variables.
Answers file
For an unattended install, pass --answers FILE with one key=value line per question. Secrets are included in this file; protect it and delete it afterwards. DNS credentials go on one line, separated by ;. A missing answer takes the default; a required answer that is missing or invalid stops the installer with the name of the key, so you can complete the file and run it again.
An excerpt:
install_dir=/opt/excubius
service_user=excubius
public_url=https://monitoring.areito.example
server_aliases=
tls_mode=letsencrypt-dns
tls_email=ops@areito.example
tls_dns_provider=dns_cf
tls_dns_credentials=CF_Token=<token>
default_preset=enterprise
registry_user=<registry user>
registry_token=<read-only token>
slack_bot_token=<bot token>
slack_default_channel=#areito-alerts
sudo ./install.sh --answers ./answers.conf --yes
Upgrades and versioned answers
The installer records your non-secret answers in <dir>/install.answers, with the installer version that wrote them and whether that run finished. On an upgrade it asks only the questions introduced since that version. A run that did not finish is treated as a new installation: every question is asked again, with the earlier answers as defaults. Secrets are never written to install.answers.
On the server
| Path | What |
|---|---|
<dir>/.env | Configuration and secrets; mode 0600, owned by the service account |
<dir>/install.answers | Your non-secret answers, the version that wrote them and whether that run finished |
<dir>/current | The installed release, a link into <dir>/releases/ |
<dir>/backups | Daily database dumps, the last 14 kept, plus the final dump of an uninstall |
~<service account>/.config/systemd/user/ | excubius.service and the backup timer |
/var/log/excubius-install.log | The installer's log, without secrets |
As the service account:
sudo -iu excubius
export XDG_RUNTIME_DIR=/run/user/$(id -u) # once per shell, for systemctl --user
systemctl --user status excubius # the platform
<dir>/current/scripts/compose.sh ps # the containers
<dir>/current/scripts/compose.sh logs -f backend # the API's log
<dir>/current/scripts/backup-db.sh # a database backup now
<dir>/current/scripts/enable-tls.sh --status # TLS without the console
<dir>/current/scripts/rollback.sh # back to the previous release