jcoffey-dev
3fd909cba3
GitHub took the organization's repos and GHCR offline on 2026-09-20. Repo, release, raw-file and clone links now go to Gitea at git.coffeylabs.org, container images to registry.coffeylabs.org, and GitLab-style /-/blob paths to Gitea's /src/branch form. Go module paths are identifiers and stay as they are; links to GitHub issues and pull requests are left as history.
4.6 KiB
ihasmail-oneshot
One command that turns a Linux Docker host into a working mail server with webmail. It deploys a fresh Stalwart mail server and a fresh ihasmail webmail, links them together, gets them certificates, and hands you the administrator password and the DNS records to publish.
ihasmail-oneshot deploy --domain example.com --user alice
Documentation
| 📘 Step-by-step guide | Start here. On docs.ihasmail.org: DNS, ports, deploying, publishing records, signing in, upgrading and backups |
| 📋 Reference | Requirements, every command and flag, the deployment directory, upgrading, backing up, removing |
| ⚙️ How it works | Why it exists, the deploy sequence, Stalwart setup without its wizard, shared certificates, IP bans behind a proxy |
| 🔒 Security model | What is exposed, where secrets live, the trust decisions it makes |
| 🧰 Troubleshooting | Problems by message or symptom, and known limits |
| 🧪 Contributing | Building, the unit and end-to-end tests, the code layout, releases |
What you get
- A mail server for
example.com, with webmail athttps://webmail.example.comand Stalwart's admin UI athttps://mail.example.com/admin. - A mailbox for each
--user, and an administrator, with generated passwords incredentials.txt. - Certificates for the webmail and for Stalwart's mail ports.
dns-records.zone: every DNS record to publish, DKIM keys included.- An ordinary
docker composeproject, managed with the usual commands and not tied to this tool. ihasmail runs read-only with no volume; everything durable is in Stalwart's volume.
Requirements
- Linux (amd64 or arm64) with Docker Engine and the compose plugin.
- For a mail host: a domain whose DNS you control, a static public IP, ports 25, 80, 443, 465, 993, 995 and 4190 open, outbound port 25 allowed by your provider, and reverse DNS for the host's address naming the mail host.
The full list is in docs/reference.md.
Install
ARCH=amd64 # or arm64
curl -fsSLO https://git.coffeylabs.org/coffey-labs/ihasmail-oneshot/releases/download/latest/ihasmail-oneshot-linux-$ARCH.tar.gz
curl -fsSLO https://git.coffeylabs.org/coffey-labs/ihasmail-oneshot/releases/download/latest/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
tar -xzf ihasmail-oneshot-linux-$ARCH.tar.gz
sudo install -m 0755 ihasmail-oneshot /usr/local/bin/
Or build from source with Go 1.26.8 or newer:
go build -o ihasmail-oneshot ./cmd/ihasmail-oneshot.
Use
Try ihasmail against a real Stalwart on your own machine, with no domain and nothing reachable from outside:
ihasmail-oneshot deploy --local --user alice
ihasmail-oneshot destroy --dir ihasmail-example-test # when you're done
Deploy a real mail host, after pointing mail.example.com and
webmail.example.com at it:
ihasmail-oneshot deploy --domain example.com --email [email protected] --user alice
It checks the host, shows the plan with the exact ihasmail release it will use,
and asks before changing anything. Then publish dns-records.zone, and mail
flows.
Versions
Releases are tagged by date (v2026.9.15). Each pins the Stalwart and Caddy
versions it was tested with. ihasmail is the newest release at deploy time,
written into compose.yaml by its dated tag, and checked by an end-to-end test
every Monday. Nothing upgrades by itself afterwards. Details in
CONTRIBUTING.md.
Security
To report a vulnerability, see SECURITY.md. Please don't open a public issue.
License
AGPL-3.0-or-later, the same as ihasmail. See LICENSE.
Running the tool to deploy your own mail host places no obligations on you. The license matters if you modify the tool and offer it to others, including as a hosted service that deploys on their behalf: then your modified source must be available to them.