- Go 69.2%
- TypeScript 27.4%
- Go Template 2.5%
- Dockerfile 0.6%
- CSS 0.2%
- Other 0.1%
|
All checks were successful
ci / cli-build (amd64, linux) (push) Successful in 58s
ci / cli-build (amd64, windows) (push) Successful in 1m3s
ci / cli-build (arm64, linux) (push) Successful in 1m3s
ci / cli-build (arm64, windows) (push) Successful in 1m3s
ci / build (push) Successful in 2m46s
ci / frontend-docker (push) Successful in 0s
ci / build-2 (push) Successful in 2m44s
ci / ingester-docker (push) Successful in 0s
ci / build-1 (push) Successful in 3m30s
ci / api-docker (push) Successful in 0s
ci / build-3 (push) Successful in 37s
ci / chart (push) Successful in 0s
|
||
|---|---|---|
| .forgejo/workflows | ||
| api | ||
| cli | ||
| frontend | ||
| helm | ||
| ingester | ||
| .gitignore | ||
| docker-compose.yml | ||
| README.md | ||
| renovate.json | ||
Mail Archiver
A self-hosted mail archiving system with three components:
- api/ — Go/gin REST API. Central component: auth, search, storage configuration, mail retrieval. Stateless, safe to run as multiple Kubernetes replicas.
- ingester/ — Go service that gets mail into the archive: an SMTP listener mail servers can relay/push to, and an IMAP puller that polls mailboxes. Both forward to the API over HTTP. Stateless; configuration is fetched from the API so it can be reconfigured entirely from the web UI.
- frontend/ — React/TypeScript/Tailwind SPA: search mail, view it
(sanitized HTML, sandboxed iframe), download as
.eml, and administer users, mailboxes, storage, retention and ingester settings.
Architecture notes
Multi-replica API. No in-memory session state — auth is a stateless
JWT. Background jobs (retention sweep, search reindex retry) are gated by
a simple database row lease (worker/scheduler.go) so exactly one replica
runs them at a time while all replicas keep serving HTTP traffic.
Storage is the source of truth, the database is not. Every archived
mail is written to the storage backend (file or S3-compatible, via
minio-go) as two objects: the raw
.eml (byte-identical to what arrived) and a .json metadata sidecar
(mailbox, from/to/subject/date/message-id, attachment list). If the
database is lost entirely, POST /api/admin/reindex walks the storage
backend and rebuilds the database (and search index) purely from these
sidecars — see archive/reindex.go. Only derived/administrative state
(users, storage/ingester settings, search index) is allowed to be lost;
none of it is required to recover the archived mail itself.
Optional encryption at rest: set STORAGE_ENCRYPTION_KEY on the API and
every new .eml/.json object is AES-256-GCM encrypted before it's
written. The key lives in an environment variable, deliberately not
the database, so an encrypted archive stays recoverable even after a full
database loss.
Search. Meilisearch indexes mail
metadata + body text for the search UI. It's a derived index, not a
source of truth — worker/scheduler.go retries indexing for anything that
fails, and reindex rebuilds it from scratch if needed.
Auth & scoping. Three roles:
admin— full access, including settings and user management.auditor— read-only access to all archived mail, no config changes.receiver— scoped to only the mailbox(es) assigned to them.
HTML mail safety. Mail HTML is sanitized server-side
(bluemonday, scripts, event
handlers, iframes, forms stripped) and then rendered in the frontend
inside a fully sandboxed <iframe sandbox=""> as defense in depth.
Running locally
cp .env.example .env # if you add one; otherwise set env vars directly
docker compose up --build
Then create an ingester API key from the web UI (Settings → Ingester API
keys) and set INGESTER_API_KEY before starting the ingester, or restart
the ingester service after creating one.
Key environment variables
api
| Variable | Purpose |
|---|---|
JWT_SECRET |
required; signs auth tokens |
DB_DRIVER |
sqlite (default), postgres, mysql, mssql |
MEILISEARCH_HOST, MEILISEARCH_API_KEY |
search backend |
STORAGE_FILE_PATH |
file backend base path (ignored if backend is s3; configurable via UI too) |
STORAGE_ENCRYPTION_KEY |
optional; enables at-rest encryption of archived mail |
INITIAL_ADMIN_EMAIL / INITIAL_ADMIN_PASSWORD |
seeded on first boot only |
ENABLE_SCHEDULER |
set to false on replicas that shouldn't run background jobs (optional — the lease makes this safe to leave on everywhere) |
EXECUTE_MIGRATIONS |
default true; set to false on the long-running api process when something else (e.g. the Helm chart's db-migrate Job) applies schema migrations instead |
MIGRATE_ONLY |
default false; set to true to run migrations/seeding and exit immediately instead of starting the server — used by the Helm chart's db-migrate Job |
ingester
| Variable | Purpose |
|---|---|
API_BASE_URL |
e.g. http://api:8080 |
API_KEY |
created via Settings → Ingester API keys in the web UI |
CONFIG_REFRESH_SECONDS |
how often to re-fetch SMTP/IMAP config from the API |
Kubernetes
A Helm chart is in helm/ (based on the filamentmanagement chart's
structure/conventions). It bundles meilisearch as an optional subchart
dependency (can be pointed at an external instance instead via
meilisearch.enabled=false) and expects an external MariaDB/MySQL instance
(mariadb.external.host/mariadb.auth.*), and auto-generates JWT/admin/
ingest secrets on first install if not supplied.
cd helm
helm dependency update
helm install mail-archiver . -n mail-archiver --create-namespace
Key values worth setting before a real deployment:
storage.backend(fileors3) andstorage.s3.*/storage.file.persistence.*storage.encryptionKeyfor at-rest encryptionadmin.email/admin.password(or leave blank to auto-generate — seehelm get notesfor how to retrieve it)replicaCountApi+autoscaling.enabledfor the api tier (the component designed to run as N replicas)ingress.enabledandingress.hosts
Note: the frontend image's nginx config proxies /api/ to a fixed
in-cluster hostname (api), matching docker-compose.yml — the chart
names the api Service accordingly, which means only one release of this
chart should run per namespace.
Schema migrations run via a dedicated <release>-db-migrate Job (the api
image with MIGRATE_ONLY=true), not on every api pod startup — the api
Deployment sets EXECUTE_MIGRATIONS=false. The Job is a Helm hook
(post-install,pre-upgrade) so it runs once per install/upgrade: after the
chart's Secrets exist on a fresh install, and before the api Deployment's
pods roll onto a new image on upgrade.
The chart deploys one ingester, authenticated via a bootstrap key
(INGEST_BOOTSTRAP_API_KEY) that works only while exactly one Ingester
exists in the database (the api auto-seeds one named "Default" on first
boot). If you create additional ingesters from the web UI (Settings >
Ingesters), the bootstrap key stops working — mint a real API key for the
chart-deployed ingester from the UI instead and point ingest.existingSecret
at a Secret containing it.
Run helm template . | kubectl apply --dry-run=client -f - to validate
against your cluster's API schema before installing.