Home

This wiki explains how to deploy, configure and test ALPS, and how it is built. It is for people who run ALPS for their users and for people who work on its code. The reference documents live in the repository's docs/ directory, and the pages here link to them for the full detail.

What ALPS is

ALPS is a webmail: a Go backend that serves a Lit frontend from the same binary, with plugins for contacts, calendars, mail filters, OpenPGP and password change. It keeps no mail and no database of its own. It reads mail from an IMAP server (or a local Maildir), keeps each account's settings on that server as IMAP METADATA, and sends through an SMTP submission server, signing in to each with the user's own username and password.

What the mail server must provide

• IMAP4rev1 or IMAP4rev2, with the LOGIN command accepted on the connection ALPS opens. ALPS does not use SASL AUTHENTICATE or OAuth.
• METADATA or METADATA-SERVER (RFC 5464), for anything to be kept. Without it, settings, identities, linked accounts, security keys, the OpenPGP keyring and the CalDAV and CardDAV connections users set up last for one IMAP connection only, so use such a server only to try ALPS out.
• UIDPLUS is strongly recommended and MOVE recommended. Other capabilities, such as THREAD, SORT, QUOTA, ACL and PREVIEW, are used when the server lists them, and IDLE, NOTIFY and CONDSTORE only when you turn them on.
• A Sent folder and a Drafts folder on the IMAP server.
• An SMTP submission server that takes AUTH PLAIN with the user's credentials. ALPS does not start without [smtp] server, even with the Maildir provider.

Mail Server Requirements has the full list, what ALPS does without each capability, and how to check a server.

Try it in five minutes

You need Go 1.25.0 or later on Linux, macOS, a BSD or Windows, and a mailbox whose provider lets you sign in to IMAP and SMTP with a password. The built interface is in the repository, so Node.js is not needed.

1. Get the code:

   git clone https://github.com/migadu/alps.git
   cd alps

2. Create config.toml in the clone, with your provider's servers in place of the example names:

   [server]
   addr = "127.0.0.1:1323"
   
   [provider.imap]
   server = "imaps://imap.example.com:993"
   
   [smtp]
   server = "smtps://smtp.example.com:465"
   
   [plugin.base]
   enabled = true
   
   [plugin.gpg]
   enabled = true

3. Start ALPS:

   go run ./cmd/alps -config config.toml

4. Open http://localhost:1323 and sign in with the username and password your provider gives for IMAP.

Local Try-Out explains each line of that file, shows how to check that settings are kept and mail goes out, and lists the fixes for the usual startup and sign-in errors.

Architecture

• Architecture Overview: the binary, the session and its IMAP connections, and one request from the browser to IMAP and SMTP.
• Mail Server Requirements: what the IMAP and SMTP servers must offer, what ALPS uses when they offer more, and how to check a server.
• Sessions and Sign-in: how users sign in, how long they stay signed in, login_key, restarts and linked accounts.
• Storage in IMAP METADATA: what ALPS keeps on the mail server instead of a database, and what that means for backups and migrations.
• Mail Providers: the imap, maildir and multi providers, and how multi routes each login.
• Plugins: the six built-in plugins, how the configuration decides which load, and how to write one.
• Features: new-mail push, change numbers, previews, search, attachments, languages, BIMI logos and branding.
• Security Features: two-factor sign-in, recovery codes, linked-account trust, rate limits, the origin check and cookies.
• Clustering: several nodes behind a load balancer, what they share and why sessions need affinity.

Tests

• Testing Overview: the three test tiers and how to run all of them before a pull request.
• Go Tests: the backend tests, their test servers and mocks, and how to run one package or one test.
• Frontend Unit Tests: the Vitest suite under jsdom, its helpers and how to write a component test.
• Browser Tests: the Playwright suite against a full mail stack, its variables, and how to read a failed run.

Before you send a change, also read the README's Contributing section and its AI Assistance Policy.

Configuration

• Configuration Overview: the file as a whole, a minimal working file, how defaults, unknown keys and startup checks behave, and the environment variables.
• Server: [server], with listening, proxies and origins, login_key, session limits, timeouts, attachments, push and CONDSTORE.
• Providers and SMTP: [provider] and its imap, maildir and multi sections, and [smtp].
• TLS: certificate files, Let's Encrypt, the staging directory and certificates shared through S3.
• Cluster: every [cluster] key, the secret key and the settings all nodes must share.
• Rate Limiting and WebAuthn: [server.rate_limit] and [webauthn].
• Logging and Cache: [logging], [cache], [server] debug and the log lines to look for.
• Plugins: the [plugin.<name>] sections, which plugins load, server URLs and the password plugin's options.
• Branding: [branding], the default theme and a custom logo.

Common Setups

• Local Try-Out: ALPS on your own computer against a mailbox you already have, and the frontend dev server.
• Behind a Reverse Proxy: ALPS on plain HTTP behind nginx or Caddy, with complete proxy configurations.
• Let's Encrypt Standalone: ALPS serving HTTPS itself with a Let's Encrypt certificate and no proxy.
• Cluster: two nodes behind a load balancer, optionally sharing Let's Encrypt certificates through S3.
• Many Domains: one ALPS for several domains on different mail servers, with the multi provider.
• Dovecot and Postfix: ALPS on the same host as Dovecot (with METADATA and ManageSieve) and Postfix.
• Maildir: ALPS reading Maildirs directly on the mail host, with no IMAP server.
• Password Change: Settings > Password through an HTTP endpoint or a local program.
• Running in Production: the service files, logs, signals, upgrades, backups and a production checklist.

None of these setups sets up a CalDAV or CardDAV server. Calendar, Tasks and Contacts appear for a user once there is one to use. You can name a default server in [plugin.caldav] and [plugin.carddav], or per domain as Many Domains shows, and users then reach it with their mail username and password. Users can also enter a server of their own, or separate credentials, under Settings > Calendar and Settings > Contacts. See Plugin Configuration and docs/CDAV.md. The OpenPGP plugin also finds other people's public keys through CardDAV, so for a user with no CardDAV server an encrypted message can go only to themselves (Plugins).