2. The console¶
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
adminpassword 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:
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:
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.
dist/ is then static files for any web server. Point the build at the
mail server either with VITE_API_BASE_URL at build time, or by setting
the tag in index.html when you deploy it:
For a development server against a running mail server:
If you use that, the server's INBUXA_ADMIN_URL is
http://localhost:5173.
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 the console on your workstation and reach 8080 over SSH:
ssh -N -L 8080:localhost:8080 [email protected] &
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. 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, with
API_BASE_URL=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¶
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:
- Server Identity: the server's hostname, the default email domain, and whether to get a TLS certificate automatically and generate email signing (DKIM) keys.
- Storage: where mail, attachments and files, the search index, and the cache go. The defaults keep everything in the built-in store.
- Account Directory: whether people sign in with accounts kept in inbuxa itself, or against an existing directory. See Directories and SCIM.
- 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. - 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.
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.
With the default log files, docker logs 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:
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.