Install it · 5 of 9
1. The mail server
Step one: install the inbuxa mail server, from the published image, the release binary or source, and bring it up in bootstrap mode ready for the console.
On this page
- Before you start
- Install
- Run it under systemd
- What bootstrap mode is
- Setting it up from a file instead
- Check it worked
- If it doesn't start
- The server's environment
- Listener ports for a new server
- Passwords outside DAV
- Proxies the server believes
- Mail through a load balancer that sends PROXY headers
- Certificates renewed outside the server
- A top-level domain of your own
- Next
- Undoing it
inbuxa-server is the whole mail system in one program: JMAP, IMAP, POP3,
SMTP, CalDAV, CardDAV and WebDAV, the store, the filters and the
administration API. Install it first — the console and the webmail both need
it running.
This page ends with a server in bootstrap mode, waiting for the console to complete its first boot.
Coming from Stalwart
Install the program from this page, but don't start it in bootstrap mode. Coming from Stalwart writes its configuration first, and imports the old store before it ever starts.
Before you start
- A Linux machine with Docker, or with systemd if you would rather run the release binary or build it yourself.
- A hostname for the server, pointed at that machine. It does not have to resolve yet, but certificates cannot be issued until it does.
- Somewhere to keep two directories: one for configuration, one for data.
mail.example.com. A 198.51.100.10
Install
The image is public and built for linux/amd64 and linux/arm64:
docker pull registry.coffeylabs.org/inbuxa/inbuxa-server:latest
It runs as an unprivileged user and keeps configuration in /etc/inbuxa
and data in /var/lib/inbuxa, both of which should be volumes:
docker run -d --name inbuxa-server \
-v inbuxa-config:/etc/inbuxa \
-v inbuxa-data:/var/lib/inbuxa \
-p 25:25 -p 465:465 -p 587:587 -p 993:993 -p 443:443 \
-p 127.0.0.1:8080:8080 \
registry.coffeylabs.org/inbuxa/inbuxa-server:latest
Port 8080 is the setup port, and it is bound to loopback here on purpose:
reach it over an SSH tunnel rather than exposing it. Add -p 995:995 and
-p 4190:4190 if you want POP3 and ManageSieve.
The server holds no Linux capabilities, not even the one for ports below
1024. Docker lets any user listen on those inside a container's own
network, so the command above needs nothing more. Podman doesn't, and
neither does --network host: with Podman, add
--sysctl net.ipv4.ip_unprivileged_port_start=0; on the host's network,
add --cap-add NET_BIND_SERVICE. Or move the listeners above 1024 with
INBUXA_LISTENER_PORTS.
Each release has binaries for linux/amd64 and linux/arm64, and a
SHA256SUMS to check them against:
V=v2026.11.11 # the newest is at git.coffeylabs.org/inbuxa/inbuxa-server/releases
A=arm64 # or amd64
curl -fLO https://git.coffeylabs.org/inbuxa/inbuxa-server/releases/download/$V/inbuxa-linux-$A.tar.gz
curl -fLO https://git.coffeylabs.org/inbuxa/inbuxa-server/releases/download/$V/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS
tar xzf inbuxa-linux-$A.tar.gz
sudo install -m 0755 inbuxa /usr/local/bin/inbuxa
inbuxa --version
The binaries need glibc 2.39 or newer: Debian 13, Ubuntu 24.04, Fedora 40, Raspberry Pi OS based on Debian 13, and Arch are all new enough. On Debian 12, Ubuntu 22.04, Rocky 9 or Raspberry Pi OS based on Debian 12 it won't start; use the image there, or build from source.
Then run it under systemd.
git clone https://git.coffeylabs.org/inbuxa/inbuxa-server.git
cd inbuxa-server
cargo build --release -p inbuxa
sudo install -m 0755 target/release/inbuxa /usr/local/bin/inbuxa
The build needs a current Rust toolchain, and takes a while on small machines. For an ARM board, the release binary saves cross-compiling. Then run it under systemd.
Or build the same image the release publishes:
docker build -t inbuxa .
The server always needs --config <PATH> (or CONFIG_PATH in the
environment). The image supplies it already. What decides the mode is whether
a file exists at that path, not whether you passed the option.
Run it under systemd
Without a container, give the server its own user and the three directories
the image would have: configuration in /etc/inbuxa, data in
/var/lib/inbuxa, and log files in /var/log/inbuxa. The server writes its
configuration at the end of first boot, so it has to own /etc/inbuxa too.
sudo useradd --system --user-group --no-create-home --shell /usr/sbin/nologin inbuxa
sudo install -d -o inbuxa -g inbuxa /etc/inbuxa /var/lib/inbuxa /var/log/inbuxa
Then the service, as /etc/systemd/system/inbuxa.service:
[Unit]
Description=inbuxa mail server
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=inbuxa
Group=inbuxa
ExecStart=/usr/local/bin/inbuxa --config /etc/inbuxa/config.json
WorkingDirectory=/var/lib/inbuxa
AmbientCapabilities=CAP_NET_BIND_SERVICE
LimitNOFILE=65536
KillSignal=SIGINT
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now inbuxa
journalctl -u inbuxa | grep -A4 "bootstrap mode"
AmbientCapabilities lets the unprivileged user bind the mail ports and 443,
which are all below 1024. Bootstrap mode needs only port 8080, so without it
first boot still works, but afterwards only the higher ports open.
sudo setcap cap_net_bind_service=+ep on the binary does the same, but is
lost whenever the binary is replaced.
Don't copy the unit from the repository as it is
resources/systemd/inbuxa.service in the source has
ConditionPathExists= on the configuration file. A new server has no
configuration file yet, so systemd skips it without starting it, and
bootstrap mode never happens. Use the unit above, or remove that line.
Once first boot is done, it's worth putting it back, in the [Unit]
section, so a server that ever loses its configuration stays down rather
than coming back up in bootstrap mode:
ConditionPathExists=/etc/inbuxa/config.json
What bootstrap mode is
With no configuration file at that path, the server starts in bootstrap mode: it opens port 8080 and nothing else, and prints a temporary administrator to its log, once.
════════════════════════════════════════════════════════════
🔑 INBUXA bootstrap mode - temporary administrator account
username: admin
password <shown once, here>
This password is shown only once. To pin a credential
instead, set INBUXA_RECOVERY_ADMIN=admin:<password> in the
server's environment and restart it.
════════════════════════════════════════════════════════════
Copy that password before you do anything else. If you lose it, stop the
server, set INBUXA_RECOVERY_ADMIN=admin:<password> in
its environment and start it again.
No mail ports are open yet, and there is no web interface on this host at any point: the console is what completes setup, over JMAP.
Setting it up from a file instead
From 27.1-rc.32 a new server can skip bootstrap mode and the console's setup
steps: --seed reads the first settings from a file. That suits an install
you describe in files rather than click through, such as a Kubernetes chart
or a configuration management tool. The inbuxa Helm chart, in development
for 27.1, runs it for you from its server.seed value.
The server needs its config.json (the data store) as usual. The seed file
is a JMAP request: the calls you would send to /jmap to set the server up,
in order. A later call can name something an earlier one created by its
creation id, "#d" below. A password or key is never written in the file:
{"$file": "/path"} stands for the contents of that file, so it can come
from a mounted secret.
{
"using": ["urn:ietf:params:jmap:core", "urn:inbuxa:jmap:registry"],
"methodCalls": [
["x:Domain/set", {"create": {"d": {
"name": "example.org",
"dkimManagement": {"@type": "Automatic"}
}}}, "domain"],
["x:SystemSettings/set", {"update": {"singleton": {
"defaultHostname": "mail.example.org",
"defaultDomainId": "#d"
}}}, "settings"],
["x:Account/set", {"create": {"admin": {
"@type": "User", "name": "admin", "domainId": "#d",
"roles": {"@type": "Admin"},
"credentials": {"0": {"@type": "Password",
"secret": {"$file": "/run/secrets/admin-password"}}}
}}}, "admin"]
]
}
inbuxa --seed /etc/inbuxa/seed.json --config /etc/inbuxa/config.json
It upgrades the store's layout if it needs to, writes the settings a first start writes, runs the calls as the system administrator and exits. It opens no ports. Start the server normally afterwards.
A seed is for a new store, once. The store remembers it was seeded, so running it again does nothing, even if the file has changed since: from then on, change settings in the console. The exit code says what happened:
| Code | Meaning |
|---|---|
| 0 | The seed was applied, or was applied to this store before |
| 1 | A call failed. The message names it. The store may hold part of the seed: finish the setup in the console, or start again with an empty store |
| 2 | Refused: the store was already set up another way, or an earlier seed run stopped partway. Nothing was changed |
A seed that fails partway isn't retried, because running it again would
create things twice. In Kubernetes, give its Job backoffLimit: 0, as the
chart does.
Check it worked
docker logs inbuxa-server 2>&1 | grep -i "bootstrap mode" # or: journalctl -u inbuxa | grep -i "bootstrap mode"
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/healthz/live
You want the bootstrap line, and 200 from the health check:
Server started in bootstrap mode ... details = "No configuration file was
found. Port 8080 is open for initial setup." version = "2026.10.10.1 (upstream 0.16.25)"
A DNSSEC warning in the log at this point is normal on a machine whose resolver cannot validate: DANE is disabled rather than deferring mail. Fix the resolver before you carry real mail.
If instead the server printed its --help and exited, it was given no
configuration path at all. Under systemd, systemctl status inbuxa saying
the start condition failed means the unit checks for a configuration file
that doesn't exist yet; see the warning above.
If it doesn't start
When the server can't open its data store, its last lines say why, and it exits with a code of its own, so a supervisor or a script can tell the cases apart:
| Exit | The line starts | Check |
|---|---|---|
| 78 | data store: bad configuration |
config.json, the secret files it names, and the database name |
| 69 | data store: unreachable |
that the database is running, and its host and port are reachable from the server |
| 77 | data store: credentials refused |
the user name and password, and that the user may use the database |
| 76 | data store: TLS failed |
that the database offers TLS, and that its certificate is trusted |
| 1 | data store: error |
the rest of the line |
For example, with the wrong password:
⚠️ Startup failed: data store: credentials refused: failed to create tables: PostgreSQL error
(store.postgresql-error): reason = db error: FATAL: password authentication failed for user
"inbuxa", code = 28P01
Check the user name and password, and that the user may use the database.
PostgreSQL's errors are told apart fully. With other stores, anything but bad configuration exits with 1. Server 27.1-rc.32 and later; before that, every case exits with 1.
To check the whole data layer without starting the server, run it with
--check. It opens the data store, writes, reads and deletes a small object
in the blob store, and connects to NATS, then prints a line for each:
ok data store
ok blob store: wrote, read and deleted a test object
ok coordinator: NATS 2.15.2 at nats.example.test:4222
A part it can't use is named the same way, as blob store: or
coordinator: in place of data store:, with the same exit codes. The Helm
chart runs it before each server pod starts. Server 27.1-rc.33 and later.
The server's environment
A few settings are read from the server's environment rather than from
config.json: INBUXA_RECOVERY_ADMIN above, and the addresses of
the console and
the webmail. The server reads
them when it starts, so restart it after changing one.
Listener ports for a new server
A new server listens on 25 (SMTP), 465 (submission), 993 (IMAP), 995 (POP3), 4190 (ManageSieve), 443 (HTTPS) and 8080 (HTTP). Where it can't have ports below 1024, as in a Kubernetes pod with every capability dropped, move them or leave some out:
INBUXA_LISTENER_PORTS=smtp=2525,submissions=4465,imaps=9993,pop3s=off,https=8443
The names are smtp, submissions, imaps, pop3s, sieve, https and
http; off leaves that listener out. The server checks it on every start
and refuses to start over a mistake in it, but uses it only once: when it
creates its listeners, on a store that has none. After that they are
settings like any other, changed in the console under
Settings › Network › Listeners (ports).
Publish the outside ports onto the new ones, -p 25:2525 and so on.
Passwords outside DAV
JMAP and the management API take a token, never a password: an OAuth sign-in or an API key. Only CalDAV and CardDAV take a password, because that is how calendar and contacts apps sign in. For a job that needs passwords on JMAP for a while, such as moving accounts, set:
INBUXA_HTTP_BASIC_AUTH=all
dav, or leaving it unset, is the default. Take it out again when the job
is done.
Proxies the server believes
With Obtain remote IP from Forwarded header
on, the server reads the visitor's address from X-Forwarded-For, but only
on connections from a proxy it trusts. By default that
is any address on the same machine or a private network: loopback
(127/8, ::1), the private ranges of RFC 1918 (10/8, 172.16/12,
192.168/16), shared address space (100.64/10), and IPv6 unique local and
link-local addresses (fc00::/7, fe80::/10). A connection from anywhere else counts as the
visitor itself, whatever its headers say.
When the request has passed through several proxies, the visitor is the last address in the header that isn't a trusted proxy. Anything in front of it was written by the visitor and is ignored. If your proxy connects from a public address, or you'd rather trust fewer networks, list them yourself:
INBUXA_HTTP_TRUSTED_PROXIES="127.0.0.1 ::1 203.0.113.10"
The list replaces the default. Separate entries with spaces or commas, and give
either an address or a network such as 203.0.113.0/24.
The server reads one header only, the one your proxy writes. nginx, Caddy,
Traefik and HAProxy's option forwardfor write X-Forwarded-For, the default.
If your proxy writes the RFC 7239 Forwarded header instead, such as HAProxy's
option forwarded, say so:
INBUXA_HTTP_FORWARDED_HEADER=forwarded
The other header is ignored, because a proxy passes it through as the visitor
sent it. Server 27.1-rc.27 and 2026.11.17 and later; before those, a visitor
could send a Forwarded header past a proxy that writes only
X-Forwarded-For.
A loopback address in the header counts as this machine only when the request came from this machine all the way. If a proxy on another machine reports a loopback visitor, the server takes that proxy as the visitor.
To turn the header on from the environment instead of the console, set:
INBUXA_HTTP_USE_FORWARDED=true
true or false overrides the console's setting; leave it unset to use the
console's. Do this when the server is only ever reached through your own
proxies, such as behind an ingress or with the webmail in front. Otherwise
the server counts every visitor as the proxy: by default, 100 wrong passwords a day,
from anyone, ban the proxy, and with it everyone behind it. Server
27.1-rc.32 and later.
Mail through a load balancer that sends PROXY headers
A load balancer in front of the server hides each sender's address unless
it passes it on. Many can, in a PROXY protocol header at the start of each
connection: AWS and other cloud network load balancers, HAProxy with
send-proxy-v2. Give the mail listeners a second port for those
connections, and name the load balancer's own addresses:
INBUXA_MAIL_PROXY_LISTENERS=smtp=10025,submissions=10465,imaps=10993
INBUXA_MAIL_PROXY_TRUSTED_NETWORKS="198.51.100.10 198.51.100.11"
Each listener named gets a copy on the port given, with the same protocol and TLS. The copy takes the sender's address from the PROXY header, but only on connections from the addresses listed; from anywhere else, the header is not believed. The listeners it copies carry on as before. Point the load balancer at the new ports, and have it listen on the standard ones (25, 465, 993): the server tells mail from the internet by port 25, which it reads from the header.
Name the load balancer's addresses, never a whole network the load balancer shares with others: anyone who can connect from a trusted address can claim to be any sender. Networks wider than /8 are refused. Server 27.1-rc.32 and later.
Certificates renewed outside the server
When something else issues and renews the certificates (cert-manager, a
script with certbot), point the server at the files instead of storing
them. Name directories that each hold tls.crt (the certificate, then its
chain) and tls.key, the layout of a Kubernetes TLS Secret:
INBUXA_TLS_CERTIFICATE_DIRS=/etc/inbuxa/tls/mail,/etc/inbuxa/tls/mx
The server uses each certificate for the names in it. The certificates aren't stored, and don't show in the console. A certificate in the console can point at files too: give its certificate and private key as files.
Either way, each server checks the files once a minute, and a renewal is in use within about a minute of the files changing, with no restart. A Kubernetes Secret takes up to another minute to reach the pods, so count on two. A directory that can't be read, or a certificate that has expired, is logged and left out. Server 27.1-rc.33 and later.
A top-level domain of your own
The server accepts a domain only when it ends in a public suffix, such as
.com or .co.uk, or in one of the names reserved for private networks:
.internal, .lan, .home, .local, .test, .corp, .private,
.intranet, .localdomain and .localhost. If your own DNS serves a
top-level domain of its own, name it in INBUXA_PRIVATE_TLDS, before first
boot if the server's hostname or default domain uses it:
INBUXA_PRIVATE_TLDS=myownlab
Separate several with commas or spaces. A suffix of more than one label, such
as home.arpa, works too. Domains under them are then accepted everywhere a
domain is: the setup wizard, domains, addresses and directory sign-ins.
INBUXA_PRIVATE_TLDS is newer than release 2026.10.10.1: it needs the next
release, or a server built from source since 11 October 2026. An older server
ignores it.
Pass each one with -e when you create the container, or keep them in a
file and pass --env-file:
docker run -d --name inbuxa-server \
-e INBUXA_ADMIN_URL=https://console.example.com \
...
A container's environment is fixed when it is created, so changing one means removing the container and running it again. The volumes keep everything else.
If you start the binary by hand, put them in front of the command:
INBUXA_ADMIN_URL=https://console.example.com \
inbuxa --config /etc/inbuxa/config.json
Under systemd, add them to the service with sudo systemctl edit inbuxa:
[Service]
Environment=INBUXA_ADMIN_URL=https://console.example.com
Then sudo systemctl restart inbuxa. For a secret such as
INBUXA_WEBMAIL_CLIENT_SECRET, use EnvironmentFile= pointing at a file
only root can read, instead of Environment=.
Next
Install the console, point it at this server, and complete first boot. Until that is done the server carries no mail.
If nginx already holds ports 80 and 443 on this machine, put the server behind it.
Undoing it
Nothing has been written outside the two volumes, so removing them is a clean slate:
docker rm -f inbuxa-server
docker volume rm inbuxa-config inbuxa-data
Once the server is set up, those volumes are your installation: back them up before an upgrade, and keep them if you ever rebuild the container.
sudo systemctl disable --now inbuxa
sudo rm /etc/systemd/system/inbuxa.service /usr/local/bin/inbuxa
sudo rm -r /etc/inbuxa /var/lib/inbuxa /var/log/inbuxa
sudo userdel inbuxa
Once the server is set up, /etc/inbuxa and /var/lib/inbuxa are your
installation: back them up before an upgrade, and keep them if you only
mean to reinstall the binary.