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

Install it · 5 of 9

2. The console

Step two: install inbuxa Admin, the console, and use it to complete the server's first boot over JMAP.

7 min read

On this page

inbuxa Admin is the administration interface: every server setting, first boot, and recovery, in the browser. It is static files that talk to the mail server from the reader's browser, so it holds no data and keeps no state of its own.

It is also what completes the server's first boot, so install it next.

Not on the mail host

The console is a separate deployment, and putting it on the mail server gives that machine a web surface it is designed not to have. Run it somewhere else — another host, or your workstation while you set things up. Why.

Before you start

  • The mail server running in bootstrap mode, and the temporary admin password from its log.
  • A hostname for the console, or a loopback port if you are only setting things up. Decide it now: the server registers the console's redirect address, and it has to match.

Tell the server where the console is

The server registers its first-party OAuth clients on every start. Set the console's address in the server's environment, then restart the server (how, with or without a container):

INBUXA_ADMIN_URL=https://console.example.com

That registers the client id inbuxa-admin with the redirect https://console.example.com/oauth/callback. An address that does not match the console's real one is the usual cause of a sign-in that bounces straight back.

Once set up, the server sends the console to its sign-in page at https:// and its hostname. If browsers reach the server some other way, through a different name or port, set that address too:

INBUXA_PUBLIC_URL=https://mail.example.com:8443

On Dokploy, Coolify or Portainer?

On a platform you already run has the console and the webmail as one compose file, for a platform that already puts a proxy and certificates in front of its containers.

Install

docker pull registry.coffeylabs.org/inbuxa/inbuxa-admin:latest
docker run -d --name inbuxa-admin \
  -e API_BASE_URL=https://mail.example.com \
  -p 127.0.0.1:8081:8080 \
  registry.coffeylabs.org/inbuxa/inbuxa-admin:latest

API_BASE_URL is read at container start and written into the page, so one image serves any installation. Put your reverse proxy in front of port 8080; the image serves plain HTTP and expects TLS to be terminated for it.

Building it needs Node.js 22 or newer, and npm, which comes with it. Nothing else has to be installed: the build tool, Vite, is one of the project's dependencies, so npm ci fetches it.

git clone https://git.coffeylabs.org/inbuxa/inbuxa-admin.git
cd inbuxa-admin
npm ci
VITE_API_BASE_URL=https://mail.example.com npm run build

dist/ is then static files, and the console needs no Node.js or any other program running once it is built. Instead of building the address in, you can leave VITE_API_BASE_URL out and set the tag in dist/index.html when you deploy it:

<meta name="api-base-url" content="https://mail.example.com">

Copy dist/ to any web server, at the root of the console's hostname rather than under a path. The server has to answer with index.html for every path that isn't a file, or the sign-in's return to /oauth/callback is a 404. In nginx:

server {
    listen 443 ssl;
    server_name console.example.com;
    # ssl_certificate and ssl_certificate_key as usual

    root /var/www/inbuxa-admin;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # The file names under assets/ change with every build.
    location /assets/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # index.html names the current build, so it is never cached.
    location = /index.html {
        add_header Cache-Control "no-cache";
    }
}

In Caddy, try_files {path} /index.html before file_server does the same.

Reach the server during first boot

https://mail.example.com doesn't answer yet. A server in bootstrap mode listens on port 8080 and nothing else, and the server page binds that port to loopback. A console pointed at port 443 before first boot stops at Failed to fetch, because the browser gets no answer at all.

For first boot, run a temporary console on your workstation, or on the mail server if your workstation has no Docker, and reach 8080 over SSH:

ssh -N -L 8080:localhost:8080 you@mail.example.com &
docker run -d --rm --name inbuxa-admin-setup \
  -e API_BASE_URL=http://localhost:8080 \
  -p 127.0.0.1:8081:8080 \
  registry.coffeylabs.org/inbuxa/inbuxa-admin:latest

Then open http://localhost:8081.

In the checkout from the step above, run the development server instead of building:

ssh -N -L 8080:localhost:8080 you@mail.example.com &
npm run dev

Then open http://localhost:5173. The repository's .env.development already points the development server at http://localhost:8080, so there is nothing to set.

Run the temporary console on the mail server instead, bound to loopback, and forward both ports with one SSH command. The console page comes from 8081, and the page then talks to the server on 8080, so your browser needs both:

# on the mail server
docker run -d --rm --name inbuxa-admin-setup \
  -e API_BASE_URL=http://localhost:8080 \
  -p 127.0.0.1:8081:8080 \
  registry.coffeylabs.org/inbuxa/inbuxa-admin:latest

# on the machine with your browser
ssh -N -L 8080:localhost:8080 -L 8081:localhost:8081 you@mail.example.com

Then open http://localhost:8081. Forwarding only one of the two ports gives connection refused (no 8081) or Failed to fetch (no 8080). If the server runs without a container and there is no Docker on it either, build the console from source on your workstation and use the tab before this one.

Bootstrap mode accepts the console at any address, so the server's INBUXA_ADMIN_URL doesn't need to match this temporary one.

After Finish setup and the server's restart, the mail ports and 443 are open. Stop the temporary console and close the tunnel. From then on, the console at its permanent address, pointed at https://mail.example.com, is the one you use.

DNS through Cloudflare or another proxy

Keep the mail server's hostname DNS only, not proxied. The proxy carries neither SMTP nor IMAP, so the name has to lead to the server itself.

Complete first boot

Coming from Stalwart

Skip this section. A server imported from Stalwart has its hostname, domains, certificates and accounts already, and never runs first boot. Sign in with an administrator account the old server had. See Coming from Stalwart.

Open the console and sign in with the bootstrap admin account. Welcome to inbuxa walks through five steps, all sent to the server over JMAP:

  1. Server Identity: the server's hostname, the default email domain, and whether to get a TLS certificate automatically and generate email signing (DKIM) keys. A domain under a top-level domain your own DNS serves is refused unless the server knows about it.
  2. Storage: where mail, attachments and files, the search index, and the cache go. The defaults keep everything in the built-in store.
  3. Account Directory: whether people sign in with accounts kept in inbuxa itself, or against an existing directory. See Directories and SCIM.
  4. Logging: where the log goes. The default is log files on disk, in /var/log/inbuxa; Console sends it to the container's output instead.
  5. Automatic DNS Management: whether the server publishes its own DNS records through your DNS host's API. It can be set up later instead; see DNS, DKIM and certificates.

Finish setup creates the permanent administrator and shows its credentials once. Then restart the server: the new configuration takes effect at the restart, and from then on you sign in with those credentials.

The wizard doesn't create mailboxes. Add people afterwards, in the console or in the webmail's Administration.

A server that is already configured refuses bootstrap credentials, so the wizard cannot be pointed at a live server by accident.

Write down the permanent administrator

The credentials are shown once, and the password can't be shown again. The temporary admin account stops working after the restart. The account the wizard creates is the one you keep.

If the console says Failed to fetch after first boot

After the restart the console talks to https://mail.example.com, and any request the browser can't complete shows only as Failed to fetch (NetworkError when attempting to fetch resource in Firefox). The browser's developer tools (F12, then Network) show which request failed. The usual causes, most common first:

  • The server's certificate isn't trusted yet. Until it has a certificate of its own, the server answers with a self-signed one, and browsers refuse that on the console's background requests without asking. Open https://mail.example.com/healthz/live in a tab: a certificate warning there is the cause. With the automatic certificate on, the server asks Let's Encrypt for one, which needs the name to point at the server, port 443 open from the internet and, behind Cloudflare, DNS only. To carry on meanwhile, accept the warning in that tab and reload the console. You can also upload a certificate under Settings › Security › Certificates.

  • The console points somewhere else. API_BASE_URL (or the api-base-url tag) must be the server's real address, exactly.

  • The server doesn't recognize the console. After first boot the server answers the console only at the exact address in INBUXA_ADMIN_URL, scheme, host and port included. A container keeps the environment it was created with, so after changing it, recreate the container (docker compose up -d --force-recreate); a restart keeps the old value.

  • Something in between answers instead. A reverse proxy or a firewall with HTTP inspection in front of the server can drop the browser's CORS preflight. This sends the same one:

    curl -si -X OPTIONS https://mail.example.com/jmap/session \
      -H 'Origin: https://console.example.com' \
      -H 'Access-Control-Request-Method: GET' \
      -H 'Access-Control-Request-Headers: authorization'
    

    A healthy server answers 204 with access-control-allow-origin: https://console.example.com.

  • Only 8080 is open. A server run without a container needs permission to bind the ports below 1024; see Run it under systemd.

Check it worked

  • The console signs in, and the dashboard names who is signed in.
  • The server's log no longer says bootstrap mode after a restart; a configuration file now exists at the path you gave it.
  • The server is listening on its mail ports, not only 8080.
  • Your domain appears in the console with DKIM keys, and its DNS records are offered for publishing.
docker logs inbuxa-server 2>&1 | tail -5   # or: journalctl -u inbuxa -n 5

With the default log files, docker logs (or the journal) shows only what the server printed before it read its configuration. The rest is in /var/log/inbuxa, or in the console under Management › Observability › Logs.

Next

Install the webmail, so that the mailbox you just made can be read by the person who owns it.

Before mail flows, publish the MX, SPF, DKIM and DMARC records the console gives you. Mail will not be delivered to you, and what you send will be treated as suspicious, until they are live.

Undoing it

The console holds nothing, so removing it removes nothing:

docker rm -f inbuxa-admin

Delete the files you copied from dist/ and the web server's site for the console.

The registered OAuth client stays on the server; it is reused if you put the console back at the same address. Changing that address means setting INBUXA_ADMIN_URL again and restarting the server, which registers the new redirect.