Simple Install Guide

[mackenziebowes]

How to Self-Host Stalwart Mail on a VPS

I installed Stalwart to a VPS this morning, wrote a guide about some of the stuff that was less than clear in installing.
Won't work for everyone or every config, but I think it's a decent guide for getting up and running fast.

1. Get Resources

Get a domain name and a VPS instance, Linode 2 GB is fine. Not affiliated with Linode, just what I used.
Launch the linode with Ubuntu 24.04 LTS, selecting your nearest datacenter. Set a root password.

2. Connect

After the linode provisions, connect via terminal with ssh <ip address> and enter the root password.
Leave this terminal window open until step 8.

3. Install Stalwart

Use curl --proto '=https' --tlsv1.2 -sSf https://get.stalw.art/install.sh -o install.sh inside your ssh tunnel to download the stalwart installer.
Use sudo sh install.sh /opt/stalwart-mail for the default install location.

Note:

The stalwart installer provides an admin account and autogenerated password - keep track of this information for step 5!

4. Lock Admin

Use sudo nano /opt/stalwart-mail/etc/config.toml to open the stalwart config, edit:

[admin]
enabled = true
bind = "127.0.0.1:8080"

then
sudo systemctl restart stalwart-mail sudo systemctl restart stalwart to lock down your admin panel from outside connections.
Leave this terminal window open until you're done with installing Stalwart.

5. Tunnel to Admin

In a new terminal, use
ssh -L <port_of_choice>:localhost:8080 root@<server_ip> - you can use 8080 too, if you want, just make sure it's a port not in use.
This tunnel will ask for the root password again, provide it and while that terminal window is open, you can open a browser and go to localhost:<port_of_choice> to access the admin panel!
The default username is admin and the password is the one generated in step 3.

Note:

Stalwart uses a username system - it's not [email protected], just admin

6. Domain Config

Go to your domain registrar (e.g., Namecheap) and add the following DNS records:

Basic Records

Type	Host	Value	Notes
A	mail	Your server IP	Points mail.<your_domain_name>.<your_tld> to your VPS
MX	@	mail.<your_domain_name>.<your_tld>.	Main mail delivery
TXT	@	"v=spf1 mx -all"	SPF – allow mail from your server only

Your domain name is the part of your domain before the period, the TLD (top-level-domain) is the part after.

DKIM

DKIM is an email security feature that's needed to interact with modern mail providers.
You get your DKIM info from:

1. "manage/directory/domains"
2. Add domain if none yet exists
3. After adding domain, click on "..." on right side of entry
4. Select "View DNS Records"
   That page will have a route like /manage/dns/<your_domain>/view

   Type	Host	Value (starts with…)
   TXT	202505e._domainkey	"v=DKIM1; k=ed25519; p=..."
   TXT	202505r._domainkey	"v=DKIM1; k=rsa; p=..."
   Paste them exactly as Stalwart provides.

DMARC & TLS-RPT

Add these too:

Type	Host	Value
TXT	_dmarc	"v=DMARC1; p=reject; rua=mailto:postmaster@<your_domain>"
TXT	_smtp._tls	"v=TLSRPTv1; rua=mailto:postmaster@<your_domain>"

Note:

Be sure to update <your_domain> to your domain

7. Fix TLS Certificate Issues

Stalwart doesn't auto-deploy a proper TLS certificate, you gotta do that yourself.
Go to /settings/acme and create an acme provider.

What is Acme?

Nerd. It's a certificate protocol. Automatic Certificate Management Environment. Gives you free and automatically rotating TLS certificates so everyone knows your emailer is safe.

There are three required, non-default fields you have to configure:

Directory Id

This is just an internal name for your stalwart install, put whatever here.

Contact Email

This is where ACME sends alerts, use whatever other email you check normally.

Subject Names

This is where you put the domain that's being certified by the ACME system, just mail.<your_domain>.<your_tld> is good!

This should just work if you set your DNS stuff up correctly and you gave your registrar time to distribute your settings.

8. Restart Stalwart

sudo systemctl restart stalwart-mail in your first terminal that's still open from step 2 for a final restart.

9. Create Users

Go to manage/directory/accounts on your Stalwart admin panel and add your new accounts.

Note: Usernames AND addresses

Most modern mail providers use email addresses as usernames - Stalwart doesn't, pay attention to when later integrations ask for a username vs an email address.

Note: Authentication

Stalwart is built for big boys, so there's a lot of configuration options.
If you're like me, you just need to use the internal auth server, which is prebuilt, and you just need to secure your accounts with a password, so:
Click over to the Authentication tab and write in a password for this account.

Then use a standard mail client (Thunderbird, Apple Mail, etc.):

IMAP (Incoming)

• Host: mail.yourdomain.com
• Port: 993
• SSL/TLS: Yes
• Username: the username you set for the account
• Password: the password you set

SMTP (Outgoing)

• Host: mail.yourdomain.com
• Port: 587
• STARTTLS: Yes (You can also use SSL/TLS)
• Username: the username you set
• Password: the username you set

Send test mail between your users and confirm deliverability via https://mxtoolbox.com.

[mdecimus]

Hi,

Thanks for the contribution!

We've recently updated the get started guide for Stalwart. If you have any suggestions to make the installation process clearer please let me know!

[Sedation6612]

@mdecimus Why don't y'all include an official docker compose into the installation guide?

[mdecimus]

Stalwart supports multiple backend combinations so it will be tricky to keep docker composes for all possibilities. When running Stalwart using an embedded database (RocksDB or SQLite), there is not much to compose as everything runs from a single container. But I guess a basic compose example could be included.

[mackenziebowes]

@Sedation6612 afaict docker/nix flakes wouldn't fix having to find the configs to put in the domain and setting up SMTP. Installing stalwart was stupidly easy for how great it works, just wrote this out for some gotchas

[9to1url]

I recently built the Docker image and deployed to k8s, super easy and super clean :-)
I recommend k8s deployment.

[pepa65]

Suggested edits:

• In 2. Connect: "connect via terminal with ssh -l root <ip address>"
• In 3. Install Stalwart: "Use sudo sh install.sh /opt/stalwart for the default install location."
• In 4. Lock Admin: "Use sudo nano /opt/stalwart/etc/config.toml"
• In 8. Restart Stalwart: "sudo systemctl restart stalwart"