ihasmail-oneshot: From a Bare Server to Mail and Webmail in One Command

Almost everything I have written about ihasmail has quietly started from the same place: you already have a Stalwart mail server. Point ihasmail at it, start one container, sign in. That really is all it takes, if you are already there.

If you are not already there, though, and you like the look of it and the idea of running your own mail, the first step turns out to be "install and configure a mail server", which is not one step at all.

So there is now a tool for that. It is called ihasmail-oneshot, and it does exactly what the name promises:

ihasmail-oneshot deploy --domain example.com --user alice

A minute or two later you have a mail server for your domain, webmail in front of it, a mailbox for Alice, and a short list of things to do next.

Why this needed to exist

Installing Stalwart is easy. Installing ihasmail is easy. Getting the two of them working together, safely, on a server on the internet, is where the evening goes.

None of it is hard on its own. It is that there are a dozen small decisions, each one easy to get slightly wrong, and most of them don't show their mistakes until later:

• The first-time setup expects a person. A brand new Stalwart starts in a setup mode that wants someone to walk through a wizard in the browser, and hands out a temporary admin password to do it.
• Both services want the same doors. Your webmail needs a security certificate for HTTPS. So does the mail server, for the apps on your phone and laptop. The usual way of getting certificates has both of them fighting over the same port, and two things fighting over one port fail in confusing, now-and-then ways.
• Security features can trip over each other. Stalwart is good at spotting bots and blocking them. Put anything in front of it — like the part that handles HTTPS — and every visitor appears to come from that one thing. While I was building this, a short burst of fake "bot" requests in my test setup got the front end blocked, and with it every calendar sync and autoconfig lookup, for everyone. Nothing looked broken. It just stopped working.
• Mail doesn't flow until DNS is right, and the list of records a mail server needs is long, oddly named and unforgiving of typos.

ihasmail-oneshot is the answer to each of those, worked out once against a real Stalwart and written down as a program, so nobody has to rediscover them one support thread at a time.

What it actually does

You run one command on a Linux machine with Docker. It:

1. Checks the machine first — that Docker is working, that the ports it needs are free, and that you're not about to overwrite something — and tells you every problem at once rather than one per attempt.
2. Shows you the plan and asks before changing anything.
3. Sets up Stalwart for you, doing what the setup wizard would have walked you through, and creates your administrator account. The temporary setup password is gone before it finishes.
4. Starts ihasmail and connects it to Stalwart over a private network on the same machine, so the two talk without ever going out onto the internet.
5. Gets certificates for both the webmail and the mail server, arranged so they share the doors instead of fighting over them.
6. Fixes the blocking problem before it can happen, so a bot gets itself blocked and nobody else.
7. Creates the mailboxes you asked for, with generated passwords.
8. Proves it all works by actually signing in through the webmail before it says "done".
9. Hands you your DNS records in a file, ready to paste into your DNS provider.

When it finishes, what's left on your server is an ordinary Docker Compose project. It isn't tied to the tool in any way. You can look at every file it wrote, and run it with the same commands you would use for anything else.

Trying it without a domain

If you just want to see ihasmail in action against a real Stalwart, there is a local mode that needs no domain, no open ports and no certificates:

ihasmail-oneshot deploy --local --user alice

It ends with a summary, trimmed a little here to fit:

==> done
    webmail      http://127.0.0.1:8080
    Stalwart     http://127.0.0.1:8081/admin
    sign in as   [email protected]
    mailbox      [email protected]

The passwords are in a credentials.txt file next to everything else it wrote, readable only by you.

Open the webmail address, sign in as Alice, and look around. Nothing outside your own machine can reach it. When you're done, one more command removes the lot:

ihasmail-oneshot destroy --dir ihasmail-example-test

Setting up a real mail server

For the real thing, the steps are short, and the README walks through each one in detail:

1. Point two names at your server — mail.example.com and webmail.example.com — at your DNS provider.
2. Open the ports in any firewall in front of it.
3. Run the deploy command with your domain, and add a --user for each person who needs a mailbox.
4. Publish the DNS records it gives you. This is the step that decides whether your mail arrives, so don't skip any of them.
5. Sign in at your new webmail, and change the generated passwords.

Two things are genuinely outside what any tool can do for you, and it will remind you of both at the end. Many hosting providers block outgoing mail on port 25 until you ask them to open it. And your server's address needs reverse DNS set to your mail server's name, which is done at your hosting provider, not in your own DNS. Get those two sorted and your mail will actually reach people's inboxes.

What it won't do

It's worth being clear about the edges, because they are deliberate:

• It only builds fresh servers. It won't touch an existing Stalwart, and it refuses to write over a deployment that is already there. That is on purpose: a setup tool that "helpfully" reconfigures a server holding someone's mail is a tool nobody should trust.
• One domain to start. You can add more afterwards in Stalwart or in ihasmail's Administration menu.
• One machine. It's for getting a single server up quickly, not for clusters.
• It's new. This is an early release. Before it went out, I ran a full deployment end to end against a stand-in for Let's Encrypt: real certificates, real ports, real sign-ins, and the blocking behaviour tested both ways. What it hasn't done yet is years of running other people's mail. Bug reports are very welcome.

Already running an older Stalwart?

If you already have a Stalwart server but it's on version 0.15.5, you're in the other common starting point. ihasmail needs Stalwart 0.16 or newer, and that upgrade is its own adventure.

That's what stalwart-migrator is for. It upgrades your existing server in place, picks up where it left off if it gets interrupted, and checks the server still works afterwards. It moved my own server across with eight seconds of downtime. Take a snapshot first, though: it can't undo an upgrade.

Between the two tools, both usual starting points are covered: nothing yet, or an older Stalwart. They sit side by side on ihasmail.org for exactly that reason.

Try it

• Download: the latest release, a single program for Linux on amd64 and arm64
• Source and full guide: github.com/Coffey-Labs/ihasmail-oneshot
• The webmail it sets up: ihasmail.org, with the live demo and the documentation
• For older Stalwart servers: stalwart-migrator
• Everything else I build: coffeylabs.org/projects

It's free, open source and AGPL-3.0, like ihasmail itself. If it gets you from a bare server to your own mail in an evening instead of a weekend, it has done its job. And if a different setup suits your server better, run that.