Skip to content

3. The webmail

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.

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.

git clone https://git.coffeylabs.org/inbuxa/inbuxa-webmail.git
cd inbuxa-webmail
cp .env.example .env
# edit: MAIL_SERVER_URL, APP_SECRET, OAUTH_CLIENT_SECRET, PUBLIC_URL
docker compose up --build -d

It comes up on http://localhost:8080.

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:

Undoing it

docker rm -f inbuxa-webmail

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.