Skip to main content
Version: 0.4 · current

Installer reference

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

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​

OptionEffect
(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-onlyRun the preflight checks only. Changes nothing
--images FILEInstall from an images archive, without registry access. An archive in images/ next to the script, as in the offline package, is used automatically
--answers FILENon-interactive: key=value lines, secrets included. See Answers file
--reconfigureOn an upgrade, ask every question again. TLS answers given then are applied to the running platform
--reinstallRemove the installed software keeping the database, then install asking every question
--purgeDelete everything, the database included, then install fresh
--uninstallRemove 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 --purgeAlso 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-backupNo final database dump on --uninstall or --reinstall
--yes, -yAccept 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-runPrint 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-checksContinue even when preflight checks fail, on unsupported systems, at your own risk
--help, -hPrint 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​

CheckRequirementWhen it is not met
Operating systemRocky Linux or another RHEL-family systemFails
Major version9 or 10Warns
Architecturex86-64Fails
Init systemsystemdFails
Package managerdnfFails
Memory4 GiBWarns
CPUs2 vCPUWarns
Disk20 GiB free under /home, where the service account keeps images and the databaseWarns
Ports80 and 443 free, on a new installationFails
SELinuxReported—
Registriesghcr.io and docker.io reachable over HTTPS, or a readable images archiveFails
ClockSynchronisedWarns; 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.

KeyQuestionDefaultAsked whenSince
install_dirInstall directory/opt/excubiusAlways; an absolute path0.2.0
service_userService account that runs the platformexcubiusAlways; created if missing, runs the containers rootless0.2.0
public_urlPublic URL users will openhttps://monitoring.example.comAlways; its host is the server's primary name0.2.0
server_aliasesOther names for this servernoneAlways; separated by spaces, Enter for none0.3.0
tls_modeHow HTTPS is providedletsencryptAlways: letsencrypt, letsencrypt-dns, selfsigned, custom, gateway or later0.2.0
tls_cert_namesNames to put in the certificateallThere are aliases and the mode makes a certificate0.3.0
tls_emailE-mail for the Let's Encrypt account—letsencrypt or letsencrypt-dns0.2.0
tls_dns_providerDNS provider of the names' zone—letsencrypt-dns; an acme.sh dnsapi ID such as dns_cf, dns_dreamhost or dns_azure0.3.0
tls_dns_credentialsDNS API credentials—letsencrypt-dns; entered one by one without echo0.3.0
tls_cert_fileCertificate chain file—custom; PEM, server certificate first0.3.0
tls_key_filePrivate key file—custom; PEM, without passphrase, matching the certificate0.3.0
default_presetBase presetenterpriseAlways: enterprise, databases or core0.2.0
registry_user, registry_tokenRegistry user and read-only token for the images—Without an images archive0.2.0
slack_bot_tokenSlack bot token—Always; optional0.2.0
slack_default_channelSlack channel for alerts#alertsAlways0.2.0
entra_tenant_idEntra ID tenant ID for sign-in—Always; optional0.2.0
entra_client_id, entra_client_secretEntra ID application ID and client secret—A tenant ID was given0.2.0

The TLS modes:

ModeUse it when
letsencryptEvery name is in public DNS pointing at the server and port 80 is reachable from the Internet
letsencrypt-dnsYou have API credentials for the DNS zone of the names. The server need not be reachable from the Internet
selfsignedAnywhere. Browsers warn until users trust the certificate
customYour organisation issues the certificate
gatewayTLS ends on a load balancer or reverse proxy in front
laterPlain 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​

PathWhat
<dir>/.envConfiguration and secrets; mode 0600, owned by the service account
<dir>/install.answersYour non-secret answers, the version that wrote them and whether that run finished
<dir>/currentThe installed release, a link into <dir>/releases/
<dir>/backupsDaily 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.logThe 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