docs
Try the demo Get started
Esc
↑↓ moveEnter openEsc close

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.

12 min read

On this page

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.