Install it · 5 of 9
3. The webmail
Step three: install inbuxa webmail, the mail, calendar, contacts and files client people sign in to, and connect it to the server with OAuth.
On this page
inbuxa webmail is what everyone who is not an administrator uses: mail, calendars, contacts, files and filters, on a phone as readily as a desktop.
It goes last, because it needs a server that is set up and an account to sign in with. Like the console, it is its own deployment and does not belong on the mail host.
Before you start
- The mail server set up, and the console used at least once, so that a mailbox exists.
- A hostname for the webmail. It has to match what you tell the server, exactly.
- Two secrets: one for sealing sessions, one shared with the server for OAuth.
openssl rand -base64 48 # APP_SECRET
openssl rand -base64 32 # the shared OAuth client secret
Tell the server where the webmail is
Sign-in happens on the server's own page, so the server has to know the webmail before the webmail can use it. Set both of these in the server's environment and restart it:
INBUXA_WEBMAIL_URL=https://webmail.example.com
INBUXA_WEBMAIL_CLIENT_SECRET=<the shared secret>
That registers the confidential client ihasmail-inbuxa with the redirect
https://webmail.example.com/api/auth/callback.
The two addresses must agree
The webmail builds its redirect from PUBLIC_URL + BASE_PATH +
/api/auth/callback, and the server will only accept the one it
registered from INBUXA_WEBMAIL_URL. A trailing slash or a missing
BASE_PATH on either side is enough to break sign-in. Setting
INBUXA_WEBMAIL_URL without the secret registers nothing, and the server
says so in its log.
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-webmail:latest
docker run -d --name inbuxa-webmail \
-e MAIL_SERVER_URL=https://mail.example.com \
-e APP_SECRET=<session secret> \
-e OAUTH_CLIENT_SECRET=<the shared secret> \
-e PUBLIC_URL=https://webmail.example.com \
-e ADMIN_URL=https://console.example.com \
-e APP_NAME=inbuxa \
-p 127.0.0.1:8080:8080 \
registry.coffeylabs.org/inbuxa/inbuxa-webmail:latest
Put your reverse proxy in front: the app serves plain HTTP and expects TLS to be terminated for it.
The webmail is a small Node.js server, not only static files: it holds the sessions and passes the browser's requests on to the mail server. Building and running it needs Node.js 20.19 or newer, and npm, which comes with it.
git clone https://git.coffeylabs.org/inbuxa/inbuxa-webmail.git
cd inbuxa-webmail
npm ci
npm run build
cp .env.example .env
Then set these in .env, alongside the defaults already there:
NODE_ENV=production
HOST=127.0.0.1
PORT=8080
MAIL_SERVER_URL=https://mail.example.com
APP_SECRET=<session secret>
OAUTH_CLIENT_SECRET=<the shared secret>
PUBLIC_URL=https://webmail.example.com
ADMIN_URL=https://console.example.com
APP_NAME=inbuxa
npm start runs it, reading .env from the directory it starts in. To
keep it running, give it a service of its own, for example under systemd
with the checkout in /opt/inbuxa-webmail:
[Unit]
Description=inbuxa webmail
After=network-online.target
Wants=network-online.target
[Service]
User=inbuxa-webmail
WorkingDirectory=/opt/inbuxa-webmail
ExecStart=/usr/bin/node server/dist/index.js
Restart=on-failure
[Install]
WantedBy=multi-user.target
The only place it writes is data/, where SESSION_FILE keeps sessions
across restarts, so that is the one directory the service's user needs to
own:
sudo useradd --system --no-create-home inbuxa-webmail
sudo install -d -o inbuxa-webmail /opt/inbuxa-webmail/data
sudo systemctl enable --now inbuxa-webmail
Put your reverse proxy in front of 127.0.0.1:8080, as with the image;
the checkout has nginx.example.conf and Caddyfile.example to start
from. To upgrade, git pull, npm ci and npm run build again, then
restart the service.
docker compose up --build -d in the checkout builds and runs the same
thing in a container instead.
What the settings mean
| Variable | Meaning |
|---|---|
MAIL_SERVER_URL |
How the webmail reaches the server |
APP_SECRET |
Seals sessions. Required in production |
OAUTH_CLIENT_SECRET |
The shared secret; turns on sign-in through the server's page |
OAUTH_CLIENT_ID |
Defaults to ihasmail-inbuxa, which is what the server registers |
PUBLIC_URL |
Where browsers reach the webmail, without BASE_PATH |
ADMIN_URL |
Optional: where the console is, for the dashboard's link |
APP_NAME |
What the webmail calls itself |
MAIL_SERVERS_FILE |
Optional: several servers, picked by the account's domain |
ADMINISTRATION |
On unless 0. Off turns the webmail's Administration off for everyone, including the requests behind it. The console is unaffected |
NODE_NAME |
Optional: this webmail's name, shown in Settings › About. Worth setting when one webmail runs per cluster node |
The rest are in .env.example.
Check it worked
- The sign-in page loads and asks only whether this is your own device — not for an address, when there is one server.
- Signing in hands you to the server's page, and back again, and the mailbox opens.
- Sending and receiving both work for the account you made in the console.
- The version in Settings › About links to the exact source the build came from.
A sign-in that returns to the webmail with an error is nearly always the
redirect mismatch above. Compare the server's registered client with
PUBLIC_URL, character for character.
Next
Everything is installed. From here:
- Where each service goes — what to move off this machine, and why.
- Security — what is exposed and what is not.
- Getting started — using the webmail itself.
Undoing it
docker rm -f inbuxa-webmail
sudo systemctl disable --now inbuxa-webmail
Then delete the service file, the checkout and the reverse proxy's site.
Sessions die with it and everyone signs in again; nothing else is lost, because the webmail keeps nothing of its own. Settings, mail and calendars all live on the server.