Files
inbuxa-installer/README.md
T

21 KiB
Raw Permalink Blame History

inbuxa-installer

License: AGPL-3.0-or-later Latest release Documentation: docs.inbuxa.org Forum: community.coffeylabs.org Chat on Discord

Note

Development happens on git.coffeylabs.org/inbuxa/inbuxa-installer; the copy on GitHub is a read-only mirror. Report issues at git.coffeylabs.org/inbuxa/inbuxa-installer/issues, join discussions at community.coffeylabs.org, or chat on Discord.

One program that installs the inbuxa suite on the machine you run it on: the mail server, the administration console and the webmail, each as a container or on the host, in any mixture.

inbuxa                         the interface: all of the below, a screen at a time
inbuxa survey                  what this machine is, as the installer sees it
inbuxa install --dry-run …     what would happen, before any of it does
inbuxa install …               do it

It only ever installs here. A second machine runs it too, and inbuxa join points that machine at a server already running elsewhere.

Linux only, and it says so on any other system rather than reporting a machine that does not exist. Debian, Red Hat and Arch families, and the derivatives people run: Ubuntu, Fedora, Rocky, CentOS, CachyOS. It uses whichever container runtime the distribution ships -- docker where there is one, podman on the Red Hat family -- and refuses a shape the machine cannot deliver, with the reason.

What works today

This is early. What is built:

  • inbuxa on its own (or inbuxa install with no options) -- the interface: six screens, always in the same order. What it found on this machine; the names; which components go here and how, with what the machine can't do greyed out and the reason beside it; what answers on 80 and 443; the whole plan, with the command that does the same without the interface; and the install, ticking off its steps, ending on the credentials and addresses, which stay in the terminal afterwards. Nothing happens until you answer y. It fills in the same options the flags do -- it is not a second installer -- and it is built on the standard library alone, like the rest. Without a terminal it says which flags to use.

  • --proxy snippets -- for a machine that already runs nginx or Caddy: nothing here takes 80 or 443, and the installer writes <dir>/proxy/nginx-inbuxa.conf with <dir>/proxy/nginx-inbuxa-stream.conf, and <dir>/proxy/Caddyfile.fragment, for that web server to load, trusts it in front of the suite (its X-Forwarded-For, and an exemption from the auto-ban), and leaves loading and reloading to you. nginx routes 443 by name: it terminates the console and the webmail with your certificates and passes every other name, untouched and with the PROXY protocol header, to the mail server's own HTTPS on 127.0.0.1:8443. So the server serves its own certificates for every domain it has, a domain added later included, and its _443._tcp TLSA records match. Caddy can't route TLS by name without a plugin, so its fragment terminates the server's names itself. An install made before nginx worked this way keeps its layout until install is run again with --key. Once it is loaded, the mail server's own certificates are turned on in the console. --proxy none writes nothing.

  • survey -- the machine's facts: distribution, init, whether Docker is usable by this user, Node's version, which of the suite's ports are free and what holds the ones that are not, memory, disk, and whether an install is already recorded here. It changes nothing.

  • install --dry-run -- the whole plan: every file, unit, container, port, DNS record and credential, and a refusal with a reason when the machine cannot carry out what was asked.

  • deps -- what a shape needs that this machine has not got, and, with --install, the doing of it: the Docker daemon from the distribution's own archive, the Compose plugin and Node from their official builds, both pinned by version and checked against a checksum in the source before anything is put in place. install --install-deps does the same as part of a run. A missing dependency is an offer, not a refusal.

  • install --yes -- carries the plan out: writes the deployment, fetches the images, brings the mail server up in bootstrap mode with a credential that exists only for that step, completes bootstrap, brings the rest up without it, exempts the front ends from the auto-ban, creates the first mailbox, writes credentials.txt and dns.zone, and then checks that all three answer.

  • install --answers FILE -- the install options from a JSON file, for an unattended install driven by cloud-init, Ansible or a kickstart rather than a long command line. The keys are the flag names (domain, mail-host, server, console, webmail, proxy, local, and the rest); a mistyped key is refused rather than ignored. A flag given on the command line still wins over the file, so one answers file can be a base that a flag overrides. It carries no secrets -- the API key stays on --key/INBUXA_API_KEY -- and still needs --yes to carry the plan out.

  • install --server host -- the same, with the mail server as the release binary under systemd instead of a container, checked against a checksum in the source. It gets a user of its own, its configuration and data in <dir>/server, and a unit, inbuxa-server.service. During setup it is reachable from the machine itself and nowhere else; afterwards its plain HTTP is on loopback for the proxy and the webmail, 443 is left to the proxy, and the unit will not start without a configuration file.

  • --console host -- the console's files from its release, checked against a pinned checksum, unpacked into <dir>/console and pointed at the server; the managed Caddy or your own web server (--proxy snippets) serves them. Nothing runs, so there is nothing to start.

  • --webmail host -- the webmail from its release, checked the same way, in <dir>/webmail, owned by root and only read by the webmail, which runs as its own user under inbuxa-webmail.service on the installer's own Node 26 (in /opt/inbuxa/node), on 127.0.0.1:8080. With all three on the host and --proxy snippets, no container runtime is installed at all.

  • join URL --key KEY -- the console and the webmail on this machine, for a mail server already running at URL on another one. It reaches that server only over its own HTTPS, with an API key a server administrator made in the console (--key - reads it from standard input, and INBUXA_JOIN_KEY keeps it out of the shell's history; it is never written down). Through it the front ends' addresses go into the server's inbuxa:FrontEnds, which registers their sign-in and lets the console call the server from the browser, with no restart and nothing changed on that machine by hand. It asks first, dry runs included, and refuses with the reason when the key is wrong, the server is too old, or it already lists other front ends (--replace to put these in their place). Each front end goes in a container or on the host (--console host, --webmail host), as with install. Needs a server release 2026.10.12.1 or newer. The interface does the same: skip the server on the Components screen and give its address and the key.

  • plan -f / apply -f / export -- a whole installation described in one file, however many machines. Each machine acts on its own part and prints the command to run on the others; it never reaches them. plan diffs the file against what is actually installed here and changes nothing; apply converges to it, adding and removing components; export writes the file from what is already here.

  • upgrade [server|console|webmail] -- moves what is installed here to the releases this installer installs; a newer installer brings newer releases. --dry-run shows each component's move first (so does status). The server goes first, then the console, then the webmail, each checked once it is running again and put back as it was if not, which stops the upgrade there: a container by its old image tag, the server on the host by its old binary (kept as inbuxa-server.<version>), the console and the webmail on the host by their old directory. Before the server, which may convert its store on first start, it is stopped and its own data archived into <dir>/backups (--no-backup to skip; a store kept elsewhere, PostgreSQL or S3, is backed up where it lives). A server installed before the installer turned on its log files (#70) writes none, so the console's Logs page is empty: --key - with an API key made in the console gives it them, upgrade due or not. They go to /var/log/inbuxa on the host and /var/lib/inbuxa/logs on the data volume in a container, one file a day, deleted after 30 days on a new install (Settings › Security › Security, Log files). They hold IP and email addresses.

  • uninstall [--purge] -- takes away what the installer put on this machine: containers, units, binaries (and the old ones kept for rollback), the console's and the webmail's files, the webmail's user, its Node. The data stays -- the server's volumes or directory, Caddy's certificates, the credentials and secrets -- with the install record marked removed, so install run again brings it all back. --purge removes the data too, all but <dir>/backups, which it names for you to delete. Docker, and the configuration your own web server loads, are left alone. To take one component off, run install again with it skipped.

  • Running install again -- on a machine with an install recorded, every option not given on the command line or in --answers is the install's own: its shapes, its proxy, its names, its directory and ACME settings. So a run changes only what it is given (install --mail-host NAME renames, install --webmail skip takes the webmail off, install --webmail container puts it back), and the plan lists what it took from the install. A component the install doesn't have stays off until it is asked for. Installs made before 2026.11.18 didn't record the proxy or the front ends' names; those are read back from the deployment.

  • certs [--key KEY] -- the mail server's own certificate, the one its mail ports present: who issued it, until when, for which names, whether it verifies, and where the mail host resolves. Reading it needs nothing. Fixing it needs an API key made in the console, as join does (--key - or INBUXA_API_KEY; never written down): a new ACME order, which the server doesn't start again by itself once one has failed -- typically because DNS wasn't in place during the install -- or, on a domain not yet on ACME, ACME turned on where the managed Caddy or your own web server passes the challenges. It waits for the mail ports to present the new certificate. A mail host on another domain from the install's gets its certificate on that domain: the server's own, or one added for certificates only (no DKIM keys, nothing published), as the console's Order a certificate does, on the install's ACME account. A domain's default certificate names the server's hostname, so if that is still an old name it says where to change it first. The console's and the webmail's certificates are the proxy's, which renews them itself.

  • status -- what is installed, what is running, and where those two disagree: a container stopped by hand, or a deployment nothing recorded installing. It exits non-zero when they disagree, so a machine can be asked in a script whether it still matches itself.

  • relay install --token - -- inbuxa Relay, on a machine of its own in front of the server: the release's static inbuxa-relay binary, checked against a checksum in the source and against the inbuxa release keys' signature, owned by a user of its own so an upgrade from the console can replace it, under inbuxa-relay.service with ports 25 and 443 and nothing more. It joins with the token the console shows when you add the relay (--token - reads it from standard input, INBUXA_RELAY_JOIN_TOKEN works too), and refuses on a machine that runs the mail server or where port 25 is taken. --link-listen puts the link on one address, such as a WireGuard one. Run again, it converges, and leaves a newer binary from the console alone. relay status is the relay's own account of itself; relay uninstall keeps its state, and --purge resets it, which it refuses while it holds mail unless --discard-held.

  • Moving the server -- install run again with the other --server moves the mail server between a container and the host, with its configuration and mail. It needs an API key made in the console (--key - or INBUXA_API_KEY; never written down), because the server's listeners and its auto-ban exemptions change with the shape. Everything here stops for a minute or two. The data is archived into <dir>/backups first and then copied, never moved: the old copy -- the volumes, or <dir>/server -- stays where it was until you delete it, and a failure on the way puts the server back as it was. The interface doesn't offer it yet: it has no key to give.

The design is in the inbuxa specification (§6.1 and the installer draft); the phases are there too.

inbuxa install --local --domain example.test --install-deps --yes

is the shortest thing that works today: the whole suite on loopback, with no DNS and no certificates, on a machine that starts with nothing. Without --local it takes the real ports, puts Caddy in front and obtains certificates -- which e2e/cases/install-public.sh proves against a private CA, with no internet and no public name involved.

For an unattended install, put the options in a file and point --answers at it:

cat > answers.json <<'JSON'
{ "domain": "example.com", "email": "[email protected]", "proxy": "caddy" }
JSON
inbuxa install --answers answers.json --yes

A flag still wins over the file (--answers answers.json --server host), so one file can be a base a flag overrides.

Download

Each release has static binaries for linux/amd64 and linux/arm64, and a SHA256SUMS to check them against:

V=v2026.10.15.2   # the newest: https://git.coffeylabs.org/inbuxa/inbuxa-installer/releases/latest
curl -fLO https://git.coffeylabs.org/inbuxa/inbuxa-installer/releases/download/$V/inbuxa-linux-amd64
curl -fLO https://git.coffeylabs.org/inbuxa/inbuxa-installer/releases/download/$V/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
install -m 755 inbuxa-linux-amd64 /usr/local/bin/inbuxa

SHA256SUMS is signed with minisign, so you can confirm it came from us before trusting the checksums. SHA256SUMS.minisig is the signature:

curl -fLO https://git.coffeylabs.org/inbuxa/inbuxa-installer/releases/download/$V/SHA256SUMS.minisig
minisign -Vm SHA256SUMS -P RWS1yFYwVuJ7MGJTZXLbhv9+hrEsjrC8Zg+7WmPlM86Sjy0qF/xkoCKq

The same public key signs every inbuxa release (installer, migrate and cli).

A release is a tag on main named with the INBUXA suite's release number: v27.1 for a series, v27.1.3 for a patch, v27.1-rc.1 for a release candidate (before 27.1 the tags were dated, v2026.10.15.2). .gitea/workflows/release.yml builds it with scripts/build-release.sh, which builds the same thing locally. A release candidate is published as a pre-release, so releases/latest stays on the last final release.

Shell completions and a man page

The binary writes its own, so there is nothing extra to download. For completion of the commands, flags and their values:

inbuxa completions bash | sudo tee /etc/bash_completion.d/inbuxa >/dev/null
inbuxa completions zsh  > "${fpath[1]}/_inbuxa"      # a directory on your $fpath
inbuxa completions fish > ~/.config/fish/completions/inbuxa.fish

For the manual page:

inbuxa man | sudo tee /usr/share/man/man1/inbuxa.1 >/dev/null
man inbuxa

Both are generated from the command list, so they match the binary you have.

Building and testing

go build ./cmd/inbuxa

The installer writes units, creates users and takes ports 25 and 443, so it is tested on a throwaway virtual machine rather than on anybody's desk:

e2e/vm/up.sh                              a Debian 13 machine, in qemu, as you
DISTRO=fedora e2e/vm/up.sh                or fedora, rocky9, ubuntu2404, arch, debian12
e2e/vm/run.sh e2e/cases/survey.sh         what it says about a machine
e2e/vm/run.sh e2e/cases/deps.sh           the offer, and taking it
e2e/vm/run.sh e2e/cases/install-local.sh   a whole suite, and signing in to it
e2e/vm/run.sh e2e/cases/install-public.sh  the same with real ports and certificates
e2e/vm/run.sh e2e/cases/install-host.sh    the server on the host, the rest beside it
e2e/vm/run.sh e2e/cases/join.sh           front ends joined to a server elsewhere
e2e/vm/run.sh e2e/cases/join-host.sh      the same on the host, behind nginx, no containers
e2e/vm/run.sh e2e/cases/interface.sh      the interface, driven key by key in a terminal
e2e/vm/run.sh e2e/cases/proxy-snippets.sh  behind nginx, from the configuration it writes
e2e/vm/run.sh e2e/cases/webmail-host.sh    the webmail on the host, and signing in to it
e2e/vm/run.sh e2e/cases/all-host.sh        everything on the host, behind nginx, no containers
OLD_REF=v2026.10.12.1 e2e/vm/run.sh e2e/cases/upgrade-containers.sh
                                          an older install moved to these releases
OLD_REF=v2026.10.12.1 e2e/vm/run.sh e2e/cases/upgrade-host-server.sh
                                          the same on the host, and a bad release put back
CONSOLE_TARBALL=… WEBMAIL_TARBALL=… e2e/vm/run.sh e2e/cases/upgrade-frontends-host.sh
                                          the console and the webmail on the host, moved on
OLD_REF=v2026.10.12.3 e2e/vm/run.sh e2e/cases/rerun-host-server.sh
                                          install run again: restarted when it must be, only then
e2e/vm/run.sh e2e/cases/uninstall-containers.sh  uninstalled, installed again on the data, purged
e2e/vm/run.sh e2e/cases/uninstall-host.sh  the same with the server and the webmail on the host
e2e/vm/run.sh e2e/cases/certs.sh          a failed order, reported, then fixed with a key
e2e/vm/run.sh e2e/cases/move-server.sh    the server into the host and back, keeping its mail
e2e/vm/run.sh e2e/cases/topology.sh       growing and shrinking from a file
e2e/vm/run.sh e2e/cases/status-export.sh  intent against reality, and the file
OLD_REF=<commit> e2e/vm/run.sh e2e/cases/upgrade-volumes.sh
                                          an install from before #5, upgraded
DISTRO=fedora e2e/vm/run.sh e2e/cases/selinux.sh
                                          the SELinux-sensitive paths, with it enforcing
e2e/vm/down.sh                            remove it

SERVER_BINARY=path/to/inbuxa e2e/vm/run.sh … installs a server build instead of the release wherever a case installs the server on the host (the installer's INBUXA_SERVER_BINARY), for testing a server change before it is released. CONSOLE_TARBALL= and WEBMAIL_TARBALL= do the same for the console's and the webmail's release tarballs (INBUXA_CONSOLE_TARBALL, INBUXA_WEBMAIL_TARBALL).

Each case starts from a copy of the machine taken when it was new, so a run is free to break it and a failure is the installer's rather than the last run's leftovers. e2e/vm/up.sh needs qemu, KVM and xorriso; nothing needs root on your machine.

On Fedora and Rocky the machine runs SELinux enforcing, and the installer has to live within it -- a container could not once read a directory mounted into it. So on those two, run.sh reads the audit log after any case and fails the run if the installer provoked an SELinux denial, even one the case survived; SELINUX_IGNORE=1 downgrades that to a warning. e2e/cases/selinux.sh drives the paths that have been caught before (the backup archives the server's volumes through a container) and checks them directly; on a distribution without SELinux enforcing it skips and passes.

License

AGPL-3.0-or-later. Some of this began as ihasmail-oneshot, which is ours and under the same license.