From 1b5da60397710050e7ecc0f14b2f4cde09b2e2f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jeffrey=20Bo=CC=88hm?= Date: Tue, 3 Feb 2026 20:29:46 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20applied=20the=20Di=C3=A1taxis=20approac?= =?UTF-8?q?h=20to=20the=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .cursor/rules/learned-memories.mdc | 29 -- .env.dist | 5 +- .mkdocs.yaml | 69 +++-- AGENTS.md | 61 ++++ docs/README.md | 91 +++--- docs/administration/dashboard.md | 4 +- docs/administration/dkim-signing.md | 30 +- docs/administration/dns-validation-wizard.md | 12 +- docs/administration/ios-macos-profile.md | 7 +- docs/administration/login.md | 14 +- docs/administration/manage-aliases.md | 94 +----- docs/administration/manage-domains.md | 40 +-- docs/administration/manage-fetchmail.md | 84 +----- docs/administration/manage-users.md | 109 +------ docs/administration/user-roles.md | 41 +-- docs/configuration/dns-configuration.md | 284 +----------------- docs/configuration/environment-variables.md | 120 +------- docs/configuration/external-mysql.md | 135 +-------- docs/configuration/local-address-extension.md | 52 +--- docs/configuration/mailserver-admin.md | 93 +----- docs/configuration/php-sessions.md | 80 +---- docs/configuration/relayhost.md | 144 +-------- docs/configuration/reverse-proxy.md | 175 +---------- docs/configuration/roundcube.md | 92 +----- docs/configuration/tls.md | 123 +------- docs/development/architecture.md | 68 +---- docs/explanation/architecture.md | 29 ++ docs/explanation/dns-and-email.md | 23 ++ docs/explanation/observability.md | 29 ++ docs/how-to/configure-dkim.md | 21 ++ docs/how-to/configure-dns.md | 34 +++ docs/how-to/configure-external-mysql.md | 54 ++++ docs/how-to/configure-oauth2.md | 53 ++++ docs/how-to/configure-php-sessions.md | 34 +++ docs/how-to/configure-relayhost.md | 84 ++++++ docs/how-to/configure-reverse-proxy.md | 59 ++++ docs/how-to/configure-roundcube-plugins.md | 43 +++ docs/how-to/configure-tls.md | 64 ++++ docs/how-to/install-docker.md | 61 ++++ docs/how-to/install-kubernetes.md | 70 +++++ docs/how-to/ios-macos-profile.md | 10 + docs/how-to/manage-aliases.md | 40 +++ docs/how-to/manage-domains.md | 29 ++ docs/how-to/manage-fetchmail.md | 45 +++ docs/how-to/manage-users.md | 50 +++ docs/how-to/upgrade.md | 11 + docs/how-to/validate-dns.md | 20 ++ docs/installation.md | 214 +------------ docs/observability/intro.md | 44 +-- docs/reference/dns-records.md | 145 +++++++++ docs/reference/environment-variables.md | 95 ++++++ docs/reference/local-address-extension.md | 33 ++ docs/reference/mailserver-admin-config.md | 42 +++ docs/reference/ports.md | 15 + docs/reference/service-architecture.md | 37 +++ docs/reference/upgrade-changelog.md | 46 +++ docs/reference/user-roles.md | 22 ++ docs/tutorials/getting-started.md | 86 ++++++ docs/upgrade.md | 61 +--- 59 files changed, 1579 insertions(+), 2180 deletions(-) delete mode 100644 .cursor/rules/learned-memories.mdc create mode 100644 AGENTS.md create mode 100644 docs/explanation/architecture.md create mode 100644 docs/explanation/dns-and-email.md create mode 100644 docs/explanation/observability.md create mode 100644 docs/how-to/configure-dkim.md create mode 100644 docs/how-to/configure-dns.md create mode 100644 docs/how-to/configure-external-mysql.md create mode 100644 docs/how-to/configure-oauth2.md create mode 100644 docs/how-to/configure-php-sessions.md create mode 100644 docs/how-to/configure-relayhost.md create mode 100644 docs/how-to/configure-reverse-proxy.md create mode 100644 docs/how-to/configure-roundcube-plugins.md create mode 100644 docs/how-to/configure-tls.md create mode 100644 docs/how-to/install-docker.md create mode 100644 docs/how-to/install-kubernetes.md create mode 100644 docs/how-to/ios-macos-profile.md create mode 100644 docs/how-to/manage-aliases.md create mode 100644 docs/how-to/manage-domains.md create mode 100644 docs/how-to/manage-fetchmail.md create mode 100644 docs/how-to/manage-users.md create mode 100644 docs/how-to/upgrade.md create mode 100644 docs/how-to/validate-dns.md create mode 100644 docs/reference/dns-records.md create mode 100644 docs/reference/environment-variables.md create mode 100644 docs/reference/local-address-extension.md create mode 100644 docs/reference/mailserver-admin-config.md create mode 100644 docs/reference/ports.md create mode 100644 docs/reference/service-architecture.md create mode 100644 docs/reference/upgrade-changelog.md create mode 100644 docs/reference/user-roles.md create mode 100644 docs/tutorials/getting-started.md diff --git a/.cursor/rules/learned-memories.mdc b/.cursor/rules/learned-memories.mdc deleted file mode 100644 index 283f103d..00000000 --- a/.cursor/rules/learned-memories.mdc +++ /dev/null @@ -1,29 +0,0 @@ ---- -alwaysApply: true ---- - -# Project Memory - -This file stores project-specific knowledge, conventions, and user preferences learned by the AI assistant. - -## User Preferences - -- **Documentation Writing Style**: Use technical documentation language instead of marketing speak. Avoid subjective language like "powerful", "particularly useful", "sophisticated". Use direct, factual statements about functionality. Include technical references (like RFC standards) and concrete examples. Focus on implementation details rather than promotional content. Make language concise and direct, suitable for technical documentation. - -## Technical Decisions - -- **Documentation Format**: Markdown files in /docs should contain technical feature descriptions with implementation details, configuration options, and concrete examples rather than marketing language. - -## Project Conventions - -- **Documentation Standards**: Write documentation for complex software with technical precision, avoiding promotional language and focusing on functional descriptions. - -## Project Structure - -- **Architecture**: The docker-mailserver consists of multiple Docker containers or Kubernetes pods that work together to provide a mail service. -- **Container Images**: Each container image is built in `target/`. Each subdirectory in `target/` represents a separate service component (e.g., `target/mta/`, `target/mda/`, `target/filter/`, `target/web/`, `target/db/`, `target/unbound/`, `target/ssl/`). -- **Deployment Manifests**: The project supports both Docker Compose and Kubernetes deployments: - - Docker Compose manifests are located in `deploy/compose/` - - Kubernetes manifests using Kustomize are located in `deploy/kustomize/` -- **Multi-Platform Support**: The same container images can be deployed either as Docker containers (via Compose) or as Kubernetes pods (via Kustomize), with deployment-specific configuration in the respective directories. -- **Deployment Consistency**: When changes are made to deployment manifests in `deploy/compose/` or `deploy/kustomize/`, the same changes must be applied to the corresponding manifests in the other deployment method to maintain feature parity between Docker Compose and Kubernetes deployments. diff --git a/.env.dist b/.env.dist index b7ab4b9e..adb20173 100644 --- a/.env.dist +++ b/.env.dist @@ -34,15 +34,16 @@ DOVEADM_API_KEY=changeme2 WAITSTART_TIMEOUT=2m # Configure local address extension -# @see docs/configuration/local-address-extension.md +# Check the documentation for more information. RECIPIENT_DELIMITER=- # Interval in seconds for fetchmail to check for new mails FETCHMAIL_INTERVAL=300 -## @see docs/REVERSE_PROXY.md # Expects the PROXY protocol on imap(s) and pop3(s) ports +# Check the documentation for more information. MDA_UPSTREAM_PROXY=false # Expects the PROXY protocol on smtp and submission ports +# Check the documentation for more information. MTA_UPSTREAM_PROXY=false diff --git a/.mkdocs.yaml b/.mkdocs.yaml index b94e0efb..774630dd 100644 --- a/.mkdocs.yaml +++ b/.mkdocs.yaml @@ -15,40 +15,49 @@ exclude_docs: | requirements.txt nav: - Welcome: README.md - - Quick Start: - - installation.md - - upgrade.md - - Configuration: - - configuration/environment-variables.md - - "mailserver-admin": configuration/mailserver-admin.md - - configuration/dns-configuration.md - - configuration/external-mysql.md - - configuration/relayhost.md - - configuration/local-address-extension.md - - configuration/php-sessions.md - - configuration/reverse-proxy.md - - configuration/roundcube.md - - configuration/tls.md - - Administration: - - administration/login.md - - administration/dashboard.md - - administration/manage-domains.md - - administration/manage-users.md - - administration/manage-aliases.md - - administration/manage-fetchmail.md - - administration/dkim-signing.md - - administration/dns-validation-wizard.md - - administration/user-roles.md - - administration/ios-macos-profile.md - - Observability: - - observability/intro.md + - Tutorial: + - Getting Started: tutorials/getting-started.md + - How-to guides: + - Install with Docker: how-to/install-docker.md + - Install on Kubernetes: how-to/install-kubernetes.md + - Upgrade: how-to/upgrade.md + - Configure DNS: how-to/configure-dns.md + - Configure DKIM: how-to/configure-dkim.md + - Validate DNS (wizard): how-to/validate-dns.md + - Configure relay host: how-to/configure-relayhost.md + - Configure reverse proxy: how-to/configure-reverse-proxy.md + - Configure TLS certificates: how-to/configure-tls.md + - Configure OAuth2: how-to/configure-oauth2.md + - Configure external MySQL: how-to/configure-external-mysql.md + - Configure Roundcube plugins: how-to/configure-roundcube-plugins.md + - Configure PHP sessions: how-to/configure-php-sessions.md + - Manage domains: how-to/manage-domains.md + - Manage users: how-to/manage-users.md + - Manage aliases: how-to/manage-aliases.md + - Manage fetchmail: how-to/manage-fetchmail.md + - iOS / macOS profile: how-to/ios-macos-profile.md + - Reference: + - Environment variables: reference/environment-variables.md + - Ports: reference/ports.md + - DNS records: reference/dns-records.md + - Service architecture: reference/service-architecture.md + - User roles: reference/user-roles.md + - mailserver-admin config: reference/mailserver-admin-config.md + - Local address extension: reference/local-address-extension.md + - Upgrade changelog: reference/upgrade-changelog.md + - Administration (web UI): + - Login: administration/login.md + - Dashboard: administration/dashboard.md + - Explanation: + - Service architecture: explanation/architecture.md + - DNS and email delivery: explanation/dns-and-email.md + - Observability: explanation/observability.md - Recipes: - Docker: - Traefik Reverse Proxy: https://github.com/jeboehm/docker-mailserver/tree/main/docs/example-configs/compose/traefik-reverse-proxy - Kubernetes: - External Database and HTTPS Ingress: https://github.com/jeboehm/docker-mailserver/tree/main/docs/example-configs/kustomize/external-db-and-https-ingress - Development: - - development/architecture.md - - development/development.md - - "mailserver-admin": development/mailserver-admin.md + - Development guide: development/development.md + - mailserver-admin development: development/mailserver-admin.md - Issues: https://github.com/jeboehm/docker-mailserver/issues diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..43651d31 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,61 @@ +# Agent instructions for docker-mailserver + +This file gives AI agents and contributors the project conventions, documentation framework, and structure they need to work consistently on the codebase and docs. + +## Documentation framework: Diátaxis + +Documentation follows **[Diátaxis](https://diataxis.fr)** (“A systematic approach to technical documentation authoring”). Diátaxis defines four kinds of documentation, each with a different purpose and style: + +| Kind | Purpose | Serves | Style | +| ---------------- | ---------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| **Tutorial** | Learning by doing | Acquisition of skill (study) | Lesson: take the learner through a concrete path; minimal explanation; visible results early; one main path, no branching. | +| **How-to guide** | Accomplish a specific task | Application of skill (work) | Task-oriented: clear steps to reach a goal; for users who already know what they want; no teaching, no long explanations. | +| **Reference** | Look up facts | Application of skill (work) | Technical description: accurate, complete, neutral; structure mirrors the product; consulted, not read. | +| **Explanation** | Understand context and “why” | Acquisition of skill (study) | Background and discussion: design, trade-offs, connections; can include opinion and perspective. | + +**Guidelines:** + +- **Tutorials:** One or few. One main path; show the result early; avoid options and long explanations; link to reference/explanation for depth. +- **How-to guides:** One goal per guide; title = “How to …”; steps only; link to reference for options and formats. +- **Reference:** Describe the machinery (env vars, ports, record formats, APIs); austere; structured like the product; no instruction or opinion. +- **Explanation:** Answer “why?” and “how does it fit together?”; can compare alternatives and give context; do not mix in procedures or reference tables. + +Do not mix the four types in a single doc. When in doubt, use the [Diátaxis compass](https://diataxis.fr/compass/): “Does it inform action or cognition? Does it serve study or work?” + +## Documentation structure (docs/) + +The docs are organised by Diátaxis type: + +- **`tutorials/`** — Learning path (e.g. `getting-started.md`). +- **`how-to/`** — Task guides: install (Docker/Kubernetes), upgrade, configure (DNS, DKIM, TLS, relay, reverse proxy, OAuth2, MySQL, Roundcube, PHP sessions), manage (domains, users, aliases, fetchmail), iOS/macOS profile. +- **`reference/`** — Technical reference: `environment-variables.md`, `ports.md`, `dns-records.md`, `service-architecture.md`, `user-roles.md`, `mailserver-admin-config.md`, `local-address-extension.md`, `upgrade-changelog.md`. +- **`explanation/`** — Context: `architecture.md`, `dns-and-email.md`, `observability.md`. +- **`administration/`** — Short reference for the web UI: `login.md`, `dashboard.md`; other admin topics live as how-to or reference and are linked from here. +- **`configuration/`** — Legacy entry points; these files redirect to the appropriate how-to or reference. +- **`development/`** — Developer how-to: `development.md` (Make, test, lint), `mailserver-admin.md` (mailserver-admin repository setup); `architecture.md` redirects to reference + explanation. +- **`observability/`** — `intro.md` redirects to `explanation/observability.md`. + +MkDocs config is **`.mkdocs.yaml`**; the `nav` there reflects this structure (Tutorial, How-to guides, Reference, Administration, Explanation, Recipes, Development). + +## Documentation writing style + +- Use **technical documentation language**, not marketing. Avoid subjective terms (“powerful”, “particularly useful”, “sophisticated”). +- Use **direct, factual** statements about what the software does. Include **technical references** (e.g. RFCs) and **concrete examples** where useful. +- Focus on **implementation and configuration**; keep prose concise and suitable for technical readers. +- Prefer **functional descriptions** over promotional copy. + +## Project structure + +- **Architecture:** The mailserver is made of multiple containers/pods (MTA, MDA, Web, Filter, SSL, Database, Redis, Unbound, Fetchmail) that together provide mail and management. +- **Container images:** Built under **`target/`**. Each subdirectory is one service (e.g. `target/mta/`, `target/mda/`, `target/filter/`, `target/web/`, `target/db/`, `target/unbound/`, `target/ssl/`). +- **Deployment manifests:** + - **Docker Compose:** `deploy/compose/` (e.g. `mta.yaml`, `mda.yaml`, `web.yaml`, `db.yaml`). + - **Kubernetes (Kustomize):** `deploy/kustomize/` (e.g. `mta/`, `mda/`, `web/`, `ingress/`). +- **Deployment consistency:** The same capabilities should be reflected in both Compose and Kustomize. When you change one (e.g. env vars, volumes, services), update the other so Docker and Kubernetes deployments stay in parity. + +## Quick reference for agents + +- **Adding a new feature that needs docs:** Add or update the right Diátaxis type (tutorial step, how-to, reference section, or explanation). Keep one purpose per doc; link between them. +- **Adding env vars or ports:** Document in **`reference/environment-variables.md`** or **`reference/ports.md`**; mention in the relevant how-to if it affects a procedure. +- **Adding a new how-to:** Create under **`how-to/`** with a “How to …” title; add the page to **`.mkdocs.yaml`** under “How-to guides”. +- **Changing deployment (Compose or Kustomize):** Apply the same logical change in **`deploy/compose/`** and **`deploy/kustomize/`** where applicable. diff --git a/docs/README.md b/docs/README.md index d5c665cb..2bcd717c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,58 +8,69 @@ This project enables you to operate your own email services, providing independence from large email providers. The solution is built on Alpine Linux and vendor base images, keeping container images lightweight while maintaining comprehensive functionality. -## Key Features - -- **Email Protocols**: POP3, IMAP, and SMTP with user authentication -- **Web Management**: Web-based interface for account, domain, and alias administration -- **Webmail**: Integrated webmail interface -- **External Mail Retrieval**: Fetchmail integration for retrieving emails from external providers -- **Email Authentication**: DKIM message signing for email authenticity -- **Spam Filtering**: Server-side mail filtering with configurable rules via web frontend -- **Spam Training**: Train spam filters by moving emails to or from the junk folder -- **Real-time Protection**: RBL (Real-Time Blackhole List) integration for spam prevention -- **Greylisting**: Selective greylisting for likely spam -- **Address Management**: Support for catch-all addresses and send-only accounts -- **Security**: Sender address restrictions and configurable address extensions -- **Quota Management**: Email quota management with notifications -- **TLS**: Enforced TLS for secure communication -- **Full-Text Search**: FTS support for efficient message searching -- **Health Monitoring**: Continuous self-monitoring via Docker healthcheck - -## Quick Start - -1. **[Installation Guide](installation.md)** - Get started with Docker or Kubernetes deployment -2. **[Upgrade Guide](upgrade.md)** - Upgrade procedures and version migration notes - -## Service Architecture +## Documentation structure + +The documentation is organised by purpose: + +- **[Tutorial: Getting Started](tutorials/getting-started.md)** — A step-by-step lesson to install docker-mailserver with Docker Compose and create your first mailbox. +- **How-to guides** — Task-oriented guides for specific goals (install on Kubernetes, configure DNS, manage users, configure TLS, and more). See the [How-to](how-to/install-docker.md) section in the navigation. +- **Reference** — Technical descriptions: [environment variables](reference/environment-variables.md), [DNS records](reference/dns-records.md), [ports](reference/ports.md), [service architecture](reference/service-architecture.md), [user roles](reference/user-roles.md), and related topics. +- **Explanation** — Background and context: [architecture](explanation/architecture.md), [DNS and email delivery](explanation/dns-and-email.md), [observability](explanation/observability.md). + +## Key features + +- **Email protocols:** POP3, IMAP, and SMTP with user authentication +- **Web management:** Web-based interface for account, domain, and alias administration +- **Webmail:** Integrated webmail interface +- **External mail retrieval:** Fetchmail integration for retrieving emails from external providers +- **Email authentication:** DKIM message signing for email authenticity +- **Spam filtering:** Server-side mail filtering with configurable rules via web frontend +- **Spam training:** Train spam filters by moving emails to or from the junk folder +- **Real-time protection:** RBL integration for spam prevention +- **Greylisting:** Selective greylisting for likely spam +- **Address management:** Catch-all addresses, send-only accounts, local address extension (RFC 5233) +- **Security:** Sender address restrictions and configurable address extensions +- **Quota management:** Email quota management with notifications +- **TLS:** Enforced TLS for secure communication +- **Full-text search:** FTS support for efficient message searching +- **Health monitoring:** Continuous self-monitoring via Docker healthcheck + +## Quick start + +1. **[Tutorial: Getting Started](tutorials/getting-started.md)** — Install with Docker Compose and create your first account +2. **[How to install with Docker](how-to/install-docker.md)** — Docker Compose installation steps +3. **[How to install on Kubernetes](how-to/install-kubernetes.md)** — Kubernetes deployment steps +4. **[How to upgrade](how-to/upgrade.md)** — Upgrade procedures and [upgrade changelog](reference/upgrade-changelog.md) + +## Service architecture The mailserver consists of multiple microservices: -- **MTA (Mail Transfer Agent)** - Postfix for SMTP -- **MDA (Mail Delivery Agent)** - Dovecot for IMAP/POP3 -- **Web** - Admin interface and Roundcube webmail -- **Filter** - RSpamd for spam filtering -- **SSL** - Certificate generation and management -- **Database** - MySQL for user and configuration data -- **Redis** - Caching and session storage -- **Unbound** - DNS resolver for the filter service -- **Fetchmail** - External mail retrieval (optional) +- **MTA (Mail Transfer Agent)** — Postfix for SMTP +- **MDA (Mail Delivery Agent)** — Dovecot for IMAP/POP3 +- **Web** — Admin interface and Roundcube webmail +- **Filter** — RSpamd for spam filtering +- **SSL** — Certificate generation and management +- **Database** — MySQL for user and configuration data +- **Redis** — Caching and session storage +- **Unbound** — DNS resolver for the filter service +- **Fetchmail** — External mail retrieval (optional) -See [Architecture Documentation](development/architecture.md) for detailed information. +See [Service architecture reference](reference/service-architecture.md) for a concise list and [About the service architecture](explanation/architecture.md) for context. -## Getting Help +## Getting help -- **[GitHub Issues](https://github.com/jeboehm/docker-mailserver/issues)** - Report bugs and request features -- **[Releases](https://github.com/jeboehm/docker-mailserver/releases)** - View release notes and changelog +- **[GitHub Issues](https://github.com/jeboehm/docker-mailserver/issues)** — Report bugs and request features +- **[Releases](https://github.com/jeboehm/docker-mailserver/releases)** — View release notes and changelog -## Container Images +## Container images Container images are available at: - [GitHub Container Registry](https://github.com/jeboehm?tab=packages&repo_name=docker-mailserver) - [Docker Hub](https://hub.docker.com/u/jeboehm?page=1&search=mailserver) -## Component References +## Component references - [Dovecot Documentation](https://doc.dovecot.org/2.4.1/) - [Postfix Documentation](https://www.postfix.org/documentation.html) @@ -68,6 +79,6 @@ Container images are available at: - [Redis Documentation](https://redis.io/docs/latest/) - [Unbound Documentation](https://unbound.docs.nlnetlabs.nl/en/latest/) -## Star History +## Star history [![Star History Chart](https://api.star-history.com/svg?repos=jeboehm/docker-mailserver&type=date&legend=top-left)](https://www.star-history.com/#jeboehm/docker-mailserver&type=date&legend=top-left) diff --git a/docs/administration/dashboard.md b/docs/administration/dashboard.md index 98e499e5..3db3ee63 100644 --- a/docs/administration/dashboard.md +++ b/docs/administration/dashboard.md @@ -1,5 +1,7 @@ # Dashboard -The dashboard is the main page of the administration tool. It provides a quick overview of the mailserver and the most important information. +The dashboard is the main page after login. It shows an overview of the mailserver: domains, users, and quick links to common tasks. ![Dashboard](../images/admin/dashboard.png) + +From the dashboard you can navigate to domain, user, alias, fetchmail, and DKIM management, and to the DNS Validation Wizard and observability dashboards when available. diff --git a/docs/administration/dkim-signing.md b/docs/administration/dkim-signing.md index 1434f0c6..68361e75 100644 --- a/docs/administration/dkim-signing.md +++ b/docs/administration/dkim-signing.md @@ -1,31 +1,3 @@ # DKIM Signing -DKIM (DomainKeys Identified Mail) signing provides cryptographic authentication for outgoing emails. This feature signs all outgoing emails from configured domains with a private key, allowing recipients to verify email authenticity through DNS records. - -## Implementation details - -DKIM signing is implemented using the Rspamd DKIM module. Each domain requires a separate DKIM key pair consisting of a private key (stored in docker-mailserver) and a public key (published in DNS). - -Rspamd verifies the DNS record for each domain before signing outgoing messages. This ensures that only domains with valid DKIM DNS records will have their emails signed, preventing false signatures. - -## Configuration steps - -Configure DKIM through the management interface: - -1. Access the management interface -2. Navigate to DKIM in the menu bar -3. Select the domain for DKIM configuration -4. Generate the private key -5. Add the provided DNS TXT record to your domain's DNS -6. Verify the DNS record through the management interface -7. Enable DKIM signing for the domain - -![DKIM Edit](../images/admin/dkim_edit.png) - -## DNS Record - -The management interface provides a DNS TXT record that must be added to your domain's DNS configuration. The record contains the public key used for DKIM verification by receiving mail servers. - -## Operation - -Once enabled, all outgoing emails from the configured domain are automatically signed with the DKIM private key. Receiving mail servers can verify the signature using the public key published in DNS, confirming the email's authenticity and integrity. +See **[How to configure DKIM signing](../how-to/configure-dkim.md)** for configuration steps. For DNS record format, see [DNS records reference](../reference/dns-records.md). diff --git a/docs/administration/dns-validation-wizard.md b/docs/administration/dns-validation-wizard.md index e9ac58cc..0154a741 100644 --- a/docs/administration/dns-validation-wizard.md +++ b/docs/administration/dns-validation-wizard.md @@ -1,13 +1,3 @@ # DNS Validation Wizard -The DNS Validation Wizard verifies DNS configuration for domains. It checks DNS records required for mailserver operation, including MX, SPF, DKIM, and DMARC records. - -![DNS Validation Wizard](../images/admin/dns_wizard.png) - -The wizard queries DNS records and displays the validation status for each record type. It shows which records are correctly configured and which require attention. - -## DNS Propagation - -DNS changes may take time to propagate across DNS servers. Typical propagation times range from a few minutes to 48 hours, depending on TTL values and DNS provider. If the wizard shows validation failures immediately after adding or modifying DNS records, wait for propagation to complete before re-checking. - -For detailed information about required DNS records and their configuration, see [DNS Configuration](../configuration/dns-configuration.md). +See **[How to validate DNS with the wizard](../how-to/validate-dns.md)** for usage. For required DNS records, see [DNS records reference](../reference/dns-records.md) and [How to configure DNS](../how-to/configure-dns.md). diff --git a/docs/administration/ios-macos-profile.md b/docs/administration/ios-macos-profile.md index 2949ba85..5e2c4f29 100644 --- a/docs/administration/ios-macos-profile.md +++ b/docs/administration/ios-macos-profile.md @@ -1,8 +1,3 @@ # iOS / macOS Profile -The iOS / macOS Profile feature generates configuration profiles for Apple Mail on iOS and macOS devices. These profiles automatically configure IMAP and SMTP access, eliminating the need for manual email account setup. - -Please refer to Apple's documentation for more information. - -- [MacOS documentation](https://support.apple.com/en-us/guide/mac-help/mh35561/mac) -- [iOS documentation](https://support.apple.com/en-us/102400) +See **[How to use the iOS / macOS Mail profile](../how-to/ios-macos-profile.md)** for usage and Apple documentation links. diff --git a/docs/administration/login.md b/docs/administration/login.md index 9d5d3833..b8b9f793 100644 --- a/docs/administration/login.md +++ b/docs/administration/login.md @@ -1,17 +1,15 @@ # Login -The login page provides authentication to access the `mailserver-admin` interface. Users can authenticate using either regular email address and password credentials and OAuth2, depending on the configuration. +The login page authenticates users to the mailserver-admin interface. Authentication methods are local (email + password) or OAuth2, depending on configuration. ![Login](../images/admin/login.png) -## Authentication Methods +## Authentication methods -### Local Authentication +### Local authentication -By default, users authenticate using their email address and password configured in the mailserver. +By default, users log in with their mailserver email address and password. -### OAuth2 Authentication +### OAuth2 -OAuth2 authentication can be enabled to allow users to log in using an external identity provider. When OAuth2 is enabled, a login button appears on the login page. Currently, this is only useful for granting admin rights to users. - -For OAuth2 configuration options, see [mailserver-admin configuration](../configuration/mailserver-admin.md#oauth2). +When OAuth2 is enabled, an OAuth2 login button is shown. Users can sign in via an external identity provider. OAuth2 is typically used to grant admin rights based on group membership. For setup, see [How to configure OAuth2](../how-to/configure-oauth2.md). For OAuth2 variables, see [mailserver-admin configuration reference](../reference/mailserver-admin-config.md#oauth2). diff --git a/docs/administration/manage-aliases.md b/docs/administration/manage-aliases.md index 14b401ee..d41a4376 100644 --- a/docs/administration/manage-aliases.md +++ b/docs/administration/manage-aliases.md @@ -1,95 +1,3 @@ # Manage Aliases -Alias management allows administrators to configure email forwarding rules. Aliases forward incoming emails from one address to one or more destination addresses, which can be within the same domain or external addresses. - -## Overview - -Email aliases provide flexible email routing without requiring separate user accounts. Common use cases include: - -- Forwarding emails to multiple recipients -- Creating generic addresses (e.g., `info@example.com`, `support@example.com`) -- Redirecting emails to external email providers -- Implementing catch-all functionality for specific patterns - -## Access Control - -- **Admin**: Can manage aliases across all domains -- **Domain Admin**: Can manage aliases within their assigned domain only -- **User**: Cannot manage aliases - -## Alias Operations - -### Adding an Alias - -1. Access the management interface -2. Navigate to **Alias** in the menu bar -3. Click **Add Alias** -4. Enter the following information: - - **Source Address**: The email address that will receive incoming emails and forward them to the configured destinations, formatted as a combination of local **name** part and **domain** part (e.g., `info@example.com`). - You can leave the **name** part empty to create a catch-all alias address. - - **Destination Address(es)**: An email address to forward emails to -5. Save the alias - -![Alias Create](../images/admin/alias_create.png) - -The source address must belong to a domain that exists in the system. Destination addresses can be: - -- Local users within the same domain -- Local users in other domains -- External email addresses - -**Note**: The system allows multiple aliases with the same source address (name) if they have different destination addresses. To forward emails from the same source address to additional destinations, create separate alias entries specifying the same source address but a different destination address for each entry. - -### Editing an Alias - -1. Navigate to **Alias** in the menu bar -2. Select the alias to edit -3. Modify alias configuration: - - **Source Address**: Change the receiving address - - **Destination Address**: Update forwarding destination -4. Save changes - -### Deleting an Alias - -1. Navigate to **Alias** in the menu bar -2. Select the alias to delete -3. Confirm the deletion - -**Note**: Deleting an alias only removes the forwarding rule. It does not affect any user accounts or email data. - -## Alias Behavior - -### Email Forwarding - -When an email is sent to an alias address: - -1. The mailserver receives the email -2. The alias configuration is checked -3. The email is forwarded to all configured destination addresses -4. When there is a local account with the receiving address, the email is delivered to the account mailbox. - -### Multiple Destinations - -When multiple destination addresses are configured, the email is forwarded to all addresses simultaneously. Each destination receives a complete copy of the original email. - -## Use Cases - -### Generic Addresses - -Create aliases for common business functions: - -- `info@example.com` → `team@example.com` -- `support@example.com` → `support1@example.com, support2@example.com` -- `sales@example.com` → `sales-team@example.com` - -### Personal Aliases - -Forward emails to personal accounts: - -- `john.doe@example.com` → `john.doe@gmail.com` - -### Distribution Lists - -Forward to multiple recipients: - -- `announcements@example.com` → `user1@example.com, user2@example.com, user3@example.com` +See **[How to manage aliases](../how-to/manage-aliases.md)** for step-by-step instructions. For access control, see [User roles reference](../reference/user-roles.md). diff --git a/docs/administration/manage-domains.md b/docs/administration/manage-domains.md index 3e10cf40..eb4e7730 100644 --- a/docs/administration/manage-domains.md +++ b/docs/administration/manage-domains.md @@ -1,41 +1,3 @@ # Manage Domains -Domain management allows administrators to configure mail domains for the mailserver. Each domain represents a distinct email namespace that can host multiple users and aliases. - -## Overview - -Domains define the email addresses that your mailserver can receive and send emails for. All email addresses must belong to a configured domain before users can be created or aliases can be defined. - -## Access Control - -Domain management is restricted to users with **Admin** role. Domain administrators and regular users cannot add, edit, or delete domains. - -## Domain Operations - -### Domain List - -The domain list shows all configured domains in the system: - -![Domain List](../images/admin/domain_list.png) - -### Adding a Domain - -1. Access the management interface -2. Navigate to **Domain** in the menu bar -3. Click **Add Domain** -4. Enter the domain name (e.g., `example.com`) -5. Save the domain - -The domain must be a valid domain name format. Once added, the domain is immediately available for user and alias configuration. - -### Editing a Domain - -It would be a destructive action to change the domain name. If you need to change the domain name, you should delete the domain and create a new one with the new name. - -### Deleting a Domain - -1. Navigate to **Domain** in the menu bar -2. Select the domain to delete -3. Confirm the deletion - -**Warning**: Deleting a domain removes all associated users, aliases, and DKIM configurations. This action cannot be undone. Ensure all data is backed up before deletion. +See **[How to manage domains](../how-to/manage-domains.md)** for step-by-step instructions. For access control, see [User roles reference](../reference/user-roles.md). diff --git a/docs/administration/manage-fetchmail.md b/docs/administration/manage-fetchmail.md index b634eaed..a8fd49e4 100644 --- a/docs/administration/manage-fetchmail.md +++ b/docs/administration/manage-fetchmail.md @@ -1,85 +1,3 @@ # Manage Fetchmail -Fetchmail management allows users and administrators to configure external email retrieval. Fetchmail connects to external mail servers (POP3 or IMAP) and retrieves emails, delivering them to local mailboxes on the mailserver. - -## Overview - -Fetchmail enables the mailserver to retrieve emails from external email providers and deliver them to local user accounts. This is useful for: - -- Migrating emails from external providers -- Consolidating multiple email accounts into a single mailbox -- Retrieving emails from providers that don't support forwarding -- Maintaining access to emails from legacy email systems - -## Access Control - -- **Admin**: Can manage fetchmail accounts for all users -- **Domain Admin**: Can manage fetchmail accounts for users within their assigned domain -- **User**: Can manage their own fetchmail accounts only - -## Fetchmail Operations - -### Adding a Fetchmail Account - -1. Access the management interface -2. Navigate to **Fetchmail** in the menu bar -3. Click **Add Fetchmail Account** -4. Enter the following information: - - **User**: Select the local user account that will receive the retrieved emails - - **Server**: Hostname or IP address of the external mail server - - **Port**: Port number for the mail server (typically 110 for POP3, 143 for IMAP, 995 for POP3S, 993 for IMAPS) - - **Protocol**: Select POP3 or IMAP - - **Username**: Username for authenticating with the external mail server - - **Password**: Password for authenticating with the external mail server - - **SSL**: Enable secure connection (recommended) - - **SSL Verify**: Verify the external mail server's certificate -5. Save the fetchmail account - -![Fetchmail Create](../images/admin/fetchmail_create.png) - -### Editing a Fetchmail Account - -1. Navigate to **Fetchmail** in the menu bar -2. Select the fetchmail account to edit -3. Modify configuration: - - **Server**: Update mail server address - - **Port**: Change port number - - **Protocol**: Switch between POP3 and IMAP - - **Username/Password**: Update authentication credentials - - **SSL**: Enable or disable secure connection - - **SSL Verify**: Verify the external mail server's certificate -4. Save changes - -You can see the last transaction log with the external mail server in the field "Last run log". -This helps to troubleshoot issues with the fetchmail account. - -### Deleting a Fetchmail Account - -1. Navigate to **Fetchmail** in the menu bar -2. Select the fetchmail account to delete -3. Confirm the deletion - -**Note**: Deleting a fetchmail account stops email retrieval but does not affect emails already delivered to the local mailbox. - -## Retrieval Schedule - -Fetchmail runs periodically to check for new emails on external servers. The retrieval interval is configured at the mailserver level and applies to all fetchmail accounts. - -## Security Considerations - -### Authentication Credentials - -Fetchmail stores authentication credentials securely. However, consider the following: - -- Use strong, unique passwords for external mail server accounts -- Enable SSL to encrypt credential transmission -- Regularly review and update fetchmail account credentials -- Disable unused fetchmail accounts - -### Network Security - -Ensure the mailserver can reach external mail servers: - -- Configure firewall rules to allow outbound connections to external mail servers -- Verify DNS resolution for external mail server hostnames -- Test connectivity before configuring fetchmail accounts +See **[How to manage fetchmail accounts](../how-to/manage-fetchmail.md)** for step-by-step instructions. For access control, see [User roles reference](../reference/user-roles.md). diff --git a/docs/administration/manage-users.md b/docs/administration/manage-users.md index c00afdce..0a8e84b6 100644 --- a/docs/administration/manage-users.md +++ b/docs/administration/manage-users.md @@ -1,110 +1,3 @@ # Manage Users -User management allows administrators to create and configure email accounts. Each user account represents an email address that can send and receive emails through the mailserver. - -## Overview - -Users are email accounts associated with a specific domain. Each user has a unique email address, password, and optional quota limits. Users can access their email through IMAP, POP3, or the webmail interface. - -## Access Control - -- **Admin**: Can manage users across all domains -- **Domain Admin**: Can manage users within their assigned domain only -- **User**: Cannot manage other users, only their own account settings - -See [User Roles](user-roles.md) for more information. - -## User Operations - -### User List - -The user list shows all configured users in the system: - -![User List](../images/admin/user_list.png) - -### Adding a User - -1. Access the management interface -2. Navigate to **User** in the menu bar -3. Click **Add User** -4. Enter the following information: - - **Email Address**: The full email address (e.g., `user@example.com`) - - **Password**: Set an initial password for the account - - **Quota** (optional): Storage limit in megabytes - - **Admin**: Whether the user is an administrator - - **Domain Admin**: Whether the user is a domain administrator - - **Enabled**: Whether the user is enabled - - **Send Only**: Whether the user can only send emails -5. Save the user - -The email address must belong to a domain that exists in the system. The password should meet security requirements (complexity, length) as configured in the mailserver. - -### Editing a User - -1. Navigate to **User** in the menu bar -2. Select the user to edit -3. Modify user details: - - **Password**: Update the account password - - **Quota**: Adjust storage limits - - **Admin**: Whether the user is an administrator - - **Domain Admin**: Whether the user is a domain administrator - - **Enabled**: Whether the user is enabled - - **Send Only**: Whether the user can only send emails -4. Save changes - -![User Edit](../images/admin/user_edit.png) - -**Note**: Changing the email address is typically not supported. To change an email address, create a new user and migrate data if needed. - -### Deleting a User - -1. Navigate to **User** in the menu bar -2. Select the user to delete -3. Confirm the deletion - -**Warning**: Deleting a user permanently removes the email account and all associated email data. This action cannot be undone. Ensure important emails are backed up before deletion. - -## User Properties - -### Email Address - -The email address uniquely identifies the user account. It consists of a local part (before the @) and a domain part (after the @). The email address format must be valid according to RFC 5322. - -### Password - -User passwords are stored securely using hashing algorithms. Passwords can be set during user creation or updated later through the user management interface. Password policies are enforced by the mailserver configuration. - -### Quota - -Email storage quotas limit the amount of disk space a user's mailbox can consume. Quotas are specified in megabytes. When a user reaches their quota limit: - -- Incoming emails may be rejected -- The user cannot send new emails until space is freed -- Quota warnings are sent to the user - -### Send Only - -When a user is set to send only, they can only send emails. They cannot receive emails via IMAP, POP3 or the webmail interface. - -### Admin - -When a user is set to admin, they can manage other users and domains. - -See [User Roles](user-roles.md) for more information. - -### Domain Admin - -When a user is set to domain admin, they can manage users and aliases within their assigned domain. - -See [User Roles](user-roles.md) for more information. - -## User Access - -Once created, users can access their email accounts through: - -- **IMAP**: For email client access (port 143 with TLS) -- **POP3**: For email client access (port 110 with TLS) -- **SMTP**: For email sending (port 587 with TLS) -- **Webmail**: Roundcube web interface accessible through the web service - -Users authenticate using their full email address and password. +See **[How to manage users](../how-to/manage-users.md)** for step-by-step instructions. For user properties and access control, see [User roles reference](../reference/user-roles.md). diff --git a/docs/administration/user-roles.md b/docs/administration/user-roles.md index 6b887787..c137abb6 100644 --- a/docs/administration/user-roles.md +++ b/docs/administration/user-roles.md @@ -1,42 +1,3 @@ # User Roles -In `mailserver-admin`, there are three distinct user roles, each with different levels of access and permissions: - -## Admin - -**Permissions**: Can perform all actions within the application. - -**Capabilities**: - -- Manage all mail domains, users, aliases, and DKIM settings -- Full access to all features and configurations - -## Domain Admin - -**Permissions**: Limited to managing users, aliases, and fetchmail accounts within their own domain. - -**Capabilities**: - -- Create, update, and remove users within their domain -- Define and manage mail aliases within their domain -- Configure and manage fetchmail accounts within their domain - -**Restrictions**: - -- Cannot add or edit new domains -- Cannot manage DKIM settings for any domain - -## User - -**Permissions**: Limited to managing their own fetchmail accounts. - -**Capabilities**: - -- Login to the application -- Configure and manage their personal fetchmail accounts -- Change their own password with strict password policy - -**Restrictions**: - -- Cannot manage users, aliases, or domains -- No access to DKIM settings or domain configurations +See **[User roles reference](../reference/user-roles.md)** for permissions and capabilities of Admin, Domain Admin, and User roles. diff --git a/docs/configuration/dns-configuration.md b/docs/configuration/dns-configuration.md index 11d87486..6f6c3b78 100644 --- a/docs/configuration/dns-configuration.md +++ b/docs/configuration/dns-configuration.md @@ -1,283 +1,5 @@ # DNS Configuration -This document describes the DNS records required for the mailserver to function properly. All DNS records must be configured in your domain's DNS zone to enable email delivery, authentication, and reputation management. - -## Overview - -The mailserver requires several DNS record types to operate correctly: - -- **MX Record**: Directs incoming emails to your mailserver -- **A/AAAA Records**: Resolve the mailserver hostname to IP addresses -- **SPF Record**: Authorizes your mailserver to send emails for your domain -- **DKIM Record**: Provides public key for email signature verification -- **DMARC Record**: Defines email authentication policy and reporting - -## MX Record - -The Mail Exchange (MX) record directs incoming emails to your mailserver. This is the primary DNS record that tells other mail servers where to deliver emails for your domain. - -### MX Record Configuration - -Create an MX record in your domain's DNS zone: - -```text -Type: MX -Name: @ (or your domain name) -Priority: 10 -Value: mail.example.com -``` - -Replace `mail.example.com` with the value configured in the `MAILNAME` environment variable. The priority value (10 in this example) determines the order when multiple MX records exist. Lower numbers have higher priority. - -### MX Record Example - -For domain `example.com` with mailserver hostname `mail.example.com`: - -```text -example.com. IN MX 10 mail.example.com. -``` - -### MX Record Verification - -Verify the MX record using DNS lookup tools: - -```bash -dig MX example.com -# or -nslookup -type=MX example.com -``` - -## A and AAAA Records - -A and AAAA records resolve the mailserver hostname to IPv4 and IPv6 addresses respectively. These records are required for the MX record to function, as the MX record points to a hostname that must resolve to an IP address. - -### A/AAAA Record Configuration - -Create A and AAAA records for your mailserver hostname: - -```text -Type: A -Name: mail (or your mailserver hostname without domain) -Value: 192.0.2.1 - -Type: AAAA -Name: mail (or your mailserver hostname without domain) -Value: 2001:db8::1 -``` - -Replace the IP addresses with your mailserver's actual IPv4 and IPv6 addresses. If your mailserver only has IPv4, you can omit the AAAA record, though IPv6 is recommended for modern email infrastructure. - -### A/AAAA Record Example - -For mailserver hostname `mail.example.com`: - -```text -mail.example.com. IN A 192.0.2.1 -mail.example.com. IN AAAA 2001:db8::1 -``` - -### A/AAAA Record Verification - -Verify the A and AAAA records: - -```bash -dig A mail.example.com -dig AAAA mail.example.com -# or -nslookup mail.example.com -``` - -## SPF Record - -The Sender Policy Framework (SPF) record authorizes your mailserver to send emails on behalf of your domain. SPF helps prevent email spoofing by specifying which mail servers are allowed to send emails for your domain. - -### SPF Record Configuration - -Create a TXT record with SPF policy: - -```text -Type: TXT -Name: @ (or your domain name) -Value: v=spf1 mx a ip4:192.0.2.1 ip6:2001:db8::1 ~all -``` - -### SPF Mechanisms - -Common SPF mechanisms used in mailserver configurations: - -- `mx`: Authorizes the mail servers listed in MX records -- `a`: Authorizes the IP addresses of A records for the domain -- `ip4:192.0.2.1`: Explicitly authorizes a specific IPv4 address -- `ip6:2001:db8::1`: Explicitly authorizes a specific IPv6 address -- `include:example.com`: Includes SPF policy from another domain -- `~all`: Soft fail for all other sources (recommended during testing) -- `-all`: Hard fail for all other sources (recommended for production) - -### SPF Record Example - -For domain `example.com` with mailserver at `mail.example.com`: - -```text -example.com. IN TXT "v=spf1 mx a ip4:192.0.2.1 ~all" -``` - -### SPF Record Verification - -Verify the SPF record: - -```bash -dig TXT example.com -# or use SPF validation tools -``` - -SPF records must be published as TXT records. Some DNS providers may also support the deprecated SPF record type, but TXT is the standard. - -## DKIM Record - -DomainKeys Identified Mail (DKIM) records publish the public key used to verify email signatures. DKIM signing is configured through the management interface, which generates the DNS TXT record that must be published. - -### DKIM Record Configuration - -DKIM records are generated through the management interface: - -1. Access the management interface -2. Navigate to **DKIM** in the menu bar -3. Select the domain for DKIM configuration -4. Generate the DKIM key pair -5. Copy the provided DNS TXT record -6. Add the record to your domain's DNS - -### Record Format - -DKIM records use a specific subdomain format: - -```text -Type: TXT -Name: default._domainkey (or selector._domainkey) -Value: v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC... -``` - -The record name includes a selector (typically `default`) and the `_domainkey` subdomain. The value contains the DKIM version, key type, and public key. - -### DKIM Record Example - -For domain `example.com` with selector `default`: - -```text -default._domainkey.example.com. IN TXT "v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC..." -``` - -### DKIM Record Verification - -After publishing the DKIM record, verify it through the management interface. The interface checks DNS propagation and validates the record format. You can also verify manually: - -```bash -dig TXT default._domainkey.example.com -``` - -See [DKIM Signing](../administration/dkim-signing.md) for detailed DKIM configuration instructions. - -## DMARC Record - -Domain-based Message Authentication, Reporting & Conformance (DMARC) records define email authentication policy and enable reporting. DMARC works in conjunction with SPF and DKIM to provide comprehensive email authentication. - -### DMARC Record Configuration - -Create a TXT record with DMARC policy: - -```text -Type: TXT -Name: _dmarc -Value: v=DMARC1; p=none; rua=mailto:dmarc@example.com -``` - -### DMARC Policy Options - -Common DMARC policy settings: - -- `p=none`: Monitor mode - no action taken, useful for initial deployment -- `p=quarantine`: Quarantine emails that fail authentication -- `p=reject`: Reject emails that fail authentication (recommended for production) - -### DMARC Tags - -- `v=DMARC1`: DMARC version (required) -- `p=`: Policy for emails that fail authentication (none, quarantine, reject) -- `rua=mailto:dmarc@example.com`: Email address for aggregate reports -- `ruf=mailto:dmarc@example.com`: Email address for forensic reports -- `pct=100`: Percentage of emails to apply policy to (default: 100) -- `aspf=r`: SPF alignment mode (relaxed or strict) -- `adkim=r`: DKIM alignment mode (relaxed or strict) -- `fo=0`: Failure reporting options - -### Example Policies - -**Monitoring mode** (recommended for initial deployment): - -```text -_dmarc.example.com. IN TXT "v=DMARC1; p=none; rua=mailto:dmarc@example.com" -``` - -**Quarantine mode** (after monitoring period): - -```text -_dmarc.example.com. IN TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@example.com; pct=100" -``` - -**Reject mode** (production, after validation): - -```text -_dmarc.example.com. IN TXT "v=DMARC1; p=reject; rua=mailto:dmarc@example.com; aspf=r; adkim=r" -``` - -### DMARC Record Verification - -Verify the DMARC record: - -```bash -dig TXT _dmarc.example.com -``` - -## DNS Record Summary - -For a complete mailserver setup, configure the following DNS records: - -| Record Type | Name | Value | Purpose | -| ----------- | -------------------- | --------------------------- | ---------------------------------- | -| MX | `@` | `10 mail.example.com` | Direct incoming emails | -| A | `mail` | `192.0.2.1` | Resolve mailserver hostname (IPv4) | -| AAAA | `mail` | `2001:db8::1` | Resolve mailserver hostname (IPv6) | -| TXT (SPF) | `@` | `v=spf1 mx a ~all` | Authorize sending servers | -| TXT (DKIM) | `default._domainkey` | `v=DKIM1; k=rsa; p=...` | Email signature verification | -| TXT (DMARC) | `_dmarc` | `v=DMARC1; p=none; rua=...` | Authentication policy | - -## Troubleshooting - -### Common Issues - -**Emails not being received:** - -- Verify MX record points to correct hostname -- Ensure A/AAAA records resolve the mailserver hostname -- Check firewall rules allow connections on port 25 - -**Emails marked as spam:** - -- Verify SPF record is correctly configured -- Ensure DKIM record is published and verified -- Check DMARC policy is not too restrictive during initial setup -- Review DMARC reports for authentication failures - -**DKIM verification failures:** - -- Verify DKIM DNS record is published correctly -- Check DNS propagation is complete -- Ensure the selector matches between DNS and mailserver configuration -- Verify the public key in DNS matches the private key in mailserver - -**SPF failures:** - -- Verify all sending IP addresses are included in SPF record -- Check for syntax errors in SPF record -- Ensure SPF record is published as TXT record type -- Review SPF mechanisms (mx, a, ip4, ip6) are appropriate for your setup +- **[DNS records reference](../reference/dns-records.md)** — Record types, formats, and examples (MX, SPF, DKIM, DMARC) +- **[How to configure DNS for your domain](../how-to/configure-dns.md)** — Step-by-step configuration +- **[About DNS and email delivery](../explanation/dns-and-email.md)** — Why MX, SPF, DKIM, and DMARC matter diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md index 5fc551cf..51c0d09c 100644 --- a/docs/configuration/environment-variables.md +++ b/docs/configuration/environment-variables.md @@ -1,121 +1,3 @@ # Environment Variables Configuration -This document provides an overview of all environment variables used to configure `docker-mailserver` project. - -## Basic Configuration Variables - -These are the core environment variables that need to be configured in your `.env` file for basic mailserver functionality. - -### Database Configuration - -When you use the MySQL service provided by docker-mailserver compose, you don't need to configure this. -It is required to **always set** `MYSQL_PASSWORD`. - -| Variable | Default | Description | -| ----------------------- | ------------------------------------ | ---------------------------------- | -| `MYSQL_HOST` | `db` | MySQL database hostname | -| `MYSQL_PORT` | `3306` | MySQL database port | -| `MYSQL_DATABASE` | `mailserver` | MySQL database name | -| `MYSQL_USER` | `root` (MTA/MDA), `mailserver` (Web) | MySQL database username | -| `MYSQL_PASSWORD` | _(empty)_ | MySQL database password | -| `MYSQL_TLS_VERIFY_CERT` | `no` | MySQL TLS certificate verification | - -### Mail Server Identity - -| Variable | Default | Description | -| --------------------- | ------------------------ | ----------------------------------------------------------------- | -| `MAILNAME` | `mail.example.com` | Primary mail server hostname | -| `POSTMASTER` | `postmaster@example.com` | Postmaster email address | -| `RECIPIENT_DELIMITER` | `-` | Character used for address extensions (e.g., user+tag@domain.com) | - -### Redis Configuration - -When you use the Redis service provided by docker-mailserver compose or kustomize, you don't need to configure this. -It is required to **always set** `REDIS_PASSWORD`. - -| Variable | Default | Description | -| ---------------- | ------------ | --------------------- | -| `REDIS_HOST` | `redis` | Redis server hostname | -| `REDIS_PORT` | `6379` | Redis server port | -| `REDIS_PASSWORD` | _(required)_ | Redis server password | - -### Authentication - -| Variable | Default | Description | -| --------------------- | ------------ | ------------------------------------- | -| `CONTROLLER_PASSWORD` | _(required)_ | Password for RSpamd controller access | -| `DOVEADM_API_KEY` | _(required)_ | Password for Dovecot API access | - -### Relay Configuration - -| Variable | Default | Description | -| ------------------- | ------- | --------------------------------- | -| `RELAYHOST` | `false` | SMTP relay host for outgoing mail | -| `RELAY_PASSWD_FILE` | `false` | Path to relay authentication file | - -### Filter Configuration - -Block suspicious attachments by type (bat, com, exe, dll, vbs, docm, doc, dzip). - -| Variable | Default | Description | -| ------------- | ------- | ---------------------------- | -| `FILTER_MIME` | `false` | Enable MIME header filtering | - -## Extended Configuration Variables - -These variables are used for service-to-service communication and configuration. You need them -when you use Kubernetes or decide to rename services somehow. - -### Service Address Configuration - -| Variable | Default | Description | -| ----------------------------- | ------------------------ | --------------------------------------- | -| `FILTER_MILTER_ADDRESS` | `filter:11332` | RSpamd milter service address | -| `FILTER_WEB_ADDRESS` | `filter:11334` | RSpamd web interface address | -| `MDA_AUTH_ADDRESS` | `mda:2004` | Dovecot authentication service address | -| `MDA_IMAP_ADDRESS` | `mda:143` | Dovecot IMAP service address | -| `MDA_LMTP_ADDRESS` | `mda:2003` | Dovecot LMTP service address | -| `MDA_MANAGESIEVE_ADDRESS` | `mda:4190` | Dovecot ManageSieve service address | -| `MTA_HOST` | `mta` | Postfix MTA hostname | -| `MTA_SMTP_ADDRESS` | `mta:25` | Postfix SMTP service address | -| `MTA_SMTP_SUBMISSION_ADDRESS` | `mta:587` | Postfix SMTP submission service address | -| `WEB_HTTP_ADDRESS` | `web:80` | Web interface HTTP address | -| `RSPAMD_DNS_SERVERS` | `round-robin:unbound:53` | DNS servers for RSpamd (Kubernetes) | - -### mailserver-admin Configuration - -See [mailserver-admin](mailserver-admin.md) for more information. - -### PHP Configuration - -| Variable | Default | Description | -| -------------------------- | ---------------------------------------------------------- | -------------------- | -| `PHP_SESSION_SAVE_HANDLER` | `redis` | Session save handler | -| `PHP_SESSION_SAVE_PATH` | `tcp://${REDIS_HOST}:${REDIS_PORT}?auth=${REDIS_PASSWORD}` | Session save path | - -### Proxy Protocol Configuration - -These variables enable HAProxy PROXY protocol support for load balancer integration. - -| Variable | Default | Description | -| -------------------- | ------- | ---------------------------------------------------------------------------- | -| `MDA_UPSTREAM_PROXY` | `false` | Enable Traefik / HAProxy PROXY protocol for MDA (Dovecot) IMAP/POP3 services | -| `MTA_UPSTREAM_PROXY` | `false` | Enable Traefik / HAProxy PROXY protocol for MTA (Postfix) SMTP services | - -#### Usage - -When set to `true`, these variables enable the HAProxy / Traefik PROXY protocol, which allows the mail server to receive the original client IP address when behind a load balancer or reverse proxy. - -**MDA_UPSTREAM_PROXY** affects: - -- IMAP service -- IMAPS service -- POP3 service -- POP3S service - -**MTA_UPSTREAM_PROXY** affects: - -- SMTP service -- SMTP submission service - -This is typically used when deploying behind load balancers like HAProxy, Traefik, or cloud load balancers that support the PROXY protocol. +See **[Environment variables reference](../reference/environment-variables.md)** for the full list of environment variables and their descriptions. diff --git a/docs/configuration/external-mysql.md b/docs/configuration/external-mysql.md index fa0902b2..3dc1de5b 100644 --- a/docs/configuration/external-mysql.md +++ b/docs/configuration/external-mysql.md @@ -1,136 +1,3 @@ # External MySQL Configuration -## Overview - -The `docker-mailserver` can be configured to use an external MySQL database instead of the built-in database service. This is particularly useful for production deployments, Kubernetes environments, or when you want to use an existing MySQL infrastructure. - -## Environment Variables - -To use an external MySQL database, configure the following environment variables in your `.env` file: - -```bash -# External MySQL Configuration -MYSQL_HOST=your-mysql-host.example.com -MYSQL_DATABASE=mailserver -MYSQL_USER=mailserver_user -MYSQL_PASSWORD=your_secure_password -``` - -### Variable Descriptions - -- **MYSQL_HOST**: The hostname or IP address of your MySQL server -- **MYSQL_DATABASE**: The database name to use (will be created if it doesn't exist) -- **MYSQL_USER**: The MySQL username for database access -- **MYSQL_PASSWORD**: The password for the MySQL user - -## Database Initialization - -### Required SQL Files - -The mailserver requires two SQL initialization files to be imported into your external MySQL database: - -1. **`target/db/rootfs/docker-entrypoint-initdb.d/001_mailserver.sql`** - Core mailserver schema -2. **`target/db/rootfs/docker-entrypoint-initdb.d/002_webmail.sql`** - Webmail-specific schema - -### Import Process - -#### Option 1: Manual Import - -1. **Connect to your MySQL server**: - - ```bash - mysql -h your-mysql-host.example.com -u root -p - ``` - -2. **Create the database** (if it doesn't exist): - - ```sql - CREATE DATABASE mailserver CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; - ``` - -3. **Import the SQL files**: - ```bash - mysql -h your-mysql-host.example.com -u root -p mailserver < target/db/rootfs/docker-entrypoint-initdb.d/001_mailserver.sql - mysql -h your-mysql-host.example.com -u root -p mailserver < target/db/rootfs/docker-entrypoint-initdb.d/002_webmail.sql - ``` - -#### Option 2: Using Docker - -If you have the SQL files locally, you can use Docker to import them: - -```bash -# Import mailserver schema -docker run --rm -v $(pwd)/target/db/rootfs/docker-entrypoint-initdb.d:/sql mysql:lts mysql -h your-mysql-host.example.com -u root -p mailserver < /sql/001_mailserver.sql - -# Import webmail schema -docker run --rm -v $(pwd)/target/db/rootfs/docker-entrypoint-initdb.d:/sql mysql:lts mysql -h your-mysql-host.example.com -u root -p mailserver < /sql/002_webmail.sql -``` - -## Docker Compose Configuration - -### Removing the Built-in Database - -To use an external MySQL database with Docker Compose, remove the database service: - -1. **Edit `deploy/compose/db.yaml`**: - - ```yaml - # Comment out or remove the entire db service - # services: - # db: - # image: mysql:lts - # restart: on-failure:5 - # env_file: ../../.env - # volumes: - # - ../../target/db/rootfs/docker-entrypoint-initdb.d:/docker-entrypoint-initdb.d:ro - # - data-db:/var/lib/mysql - ``` - -2. **Update service dependencies**: - - Remove `depends_on: - db` from services that depend on the database - - The services will connect to the external MySQL host instead - -### Example Configuration - -```yaml -# In your docker-compose.yml or compose override -services: - web: - environment: - - MYSQL_HOST=your-mysql-host.example.com - - MYSQL_DATABASE=mailserver - - MYSQL_USER=mailserver_user - - MYSQL_PASSWORD=your_secure_password - # Remove depends_on: db if present -``` - -## Kubernetes Configuration - -External MySQL is **required** for Kubernetes deployments, as the provided kustomization does not include a database service. - -### Prerequisites - -1. **Existing MySQL Server**: Ensure you have a MySQL-compatible database (MySQL, Percona XtraDB, MariaDB) -2. **Database Access**: Verify network connectivity from your Kubernetes cluster to the MySQL server -3. **Credentials**: Create a MySQL user with appropriate permissions - -## Database Migrations - -After importing the initial SQL files, you need to restart the web service to apply any database migrations: - -### Docker Compose - -```bash -# Restart the web service to apply migrations -docker-compose restart web - -# Or if using the production script -bin/production.sh restart web -``` - -### Kubernetes - -```bash -# Restart the web deployment -kubectl rollout restart deployment/web -n mail -``` +See **[How to use an external MySQL database](../how-to/configure-external-mysql.md)** for setup steps. For variable reference, see [Environment variables reference](../reference/environment-variables.md) (Database section). diff --git a/docs/configuration/local-address-extension.md b/docs/configuration/local-address-extension.md index 146bd10c..d1087912 100644 --- a/docs/configuration/local-address-extension.md +++ b/docs/configuration/local-address-extension.md @@ -1,53 +1,3 @@ # Local Address Extension -Local address extension allows multiple unique email addresses to be delivered to a single mailbox without additional configuration. This feature implements RFC 5233 subaddressing and is commonly known as plus-addressing. - -## Implementation - -The feature appends a configurable delimiter followed by any string to the base email address. All emails sent to extended addresses are delivered to the original mailbox. The default delimiter is `-` (dash). - -Alternative names for this feature: - -- Plus-addressing (traditional `+` delimiter) -- Subaddressing (RFC 5233 standard) -- Address tagging - -## Examples - -```text -user1-friends@example.com -user1-1382@example.com -user1-newsletter@example.com -user1-shopping@example.com -user1-temp@example.com -``` - -## Configuration - -Configure the delimiter using the `RECIPIENT_DELIMITER` environment variable: - -```bash -RECIPIENT_DELIMITER=+ -``` - -This changes the delimiter from `-` to `+`, allowing addresses like `user1+friends@example.com`. - -## Sieve Integration - -Extended addresses can be used in Sieve filtering rules for automated email processing. Sieve rules can sort emails into folders, apply actions, or forward based on the extension used. - -Example Sieve rule for `user1-newsletter@example.com`: - -```sieve -if address :matches :localpart "to" "user1-newsletter*" { - fileinto "Newsletters"; -} -``` - -## Use Cases - -- Email categorisation by source or purpose -- Service-specific addresses without multiple mailboxes -- Spam source identification -- Temporary address generation -- Email routing and filtering +See **[Local address extension reference](../reference/local-address-extension.md)** for configuration and Sieve usage. diff --git a/docs/configuration/mailserver-admin.md b/docs/configuration/mailserver-admin.md index c91358c7..4bbdf5be 100644 --- a/docs/configuration/mailserver-admin.md +++ b/docs/configuration/mailserver-admin.md @@ -1,92 +1,3 @@ -# mailserver-admin configuration +# mailserver-admin Configuration -## OAuth2 - -The `mailserver-admin` application supports OAuth2/OIDC authentication for user login. When OAuth2 is enabled, users authenticate through an external identity provider instead of using local credentials. - -### Authentication Flow - -1. User clicks the OAuth2 login button and is redirected to the configured identity provider -2. After successful authentication, the provider redirects back to `https://example.com/login/check-oauth` -3. The application retrieves user information from the provider's userinfo endpoint -4. The application extracts the user identifier from the field specified in `OAUTH_PATHS_IDENTIFIER` -5. The application attempts to match this identifier with existing users in the database -6. If a match is found, the user is logged in with their existing account -7. If no match is found and `OAUTH_CREATE_USER` is enabled, a new user account is created automatically -8. If no match is found and `OAUTH_CREATE_USER` is disabled, login is denied - -### User Identifier Configuration - -The `OAUTH_PATHS_IDENTIFIER` configuration specifies which field from the OAuth2 provider's user information contains the user identifier. This field must contain an email address that matches an existing domain configured in the mailserver. - -**Important requirements:** - -- The identifier must be a valid email address with a domain that exists in the domain list -- The field must be write-protected in the OAuth2 provider (not user-editable) -- Do not use the standard `email` field from common identity providers, as users can typically change their email address - -**Recommended OAuth2 Providers:** - -[pocket-id](https://pocket-id.org) is a tested solution that provides write-protected email attributes suitable for this use case. When using pocket-id or similar providers, configure `OAUTH_PATHS_IDENTIFIER` to point to a field that contains the user's email address and cannot be modified by the user. - -### Administrator Access Control - -Administrator rights can be granted based on the groups claim in the OAuth2 provider. Configure the `OAUTH_ADMIN_GROUP` variable with the name of the administrator group in your identity provider. Users who are members of this group will receive administrator privileges in `mailserver-admin`. - -### OAuth2 Client Setup - -To use OAuth2, create a new OAuth2 client in your identity provider with the following settings: - -- **Redirect URI:** `https://example.com/login/check-oauth` (replace with your actual domain) -- **Client ID and Secret:** Add these values to the `.env` file as `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET` - -### OAuth2 configuration example - -```bash -OAUTH_ENABLED=true -OAUTH_CLIENT_ID=xxxxx-xxxx-xxxx-xxxx-xxxxxxx -OAUTH_CLIENT_SECRET=xxxxxxxxxxxxx -OAUTH_CLIENT_SCOPES="email profile groups" -OAUTH_AUTHORIZATION_URL=https://id.example.com/authorize -OAUTH_ACCESS_TOKEN_URL=https://id.example.com/api/oidc/token -OAUTH_INFOS_URL=https://id.example.com/api/oidc/userinfo -OAUTH_BUTTON_TEXT="Login with OIDC" -OAUTH_ADMIN_GROUP=admin -OAUTH_PATHS_IDENTIFIER=sub -OAUTH_CREATE_USER=true -``` - -## Environment variables - -The following environment variables can be set in the `.env` file or in the environment: - -### General Configuration - -- `APP_ENV`: The environment the application is running in. Default: `prod` -- `APP_SECRET`: A secret key used by Symfony for various purposes (e.g., CSRF tokens). Default: `randomly generated`. -- `CSRF_ENABLED`: Whether CSRF protection is enabled. Default: `true`. -- `TRUSTED_PROXIES`: A list of trusted proxy IP addresses. - -### Database Configuration - -- `MYSQL_USER`: The MySQL database user. -- `MYSQL_PASSWORD`: The MySQL database password. -- `MYSQL_HOST`: The MySQL database host. -- `MYSQL_DATABASE`: The MySQL database name. -- `REDIS_HOST`: The Redis server host. -- `REDIS_PORT`: The Redis server port. -- `REDIS_PASSWORD`: The Redis server password. - -### OAuth2 Configuration - -- `OAUTH_ENABLED`: Whether OAuth2 is enabled. Default: `false`. -- `OAUTH_CLIENT_ID`: The client ID for the OAuth2 provider. -- `OAUTH_CLIENT_SECRET`: The client secret for the OAuth2 provider. -- `OAUTH_CLIENT_SCOPES`: The scopes requested from the OAuth2 provider. Default: `"email profile groups"`. -- `OAUTH_AUTHORIZATION_URL`: The authorization URL for the OAuth2 provider. -- `OAUTH_ACCESS_TOKEN_URL`: The access token URL for the OAuth2 provider. -- `OAUTH_INFOS_URL`: The user information URL for the OAuth2 provider. -- `OAUTH_ADMIN_GROUP`: The name of the administrator group in the OAuth2 provider. -- `OAUTH_BUTTON_TEXT`: The text displayed on the OAuth2 login button. Default: `"Login with OIDC"`. -- `OAUTH_PATHS_IDENTIFIER`: The path to the identifier in the OAuth2 provider. Default: `"sub"`. -- `OAUTH_CREATE_USER`: Whether to create a new user if no match is found in the database. Default: `false`. +See **[mailserver-admin configuration reference](../reference/mailserver-admin-config.md)** for environment variables. For OAuth2 setup, see [How to configure OAuth2](../how-to/configure-oauth2.md). diff --git a/docs/configuration/php-sessions.md b/docs/configuration/php-sessions.md index 25ee7e84..a85ef763 100644 --- a/docs/configuration/php-sessions.md +++ b/docs/configuration/php-sessions.md @@ -1,81 +1,3 @@ # PHP Session Configuration -This document explains how to configure PHP sessions in the docker-mailserver project, including both Redis and file-based session storage options. - -## Overview - -The web service supports configurable PHP session storage through environment variables. By default, sessions are stored in Redis, but you can easily switch to file-based storage or other session handlers. - -## Environment Variables - -| Variable | Default | Description | -| -------------------------- | ---------------------------------------------------------- | -------------------- | -| `PHP_SESSION_SAVE_HANDLER` | `redis` | Session save handler | -| `PHP_SESSION_SAVE_PATH` | `tcp://${REDIS_HOST}:${REDIS_PORT}?auth=${REDIS_PASSWORD}` | Session save path | - -## Session Storage Options - -### Redis Sessions (Default) - -Redis is the default session storage mechanism, providing fast, scalable session management. - -**Configuration:** - -```bash -PHP_SESSION_SAVE_HANDLER=redis -PHP_SESSION_SAVE_PATH=tcp://${REDIS_HOST}:${REDIS_PORT}?auth=${REDIS_PASSWORD} -``` - -### File-Based Sessions - -Store sessions as files on the local filesystem. - -**Configuration:** - -```bash -PHP_SESSION_SAVE_HANDLER=files -PHP_SESSION_SAVE_PATH=/tmp/sessions -``` - -## Implementation Examples - -### Docker Compose Configuration - -**Redis Sessions (Default):** - -```yaml -services: - web: - environment: - - PHP_SESSION_SAVE_HANDLER=redis - - PHP_SESSION_SAVE_PATH=tcp://redis:6379?auth=${REDIS_PASSWORD} - depends_on: - - redis -``` - -**File-Based Sessions:** - -```yaml -services: - web: - environment: - - PHP_SESSION_SAVE_HANDLER=files - - PHP_SESSION_SAVE_PATH=/tmp/sessions - volumes: - - session_data:/tmp/sessions -``` - -## PHP Configuration - -The session configuration is applied through the PHP configuration file at: -`target/web/rootfs/etc/frankenphp/php.ini` - -```ini -session.save_handler = ${PHP_SESSION_SAVE_HANDLER} -session.save_path = "${PHP_SESSION_SAVE_PATH:-tcp://${REDIS_HOST}:${REDIS_PORT}?auth=${REDIS_PASSWORD}}" -``` - -This configuration: - -- Uses the `PHP_SESSION_SAVE_HANDLER` environment variable -- Falls back to Redis configuration if `PHP_SESSION_SAVE_PATH` is not set +See **[How to configure PHP sessions](../how-to/configure-php-sessions.md)** for Redis and file-based session configuration. For variable reference, see [Environment variables reference](../reference/environment-variables.md) (PHP Sessions section). diff --git a/docs/configuration/relayhost.md b/docs/configuration/relayhost.md index a392386b..f92013d6 100644 --- a/docs/configuration/relayhost.md +++ b/docs/configuration/relayhost.md @@ -1,145 +1,3 @@ # Relayhost Configuration -## Overview - -The `docker-mailserver` MTA service can be configured to relay outgoing emails through another SMTP server. This is useful when you need to send emails through a third-party SMTP provider, corporate mail server, or when your hosting provider blocks direct SMTP connections. - -## Configuration - -### Environment Variables - -Configure the following environment variables in your `.env` file: - -```bash -# Relayhost Configuration -RELAYHOST=[mailpit]:1025 -RELAY_PASSWD_FILE=/etc/postfix/sasl_passwd_ext -``` - -### Variable Descriptions - -- **RELAYHOST**: The SMTP server to relay emails through, in the format `[hostname]:port` -- **RELAY_PASSWD_FILE**: Path to the credentials file containing authentication details - -## Credentials File - -### File Format - -Create a credentials file with the following format: - -```text -hostname username:password -``` - -### Example Credentials File - -For a relayhost at `mailpit` on port `1025` with user `user1` and password `password1`: - -```text -mailpit user1:password1 -``` - -### File Location - -The credentials file must be mounted to `/etc/postfix/sasl_passwd_ext` in the MTA container. - -## Docker Compose Configuration - -### Step 1: Create Credentials File - -Create your credentials file locally (e.g., `sasl_passwd`): - -```bash -# Create credentials file -echo "mailpit user1:password1" > sasl_passwd - -# Set secure permissions -chmod 600 sasl_passwd -``` - -### Step 2: Mount Credentials File - -Edit `deploy/compose/mta.yaml` to mount the credentials file: - -```yaml -services: - mta: - image: jeboehm/mailserver-mta:latest - build: - context: ../../target/mta - cache_from: - - type=registry,ref=ghcr.io/jeboehm/mailserver-mta:buildcache - restart: on-failure:5 - env_file: ../../.env - volumes: - - data-tls:/etc/postfix/tls:ro - # Mount your credentials file - - ./sasl_passwd:/etc/postfix/sasl_passwd_ext:ro - # For using external certificates uncomment the following lines - # and change the path on the left side of the colon. - # - /home/user/certs/mail.example.com.crt:/etc/postfix/tls.crt:ro - # - /home/user/certs/mail.example.com.key:/etc/postfix/tls.key:ro -``` - -### Step 3: Update Environment Variables - -Ensure your `.env` file contains: - -```bash -RELAYHOST=[mailpit]:1025 -RELAY_PASSWD_FILE=/etc/postfix/sasl_passwd_ext -``` - -### Step 4: Restart MTA Service - -```bash -# Restart the MTA service to apply changes -docker-compose up -d mta - -# Or using the production script -bin/production.sh up -d mta -``` - -## Common Relayhost Examples - -### Gmail SMTP - -```bash -# Environment variables -RELAYHOST=[smtp.gmail.com]:587 -RELAY_PASSWD_FILE=/etc/postfix/sasl_passwd_ext - -# Credentials file content -smtp.gmail.com your-email@gmail.com:your-app-password -``` - -### Office 365 - -```bash -# Environment variables -RELAYHOST=[smtp.office365.com]:587 -RELAY_PASSWD_FILE=/etc/postfix/sasl_passwd_ext - -# Credentials file content -smtp.office365.com your-email@yourdomain.com:your-password -``` - -## Verification - -### Test Email Sending - -1. **Send a test email** through the webmail interface -2. **Check MTA logs** for successful relay: - - ```bash - # Docker Compose - bin/production.sh logs mta - - # Kubernetes - kubectl logs statefulset/mta -n mail - ``` - -3. **Look for successful relay messages** in the logs: - ```text - postfix/smtp[1234]: 1A2B3C4D5E: to=, relay=mailpit[127.0.0.1]:1025, delay=0.1, delays=0.05/0.01/0.01/0.03, dsn=2.0.0, status=sent (250 2.0.0 Ok: queued as 1A2B3C4D5E) - ``` +See **[How to configure a relay host](../how-to/configure-relayhost.md)** for step-by-step configuration. For variable reference, see [Environment variables reference](../reference/environment-variables.md) (Relay section). diff --git a/docs/configuration/reverse-proxy.md b/docs/configuration/reverse-proxy.md index ba655dee..bf0dbcca 100644 --- a/docs/configuration/reverse-proxy.md +++ b/docs/configuration/reverse-proxy.md @@ -1,176 +1,3 @@ # Reverse Proxy Configuration -This document describes how to configure docker-mailserver to work behind a reverse proxy, specifically using Traefik as an example. The configuration uses environment variables to enable proxy protocol support and configure trusted proxy networks. - -## Overview - -When deploying docker-mailserver behind a reverse proxy, you need to: - -1. Configure the mail server to accept connections from the proxy -2. Enable PROXY protocol support to preserve client IP addresses -3. Set up the reverse proxy to route traffic to the appropriate mail services - -## Environment Variables - -The following environment variables control reverse proxy behavior: - -### Proxy Protocol Support - -| Variable | Default | Description | -| -------------------- | ------- | ---------------------------------------------------------- | -| `MDA_UPSTREAM_PROXY` | `false` | Enable PROXY protocol for MDA (Dovecot) IMAP/POP3 services | -| `MTA_UPSTREAM_PROXY` | `false` | Enable PROXY protocol for MTA (Postfix) SMTP services | - -### Trusted Proxy Networks - -| Variable | Default | Description | -| ----------------- | ------- | --------------------------------------------------------------- | -| `TRUSTED_PROXIES` | - | Comma-separated list of trusted proxy IP ranges (CIDR notation) | - -### Service Address Configuration - -**Important**: When using a reverse proxy, you must configure the internal service addresses to point to the reverse proxy's internal service ports, not directly to the mail server services. This ensures proper traffic routing through the proxy. - -| Variable | Description | -| ----------------------------- | ---------------------------------------------------------- | -| `MDA_IMAP_ADDRESS` | Internal IMAP service address (points to proxy) | -| `MDA_IMAPS_ADDRESS` | Internal IMAPS service address (points to proxy) | -| `MDA_POP3_ADDRESS` | Internal POP3 service address (points to proxy) | -| `MDA_POP3S_ADDRESS` | Internal POP3S service address (points to proxy) | -| `MTA_SMTP_ADDRESS` | Internal SMTP service address (points to proxy) | -| `MTA_SMTP_SUBMISSION_ADDRESS` | Internal SMTP submission service address (points to proxy) | - -The addresses should reference the reverse proxy's internal service name and the specific port configured for each mail protocol. This allows the mail server to route internal traffic through the proxy, maintaining consistent behavior and enabling proper PROXY protocol handling. - -## Example Configuration - -Here's a complete example configuration for use with Traefik: - -```bash -# Enable PROXY protocol support -MDA_UPSTREAM_PROXY=true -MTA_UPSTREAM_PROXY=true - -# Configure trusted proxy networks -TRUSTED_PROXIES=10.0.0.0/8 - -# Configure internal service addresses to point to Traefik's internal service -# These addresses route through the proxy, not directly to mail services -MDA_IMAP_ADDRESS=traefik-internal:33143 -MDA_IMAPS_ADDRESS=traefik-internal:33993 -MDA_POP3_ADDRESS=traefik-internal:33110 -MDA_POP3S_ADDRESS=traefik-internal:33995 -MTA_SMTP_ADDRESS=traefik-internal:3325 -MTA_SMTP_SUBMISSION_ADDRESS=traefik-internal:33587 -``` - -## Traefik Configuration - -### Using Kustomize - -To deploy Traefik resources with your mail server, include the Traefik ingress configuration in your Kustomize setup: - -```yaml -# kustomization.yaml -apiVersion: kustomize.config.k8s.io/v1beta1 -kind: Kustomization - -resources: - - deploy/kustomize/ingress/traefik - # ... other resources -``` - -This will include the following Traefik resources: - -- **MDA IngressRoutes**: Routes for IMAP (143), IMAPS (993), POP3 (110), and POP3S (995) -- **MTA IngressRoutes**: Routes for SMTP (25) and SMTP submission (587) - -### Traefik Entry Points - -The Traefik configuration defines the following entry points: - -```yaml -ports: - smtp: - port: 3325 - expose: - default: true - internal: true - submission: - port: 33587 - expose: - default: true - internal: true - imap: - port: 33143 - expose: - default: true - internal: true - imaps: - port: 33993 - expose: - default: true - internal: true - pop3: - port: 33110 - expose: - default: true - internal: true - pop3s: - port: 33995 - expose: - default: true - internal: true -``` - -### IngressRoute Configuration - -The IngressRoutes are configured with: - -- **HostSNI matching**: `HostSNI(*)` to accept all hostnames -- **Native load balancing**: `nativeLB: true` for optimal performance -- **PROXY protocol**: Version 2 support for client IP preservation - -Example IngressRoute for IMAP: - -```yaml -apiVersion: traefik.io/v1alpha1 -kind: IngressRouteTCP -metadata: - name: ingress-imap -spec: - entryPoints: - - imap - routes: - - match: HostSNI(`*`) - services: - - name: mda - port: imap - nativeLB: true - proxyProtocol: - version: 2 -``` - -## Traffic Flow - -1. **Client Connection**: Client connects to Traefik on standard mail ports (25, 587, 143, 993, 110, 995) -2. **Traefik Routing**: Traefik routes traffic to internal mail services using IngressRoutes -3. **PROXY Protocol**: Traefik sends PROXY protocol headers to preserve original client IP -4. **Mail Server**: Mail server processes the connection with original client IP information - -## Verification - -To verify the Traefik configuration is working correctly: - -```bash -# Check Traefik pod logs -kubectl logs -l app.kubernetes.io/name=traefik - -# Verify IngressRoutes are created -kubectl get ingressroutetcp - -# Test mail connectivity -telnet your-domain.com 25 -telnet your-domain.com 587 -telnet your-domain.com 143 -``` +See **[How to configure a reverse proxy (Traefik)](../how-to/configure-reverse-proxy.md)** for PROXY protocol and internal address configuration. For variable reference, see [Environment variables reference](../reference/environment-variables.md) (Proxy Protocol and Service Addresses). diff --git a/docs/configuration/roundcube.md b/docs/configuration/roundcube.md index d9baaa4c..6dc4df01 100644 --- a/docs/configuration/roundcube.md +++ b/docs/configuration/roundcube.md @@ -1,93 +1,3 @@ # Roundcube Configuration -## Overview - -The `docker-mailserver`'s web service includes Roundcube webmail interface along with the admin interface. The Dockerfile for the web service supports custom Roundcube plugin installation through build arguments. - -## Plugin Installation - -### Build Argument: RC_PLUGINS - -The web service Dockerfile accepts the `RC_PLUGINS` build argument, which allows you to specify Roundcube plugins that should be installed during the image build process. - -**Format**: Space-separated list of plugin names in the format `vendor/plugin-name` - -**Example plugins**: - -- `johndoh/contextmenu` - Enhanced context menu functionality -- `jfcherng-roundcube/show-folder-size` - Display folder sizes -- `kolab/calendar` - Calendar integration - -### Configuration in web.yaml - -The `RC_PLUGINS` argument is configured in the `deploy/compose/web.yaml` file: - -```yaml -services: - web: - image: jeboehm/mailserver-web:latest - build: - context: ../../target/web - args: - RC_PLUGINS: "johndoh/contextmenu jfcherng-roundcube/show-folder-size" -``` - -### Adding Custom Plugins - -To add or modify Roundcube plugins: - -1. **Edit the web.yaml file**: - - ```yaml - services: - web: - build: - context: ../../target/web - args: - RC_PLUGINS: "your-plugin/name another-plugin/name" - ``` - -2. **Rebuild the web service**: - - ```bash - docker-compose build web - ``` - -3. **Restart the service**: - ```bash - docker-compose up -d web - ``` - -### Example: Adding Calendar Plugin - -```yaml -# In deploy/compose/web.yaml -services: - web: - build: - context: ../../target/web - args: - RC_PLUGINS: "johndoh/contextmenu jfcherng-roundcube/show-folder-size kolab/calendar" -``` - -Then rebuild: - -```bash -docker-compose build web && docker-compose up -d web -``` - -## Plugin Sources - -Plugins are typically installed from: - -- [Packagist.org](https://packagist.org/?type=roundcube-plugin) - Official Roundcube plugin repository -- GitHub repositories -- Custom plugin sources - -## Notes - -- Plugin names must follow the `vendor/plugin-name` format -- Multiple plugins are space-separated -- Plugins are installed during the Docker build process -- Changes to `RC_PLUGINS` require rebuilding the image -- Ensure plugins are compatible with the Roundcube version used in the image +See **[How to add Roundcube plugins](../how-to/configure-roundcube-plugins.md)** for installing plugins via the `RC_PLUGINS` build argument. diff --git a/docs/configuration/tls.md b/docs/configuration/tls.md index d6028afd..aea7ab2c 100644 --- a/docs/configuration/tls.md +++ b/docs/configuration/tls.md @@ -1,124 +1,3 @@ # TLS Certificate Configuration -## Overview - -The `docker-mailserver` uses TLS certificates for secure email communication. The system supports both internally generated certificates and external certificates (such as those from Let's Encrypt). - -## Certificate Locations - -### MDA Service (Dovecot) - -The Mail Delivery Agent expects TLS certificates at: - -- **Certificate**: `/etc/dovecot/tls/tls.crt` -- **Private Key**: `/etc/dovecot/tls/tls.key` - -### MTA Service (Postfix) - -The Mail Transfer Agent expects TLS certificates at: - -- **Certificate**: `/etc/postfix/tls/tls.crt` -- **Private Key**: `/etc/postfix/tls/tls.key` - -## Default Configuration - -By default, the services use a shared `data-tls` volume that contains internally generated certificates: - -```yaml -# In deploy/compose/mda.yaml -volumes: - - data-tls:/etc/dovecot/tls:ro - -# In deploy/compose/mta.yaml -volumes: - - data-tls:/etc/postfix/tls:ro -``` - -## Using External Certificates - -### Let's Encrypt Integration - -To use certificates from Let's Encrypt or other external sources, you need to mount the certificate files directly into the containers. - -#### Step 1: Modify mda.yaml - -Edit `deploy/compose/mda.yaml` and replace the `data-tls` volume with direct file mounts: - -```yaml -services: - mda: - volumes: - - data-mail:/srv/vmail - # Remove this line: - # - data-tls:/etc/dovecot/tls:ro - # Add these lines instead: - - /path/to/your/certificate.crt:/etc/dovecot/tls/tls.crt:ro - - /path/to/your/private.key:/etc/dovecot/tls/tls.key:ro -``` - -#### Step 2: Modify mta.yaml - -Edit `deploy/compose/mta.yaml` and replace the `data-tls` volume with direct file mounts: - -```yaml -services: - mta: - volumes: - # Remove this line: - # - data-tls:/etc/postfix/tls:ro - # Add these lines instead: - - /path/to/your/certificate.crt:/etc/postfix/tls/tls.crt:ro - - /path/to/your/private.key:/etc/postfix/tls/tls.key:ro -``` - -#### Step 3: Remove SSL Service - -Since you're using external certificates, you can remove the SSL service from your deployment: - -1. **For Docker Compose**: Remove the `ssl` service from your `docker-compose.yml` -2. **For Kubernetes**: Remove the SSL-related resources from your kustomization - -### Example: Let's Encrypt Certificates - -If you have Let's Encrypt certificates in `/etc/letsencrypt/live/yourdomain.com/`: - -```yaml -# In deploy/compose/mda.yaml -services: - mda: - volumes: - - data-mail:/srv/vmail - - /etc/letsencrypt/live/yourdomain.com/fullchain.pem:/etc/dovecot/tls/tls.crt:ro - - /etc/letsencrypt/live/yourdomain.com/privkey.pem:/etc/dovecot/tls/tls.key:ro - -# In deploy/compose/mta.yaml -services: - mta: - volumes: - - /etc/letsencrypt/live/yourdomain.com/fullchain.pem:/etc/postfix/tls/tls.crt:ro - - /etc/letsencrypt/live/yourdomain.com/privkey.pem:/etc/postfix/tls/tls.key:ro -``` - -## Certificate Requirements - -### File Permissions - -Ensure your certificate files have appropriate permissions: - -- **Certificate files**: Readable by the container user (typically `root` or the service user) -- **Private key files**: Secure permissions (e.g., `600` or `644`) - -### Certificate Format - -- **Certificate**: PEM format (`.crt`, `.pem`, or `.cert` extensions) -- **Private Key**: PEM format (`.key` or `.pem` extensions) -- **Chain**: Use `fullchain.pem` for Let's Encrypt (includes intermediate certificates) - -### Logs - -Check service logs for TLS-related errors: - -```bash -bin/production.sh logs mda -bin/production.sh logs mta -``` +See **[How to configure TLS certificates](../how-to/configure-tls.md)** for using external certificates (e.g. Let's Encrypt) with the MTA and MDA. diff --git a/docs/development/architecture.md b/docs/development/architecture.md index f2d341ef..8b3a3648 100644 --- a/docs/development/architecture.md +++ b/docs/development/architecture.md @@ -1,68 +1,4 @@ # Service Architecture -`docker-mailserver` consists of several microservices: - -- **MTA (Mail Transfer Agent)** - Postfix for SMTP -- **MDA (Mail Delivery Agent)** - Dovecot for IMAP/POP3 -- **Web** - Admin interface and Roundcube webmail -- **Filter** - RSpamd for spam filtering -- **SSL** - Certificate generation and management -- **Database** - MySQL for user and configuration data -- **Redis** - Caching and session storage -- **Unbound** - DNS resolver for the filter service -- **Fetchmail** - External mail retrieval (optional) - -## Persistent Volumes - -The project uses several persistent volumes to ensure data persistence across container restarts and updates. These volumes are defined in the main `docker-compose.yml` file and mounted into specific services: - -### Volume Definitions - -```yaml -volumes: - data-db: # MySQL database storage - data-mail: # User mailboxes and email data - data-tls: # TLS certificates and keys - data-filter: # RSpamd filter data and statistics - data-redis: # Redis cache and session data - data-spool: # Postfix mail queue and spool directory -``` - -### Volume Mounts by Service - -#### Database Service (`db`) - -- **`data-db:/var/lib/mysql`** - Stores MySQL database files, user accounts, aliases, and configuration data - -#### Mail Transfer Agent (`mta`) - -- **`data-tls:/etc/postfix/tls:ro`** - Read-only access to TLS certificates for SMTP encryption -- **`data-spool:/var/spool/postfix`** - Postfix mail queue and spool directory for message processing - -#### Mail Delivery Agent (`mda`) - -- **`data-mail:/srv/vmail`** - User mailboxes, email storage, and maildir structure -- **`data-tls:/etc/dovecot/tls:ro`** - Read-only access to TLS certificates for IMAP/POP3 encryption - -#### Filter Service (`filter`) - -- **`data-filter:/var/lib/rspamd`** - RSpamd configuration, statistics, and learning data - -#### Redis Service (`redis`) - -- **`data-redis:/data`** - Redis database files for caching and session storage - -#### SSL Service (`ssl`) - -- **`data-tls:/media/tls:rw`** - Read-write access for TLS certificate generation and management - -### Volume Purpose and Data Persistence - -- **`data-db`**: Critical for maintaining user accounts, passwords, and mail server configuration -- **`data-mail`**: Essential for preserving all user emails and mailbox structures -- **`data-tls`**: Required for maintaining SSL/TLS certificates and encryption keys -- **`data-filter`**: Important for spam filter learning and statistics accumulation -- **`data-redis`**: Used for session management and temporary data caching -- **`data-spool`**: Stores Postfix mail queue and spool data, ensuring message processing continuity across restarts - -These volumes ensure that your mail server data survives container updates, restarts, and even complete system reboots, making the deployment production-ready and reliable. +- **[Service architecture reference](../reference/service-architecture.md)** — List of services and persistent volumes +- **[About the service architecture](../explanation/architecture.md)** — How the services work together and why the system is structured this way diff --git a/docs/explanation/architecture.md b/docs/explanation/architecture.md new file mode 100644 index 00000000..9d75c96b --- /dev/null +++ b/docs/explanation/architecture.md @@ -0,0 +1,29 @@ +# About the Service Architecture + +docker-mailserver is built from several services that handle different parts of mail delivery and management. Understanding how they fit together helps when configuring, troubleshooting, or extending the system. + +## Why multiple services + +Email delivery involves distinct tasks: accepting and relaying mail (MTA), storing and serving mailboxes (MDA), filtering spam (filter), and providing a web UI (web). Splitting these into separate services lets each use the right technology (Postfix, Dovecot, Rspamd, PHP) and scale or replace components independently. + +## How the services work together + +- **MTA (Postfix)** receives mail on port 25 and accepts submissions on port 587. It looks up recipients in the database, applies relay and policy, and hands mail to the filter for scanning. After filtering, it delivers to the MDA via LMTP or stores in the queue for later delivery. + +- **MDA (Dovecot)** stores mail in maildirs and serves it over IMAP and POP3. It authenticates users against the database and enforces quotas. The web interface uses Dovecot for authentication and mailbox access; the filter may use Dovecot for scanning. + +- **Filter (Rspamd)** scans messages for spam and viruses, applies DKIM signing, and can learn from user actions (e.g. moving mail to junk). It runs as a milter so the MTA can pass messages through it before delivery. + +- **Web** runs the admin UI (mailserver-admin) and Roundcube webmail. It talks to the database for users, domains, aliases, and DKIM, and to Dovecot for authentication and mailbox operations. Observability features pull data from Rspamd and Dovecot (e.g. Doveadm HTTP API). + +- **Database (MySQL)** holds users, domains, aliases, DKIM config, and application data. All services that need this data connect to the same database. + +- **Redis** is used for sessions and caching so the web service can run across multiple instances without losing session state. + +- **Unbound** (when used) provides DNS resolution for the filter so RBL and other DNS-based checks work correctly. + +- **SSL** (optional) generates and manages internal TLS certificates. In production you typically replace these with certificates from a CA (e.g. Let’s Encrypt). + +- **Fetchmail** (optional) periodically connects to external mail servers (POP3/IMAP) and delivers retrieved mail into local mailboxes. + +For a concise list of services and volumes, see [Service architecture reference](../reference/service-architecture.md). diff --git a/docs/explanation/dns-and-email.md b/docs/explanation/dns-and-email.md new file mode 100644 index 00000000..4da1d15d --- /dev/null +++ b/docs/explanation/dns-and-email.md @@ -0,0 +1,23 @@ +# About DNS and Email Delivery + +DNS records tell the rest of the internet how to reach your mailserver and whether to trust mail from it. Correct DNS is required for reliable delivery and for authentication (SPF, DKIM, DMARC). + +## Why MX matters + +The MX (Mail Exchange) record says which host accepts mail for your domain. When someone sends to `user@example.com`, the sender’s server looks up MX for `example.com`. Without a correct MX record pointing to your mailserver, other servers will not deliver mail to you or may deliver to the wrong host. + +## Why SPF matters + +SPF (Sender Policy Framework) lists which servers are allowed to send mail for your domain. Receiving servers check SPF to reduce spoofing: if mail claims to be from your domain but comes from an IP not in your SPF record, it can be marked as suspicious or rejected. Without SPF, your domain is easier to spoof and more likely to be treated as untrusted. + +## Why DKIM matters + +DKIM (DomainKeys Identified Mail) lets receiving servers verify that mail was signed by a server that holds the private key for your domain. The public key is in DNS. Signing all outgoing mail and publishing the key improves deliverability and helps receivers distinguish legitimate mail from forgeries. Many providers and filters use DKIM as a signal for reputation and filtering. + +## Why DMARC matters + +DMARC (Domain-based Message Authentication, Reporting and Conformance) tells receivers what to do with mail that fails SPF or DKIM (quarantine, reject) and where to send reports. It ties SPF and DKIM together and gives you visibility into authentication failures. Starting with a monitoring policy (`p=none`) and then tightening to quarantine or reject is a common approach. + +## How they fit together + +MX gets mail to your server. SPF and DKIM help other servers trust mail from your server and reject or down-rank spoofed mail. DMARC defines policy and reporting so you can improve authentication over time. For record types and formats, see [DNS records reference](../reference/dns-records.md). For step-by-step configuration, see [How to configure DNS for your domain](../how-to/configure-dns.md). diff --git a/docs/explanation/observability.md b/docs/explanation/observability.md new file mode 100644 index 00000000..9705b5ce --- /dev/null +++ b/docs/explanation/observability.md @@ -0,0 +1,29 @@ +# About Observability + +Observability is the ability to infer a system’s internal state from its external outputs. For a mailserver, that means using metrics and dashboards to see how mail and authentication are behaving without logging into each component. + +mailserver-admin provides observability by aggregating data from the Rspamd filter and the Dovecot MDA and presenting it in web-based dashboards. This gives operators a single place to check service health, message throughput, spam filtering results, and authentication patterns. + +## What the dashboards show + +- **Rspamd Statistics:** Health of the Rspamd controller, message counts (scanned, spam, ham, etc.), throughput over time, action distribution (reject, greylist, clean, etc.), and configuration details such as thresholds and top symbols. This helps you see how much mail is being processed and how the filter is behaving. + +- **Dovecot Statistics:** Connection to the Dovecot API (Doveadm HTTP), authentication successes and failures, index operations, authentication rate over time, and mail delivery rate over time. This helps you spot authentication issues or unusual delivery patterns. + +Data is collected from consecutive samples; rates are computed as deltas between measurements. The dashboards support different time ranges (day, week, month, year) for throughput and rate charts. + +## Why it matters + +With observability you can: + +- Confirm that Rspamd and Dovecot are reachable and responding. +- See whether message volume or filter actions have changed. +- Identify spikes in authentication failures that might indicate abuse or misconfiguration. +- Correlate delivery rates with changes in configuration or infrastructure. + +For this to work, the web service must be able to reach the Rspamd controller and the Dovecot Doveadm HTTP API. The required environment variables (e.g. `MDA_DOVEADM_ADDRESS`, `DOVEADM_API_KEY`) are described in the [Upgrade changelog](../reference/upgrade-changelog.md) (v7.3) and [Environment variables reference](../reference/environment-variables.md). +Change at least `DOVEADM_API_KEY` from the default in production. + +![Rspamd Statistics](../images/admin/obs_rspamd.png) + +![Dovecot Statistics](../images/admin/obs_dovecot.png) diff --git a/docs/how-to/configure-dkim.md b/docs/how-to/configure-dkim.md new file mode 100644 index 00000000..c41f6c3c --- /dev/null +++ b/docs/how-to/configure-dkim.md @@ -0,0 +1,21 @@ +# How to Configure DKIM Signing + +DKIM (DomainKeys Identified Mail) signs outgoing mail so receiving servers can verify authenticity. Configure it per domain in the management interface. + +## Steps + +1. Log in to the management interface. +2. Open **DKIM** in the menu. +3. Select the domain. +4. Generate the private key (if not already done). +5. Add the displayed DNS TXT record to your domain’s DNS. See [DNS records reference](../reference/dns-records.md) for DKIM format. +6. In the management interface, verify the DNS record (e.g. via the DNS Validation Wizard). +7. Enable DKIM signing for the domain. + +![DKIM Edit](../images/admin/dkim_edit.png) + +After this, outgoing mail for that domain is signed with the private key. Receiving servers verify using the public key in DNS. + +## Implementation note + +Signing is done by the Rspamd DKIM module. Rspamd checks that the domain’s DKIM DNS record is present and valid before signing. For record format and verification, see [DNS records reference](../reference/dns-records.md). diff --git a/docs/how-to/configure-dns.md b/docs/how-to/configure-dns.md new file mode 100644 index 00000000..f130ce71 --- /dev/null +++ b/docs/how-to/configure-dns.md @@ -0,0 +1,34 @@ +# How to Configure DNS for Your Domain + +To receive and send mail reliably, configure DNS records for your domain. This guide gives practical steps; for record formats and options, see [DNS records reference](../reference/dns-records.md). + +## Steps + +### 1. Add MX record + +Create an MX record pointing to your mailserver hostname (the value of `MAILNAME`, e.g. `mail.example.com`). Use priority 10 (or another value; lower = higher priority if you have multiple MX records). + +### 2. Add A and AAAA records + +Create A (and optionally AAAA) records for the mailserver hostname so it resolves to your server’s IP(s). + +### 3. Add SPF record + +Add a TXT record at the domain root with your SPF policy, e.g. `v=spf1 mx a ~all`. Adjust mechanisms (e.g. `ip4:`, `ip6:`) to match your sending IPs. Use `~all` for testing and `-all` for production once stable. + +### 4. Add DKIM record + +Configure DKIM in the management interface (see [How to configure DKIM signing](configure-dkim.md)). The interface shows the TXT record to add; publish it at the indicated name (e.g. `default._domainkey.example.com`). + +### 5. Add DMARC record (recommended) + +Add a TXT record at `_dmarc` with a DMARC policy. Start with `p=none` and `rua=mailto:...` for monitoring; move to `p=quarantine` or `p=reject` after you are satisfied with authentication. + +## Verification + +- Use the [DNS Validation Wizard](validate-dns.md) in the management interface. +- Use `dig` or `nslookup` to check MX, A, AAAA, and TXT records. + +DNS changes can take from minutes up to 48 hours to propagate. If validation fails right after adding records, wait for propagation and check again. + +For record formats and examples, see [DNS records reference](../reference/dns-records.md). For context on why these records matter, see [DNS and email delivery](../explanation/dns-and-email.md). diff --git a/docs/how-to/configure-external-mysql.md b/docs/how-to/configure-external-mysql.md new file mode 100644 index 00000000..5f1767a9 --- /dev/null +++ b/docs/how-to/configure-external-mysql.md @@ -0,0 +1,54 @@ +# How to Use an External MySQL Database + +docker-mailserver can use an external MySQL (or compatible) database instead of the included database service. Use this for production, Kubernetes, or when reusing existing MySQL infrastructure. + +## Steps + +### 1. Create the database and user + +On the MySQL server: + +```sql +CREATE DATABASE mailserver CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +``` + +Create a user with access to that database and set a password. + +### 2. Import the schema + +Import the mailserver and webmail schema from the project: + +```bash +mysql -h your-mysql-host -u root -p mailserver < target/db/rootfs/docker-entrypoint-initdb.d/001_mailserver.sql +mysql -h your-mysql-host -u root -p mailserver < target/db/rootfs/docker-entrypoint-initdb.d/002_webmail.sql +``` + +Adjust host, user, and paths as needed. + +### 3. Configure environment variables + +In `.env`: + +```bash +MYSQL_HOST=your-mysql-host.example.com +MYSQL_DATABASE=mailserver +MYSQL_USER=mailserver_user +MYSQL_PASSWORD=your_secure_password +``` + +### 4. Remove or exclude the database service (Docker Compose) + +If using Docker Compose, remove or do not include the `db` service (e.g. comment out or omit `deploy/compose/db.yaml`). Remove `depends_on: db` from services that referenced it so they use the external host instead. + +### 5. Restart the web service + +Restart the web service so it connects to the external database and runs any migrations: + +- Docker: `bin/production.sh restart web` or `docker-compose restart web` +- Kubernetes: `kubectl rollout restart deployment/web -n mail` + +## Kubernetes + +Kustomize does not include a database service; you must provide an external MySQL (or compatible) database and set `MYSQL_*` in your ConfigMap/Secrets as above. + +For variable reference, see [Environment variables reference](../reference/environment-variables.md) (Database section). diff --git a/docs/how-to/configure-oauth2.md b/docs/how-to/configure-oauth2.md new file mode 100644 index 00000000..f89d7cfd --- /dev/null +++ b/docs/how-to/configure-oauth2.md @@ -0,0 +1,53 @@ +# How to Configure OAuth2 Login + +mailserver-admin can use OAuth2/OIDC for login. When enabled, users sign in via an external identity provider instead of (or in addition to) local credentials. OAuth2 is typically used to grant admin rights based on group membership. + +## Steps + +### 1. Create an OAuth2 client in your identity provider + +Create a client with: + +- **Redirect URI:** `https://your-domain/login/check-oauth` (use your actual domain) +- **Client ID** and **Client secret** for use in `.env` + +### 2. Set environment variables + +In `.env` (or the environment): + +```bash +OAUTH_ENABLED=true +OAUTH_CLIENT_ID=your-client-id +OAUTH_CLIENT_SECRET=your-client-secret +OAUTH_AUTHORIZATION_URL=https://id.example.com/authorize +OAUTH_ACCESS_TOKEN_URL=https://id.example.com/api/oidc/token +OAUTH_INFOS_URL=https://id.example.com/api/oidc/userinfo +OAUTH_BUTTON_TEXT="Login with OIDC" +OAUTH_ADMIN_GROUP=admin +OAUTH_PATHS_IDENTIFIER=sub +OAUTH_CREATE_USER=false +``` + +Adjust URLs, scopes, and button text to match your provider. + +### 3. Configure the user identifier + +`OAUTH_PATHS_IDENTIFIER` must point to a field in the provider’s userinfo that contains an email address that exists as a user in the mailserver (same domain). The field should be write-protected in the provider so users cannot change it. Do not use a normal “email” claim that users can edit. + +### 4. Optional: auto-create users + +Set `OAUTH_CREATE_USER=true` to create a mailserver user when someone logs in via OAuth2 and no matching user exists. Use only if your provider guarantees a stable, domain-valid email identifier. + +### 5. Restart the web service + +Restart the web container so the new variables are loaded. A login button for OAuth2 will appear on the login page. + +## Flow + +1. User clicks the OAuth2 login button and is redirected to the provider. +2. After authentication, the provider redirects back to `/login/check-oauth`. +3. The application reads userinfo and takes the identifier from `OAUTH_PATHS_IDENTIFIER`. +4. If the identifier matches an existing user, that user is logged in. If `OAUTH_ADMIN_GROUP` is set and the user is in that group, they get admin rights. +5. If there is no match and `OAUTH_CREATE_USER=true`, a new user is created; otherwise login is denied. + +For all OAuth2 variables, see [mailserver-admin configuration reference](../reference/mailserver-admin-config.md). diff --git a/docs/how-to/configure-php-sessions.md b/docs/how-to/configure-php-sessions.md new file mode 100644 index 00000000..e9293914 --- /dev/null +++ b/docs/how-to/configure-php-sessions.md @@ -0,0 +1,34 @@ +# How to Configure PHP Sessions + +The web service stores PHP sessions in Redis by default. You can switch to file-based or another handler via environment variables. + +## Redis (default) + +No change needed if Redis is available. Default: + +```bash +PHP_SESSION_SAVE_HANDLER=redis +PHP_SESSION_SAVE_PATH=tcp://${REDIS_HOST}:${REDIS_PORT}?auth=${REDIS_PASSWORD} +``` + +## File-based sessions + +To use the filesystem instead: + +1. Set in `.env` (or environment): + +```bash +PHP_SESSION_SAVE_HANDLER=files +PHP_SESSION_SAVE_PATH=/tmp/sessions +``` + +2. Mount a volume for the session directory so it persists and is writable: + +```yaml +volumes: + - session_data:/tmp/sessions +``` + +3. Restart the web service. + +For variable reference, see [Environment variables reference](../reference/environment-variables.md) (PHP Sessions). diff --git a/docs/how-to/configure-relayhost.md b/docs/how-to/configure-relayhost.md new file mode 100644 index 00000000..4c3b8afa --- /dev/null +++ b/docs/how-to/configure-relayhost.md @@ -0,0 +1,84 @@ +# How to Configure a Relay Host + +To send outgoing mail through another SMTP server (e.g. a provider or corporate server), configure a relay host. + +## Steps + +### 1. Create credentials file + +Create a file (e.g. `sasl_passwd`) with: + +```text +hostname username:password +``` + +Example for relay at `mailpit` on port 1025: + +```text +mailpit user1:password1 +``` + +Set secure permissions: + +```bash +chmod 600 sasl_passwd +``` + +### 2. Mount the file into the MTA container + +In `deploy/compose/mta.yaml` (or your compose override), add a volume for the credentials file: + +```yaml +volumes: + - data-tls:/etc/postfix/tls:ro + - ./sasl_passwd:/etc/postfix/sasl_passwd_ext:ro +``` + +Use the path where the MTA expects it (e.g. `/etc/postfix/sasl_passwd_ext`). + +### 3. Set environment variables + +In `.env`: + +```bash +RELAYHOST=[hostname]:port +RELAY_PASSWD_FILE=/etc/postfix/sasl_passwd_ext +``` + +Example for Gmail: + +```bash +RELAYHOST=[smtp.gmail.com]:587 +RELAY_PASSWD_FILE=/etc/postfix/sasl_passwd_ext +``` + +Credentials file content for Gmail (use an app password): + +```text +smtp.gmail.com your-email@gmail.com:your-app-password +``` + +Example for Office 365: + +```bash +RELAYHOST=[smtp.office365.com]:587 +RELAY_PASSWD_FILE=/etc/postfix/sasl_passwd_ext +``` + +```text +smtp.office365.com your-email@yourdomain.com:your-password +``` + +### 4. Restart the MTA + +```bash +bin/production.sh up -d mta +``` + +(or `docker-compose up -d mta`). + +## Verification + +Send a test message via webmail and check MTA logs for successful relay (e.g. `status=sent`). + +For reference, see [Environment variables reference](../reference/environment-variables.md) (Relay section). diff --git a/docs/how-to/configure-reverse-proxy.md b/docs/how-to/configure-reverse-proxy.md new file mode 100644 index 00000000..d5d285be --- /dev/null +++ b/docs/how-to/configure-reverse-proxy.md @@ -0,0 +1,59 @@ +# How to Configure a Reverse Proxy (Traefik) + +To run docker-mailserver behind a reverse proxy (e.g. Traefik) and preserve client IPs, enable PROXY protocol and point internal addresses at the proxy. + +## Steps + +### 1. Enable PROXY protocol + +In `.env`: + +```bash +MDA_UPSTREAM_PROXY=true +MTA_UPSTREAM_PROXY=true +``` + +`MDA_UPSTREAM_PROXY` applies to IMAP, IMAPS, POP3, POP3S. `MTA_UPSTREAM_PROXY` applies to SMTP and submission (587). + +### 2. Set trusted proxies (if needed) + +If the web interface is behind a proxy, set trusted proxy IPs: + +```bash +TRUSTED_PROXIES=10.0.0.0/8 +``` + +Use your proxy’s CIDR range(s). + +### 3. Point internal addresses at the proxy + +When traffic goes through the proxy, configure internal service addresses to point at the proxy’s internal host/ports, not directly at MTA/MDA. Example for a Traefik internal service: + +```bash +MDA_IMAP_ADDRESS=traefik-internal:33143 +MDA_IMAPS_ADDRESS=traefik-internal:33993 +MDA_POP3_ADDRESS=traefik-internal:33110 +MDA_POP3S_ADDRESS=traefik-internal:33995 +MTA_SMTP_ADDRESS=traefik-internal:3325 +MTA_SMTP_SUBMISSION_ADDRESS=traefik-internal:33587 +``` + +Adjust host and port names to match your Traefik configuration. + +### 4. Configure Traefik (Kubernetes) + +To use the provided Traefik ingress with Kustomize, add: + +```yaml +resources: + - deploy/kustomize/ingress/traefik +``` + +This adds IngressRoutes for SMTP (25), submission (587), IMAP (143), IMAPS (993), POP3 (110), POP3S (995). Configure entry points and PROXY protocol (v2) on the Traefik side to match. + +## Verification + +- Check Traefik logs and IngressRoutes. +- Test connectivity to SMTP, submission, IMAP, and POP3 on the proxy’s public ports. + +For variable details, see [Environment variables reference](../reference/environment-variables.md) (Proxy Protocol and Service Addresses). For a Docker Compose example, see [Traefik reverse proxy example](https://github.com/jeboehm/docker-mailserver/tree/main/docs/example-configs/compose/traefik-reverse-proxy). diff --git a/docs/how-to/configure-roundcube-plugins.md b/docs/how-to/configure-roundcube-plugins.md new file mode 100644 index 00000000..7a0bdb4c --- /dev/null +++ b/docs/how-to/configure-roundcube-plugins.md @@ -0,0 +1,43 @@ +# How to Add Roundcube Plugins + +The web image supports installing Roundcube plugins at build time via the `RC_PLUGINS` build argument. + +## Steps + +### 1. Set RC_PLUGINS in the web build + +In `deploy/compose/web.yaml` (or your override), add or edit the build args: + +```yaml +services: + web: + build: + context: ../../target/web + args: + RC_PLUGINS: "vendor/plugin-name another-vendor/another-plugin" +``` + +Use a space-separated list of plugins in `vendor/plugin-name` form. Example: + +```yaml +RC_PLUGINS: "johndoh/contextmenu jfcherng-roundcube/show-folder-size kolab/calendar" +``` + +### 2. Rebuild and start the web service + +```bash +docker-compose build web +docker-compose up -d web +``` + +(or `bin/production.sh` if you use that). Changes to `RC_PLUGINS` require a rebuild. + +## Plugin sources + +Plugins are typically installed from Packagist ([roundcube-plugin](https://packagist.org/?type=roundcube-plugin)), GitHub, or other Composer-compatible sources. Ensure plugins match the Roundcube version in the image. + +## Notes + +- Plugin names must be `vendor/plugin-name`. +- Multiple plugins are space-separated. +- Plugins are installed during the Docker build; changing `RC_PLUGINS` means rebuilding the image. diff --git a/docs/how-to/configure-tls.md b/docs/how-to/configure-tls.md new file mode 100644 index 00000000..962b9912 --- /dev/null +++ b/docs/how-to/configure-tls.md @@ -0,0 +1,64 @@ +# How to Configure TLS Certificates + +By default the mailserver uses a shared `data-tls` volume with internally generated certificates. To use external certificates (e.g. Let’s Encrypt), mount certificate and key files into the MTA and MDA containers. + +## Certificate locations + +- **MDA (Dovecot):** `/etc/dovecot/tls/tls.crt`, `/etc/dovecot/tls/tls.key` +- **MTA (Postfix):** `/etc/postfix/tls/tls.crt`, `/etc/postfix/tls/tls.key` + +## Steps (Docker Compose) + +### 1. Mount certificates in MDA + +In `deploy/compose/mda.yaml`, replace the `data-tls` volume with file mounts: + +```yaml +volumes: + - data-mail:/srv/vmail + - /path/to/certificate.crt:/etc/dovecot/tls/tls.crt:ro + - /path/to/private.key:/etc/dovecot/tls/tls.key:ro +``` + +### 2. Mount certificates in MTA + +In `deploy/compose/mta.yaml`, replace the `data-tls` volume with file mounts: + +```yaml +volumes: + - /path/to/certificate.crt:/etc/postfix/tls/tls.crt:ro + - /path/to/private.key:/etc/postfix/tls/tls.key:ro +``` + +### 3. Remove or disable the SSL service (optional) + +If you no longer need internal certificate generation, remove the SSL service from your compose stack so it does not overwrite or conflict with your certificates. + +### 4. Restart MTA and MDA + +```bash +bin/production.sh up -d mta mda +``` + +## Let’s Encrypt example + +If certificates are in `/etc/letsencrypt/live/yourdomain.com/`: + +```yaml +# mda +- /etc/letsencrypt/live/yourdomain.com/fullchain.pem:/etc/dovecot/tls/tls.crt:ro +- /etc/letsencrypt/live/yourdomain.com/privkey.pem:/etc/dovecot/tls/tls.key:ro + +# mta +- /etc/letsencrypt/live/yourdomain.com/fullchain.pem:/etc/postfix/tls/tls.crt:ro +- /etc/letsencrypt/live/yourdomain.com/privkey.pem:/etc/postfix/tls/tls.key:ro +``` + +Use `fullchain.pem` so the chain is complete. + +## Requirements + +- **Format:** PEM (`.crt`, `.pem`, `.key`). +- **Permissions:** Certificate and key readable by the container user; key with restricted permissions (e.g. 600). + +If TLS errors appear, check paths and permissions and review MTA/MDA logs: `bin/production.sh logs mta`, `bin/production.sh logs mda`. diff --git a/docs/how-to/install-docker.md b/docs/how-to/install-docker.md new file mode 100644 index 00000000..11cd7aa4 --- /dev/null +++ b/docs/how-to/install-docker.md @@ -0,0 +1,61 @@ +# How to Install with Docker Compose + +This guide describes how to install docker-mailserver using Docker Compose. + +## Prerequisites + +- Docker and Docker Compose +- Domain name with DNS configured +- Basic familiarity with email server administration + +## Steps + +### 1. Configure environment variables + +Copy the example environment file and edit `.env`: + +```bash +cp .env.dist .env +``` + +Set at least `MYSQL_PASSWORD`, `REDIS_PASSWORD`, `CONTROLLER_PASSWORD`, and `DOVEADM_API_KEY`. See [Environment variables reference](../reference/environment-variables.md). + +### 2. Pull images + +```bash +bin/production.sh pull +``` + +### 3. Start services + +```bash +bin/production.sh up -d --wait +``` + +### 4. Run setup wizard + +```bash +bin/production.sh run --rm web setup.sh +``` + +Follow the wizard to create your first account and admin user. + +### 5. Access the management interface + +- Management: `http://127.0.0.1:81/manager/` +- Webmail: `http://127.0.0.1:81/webmail/` + +## Post-installation + +- Configure DNS (MX, SPF, DKIM, DMARC). See [How to configure DNS](configure-dns.md) and [DNS records reference](../reference/dns-records.md). +- Replace self-signed TLS with valid certificates. See [How to configure TLS certificates](configure-tls.md). +- Configure firewall, backups, and monitoring as needed. + +## Troubleshooting + +- **Services not starting:** Check logs with `docker-compose logs` or `bin/production.sh logs`. +- **Database errors:** Verify `MYSQL_*` and database accessibility. +- **TLS issues:** Check certificate paths and permissions. +- **Port conflicts:** Ensure ports 25, 110, 143, 587, 993, 995, 81 are free. + +For port details, see [Ports reference](../reference/ports.md). diff --git a/docs/how-to/install-kubernetes.md b/docs/how-to/install-kubernetes.md new file mode 100644 index 00000000..9f88dfcc --- /dev/null +++ b/docs/how-to/install-kubernetes.md @@ -0,0 +1,70 @@ +# How to Install on Kubernetes + +This guide describes how to deploy docker-mailserver on Kubernetes with Kustomize. An external MySQL-compatible database is required; the kustomization does not provision a database. + +A full example is in [example-configs/kustomize/external-db-and-https-ingress](https://github.com/jeboehm/docker-mailserver/tree/main/docs/example-configs/kustomize/external-db-and-https-ingress). + +## Prerequisites + +- Kubernetes cluster with kubectl configured +- MySQL or Percona XtraDB (or compatible) database +- Domain and DNS (for ingress) + +## Steps + +### 1. Configure environment (ConfigMap) + +Copy `.env.dist` to `.env`, edit it, and create a ConfigMap from it. Create Kubernetes secrets for database credentials and other sensitive values. See [Environment variables reference](../reference/environment-variables.md). + +### 2. Create namespace + +```bash +kubectl create namespace mail +``` + +### 3. Generate TLS certificates (if not using cert-manager) + +```bash +bin/create-tls-certs.sh +``` + +### 4. Create TLS secret + +```bash +kubectl create -n mail secret tls tls-certs \ + --cert=config/tls/tls.crt \ + --key=config/tls/tls.key +``` + +### 5. Apply Kustomize manifests + +From the project root: + +```bash +kubectl apply -n mail -k . +``` + +### 6. Verify pods + +```bash +kubectl get pods -n mail +``` + +Wait until all pods are running and healthy. + +### 7. Run setup wizard + +```bash +kubectl exec -n mail -it deployment/web -c php-fpm -- setup.sh +``` + +Use the wizard to set initial configuration, create the first email address, and create an admin user. + +### 8. Access the management interface + +Use your configured ingress and the admin credentials from the wizard. + +## Post-installation + +- Configure DNS and TLS as for Docker. See [How to configure DNS](configure-dns.md) and [How to configure TLS certificates](configure-tls.md). +- Change `DOVEADM_API_KEY` from default if using observability (v7.3+). diff --git a/docs/how-to/ios-macos-profile.md b/docs/how-to/ios-macos-profile.md new file mode 100644 index 00000000..ae45f24f --- /dev/null +++ b/docs/how-to/ios-macos-profile.md @@ -0,0 +1,10 @@ +# How to Use the iOS / macOS Mail Profile + +The iOS / macOS Profile feature in mailserver-admin generates configuration profiles for Apple Mail. These profiles set up IMAP and SMTP so users do not have to enter server details manually. + +Use the feature from the management interface to generate and download the profile for the user’s device. For Apple’s documentation on configuring Mail: + +- [macOS](https://support.apple.com/en-us/guide/mac-help/mh35561/mac) +- [iOS](https://support.apple.com/en-us/102400) + +**Note:** Profile generation uses the same TLS certificate the mailserver presents to clients. To generate profiles, that certificate must be mounted into the web container (see [Upgrade changelog](../reference/upgrade-changelog.md) v7.1). diff --git a/docs/how-to/manage-aliases.md b/docs/how-to/manage-aliases.md new file mode 100644 index 00000000..9e6cfe2f --- /dev/null +++ b/docs/how-to/manage-aliases.md @@ -0,0 +1,40 @@ +# How to Manage Aliases + +Aliases forward incoming mail from one address to one or more destinations (local users or external addresses). **Admin** can manage all aliases; **Domain Admin** only aliases in their domain; **User** cannot manage aliases. + +## Add an alias + +1. Log in to the management interface. +2. Open **Alias** in the menu. +3. Click **Add Alias**. +4. Enter: + - **Source Address:** Local part + domain (e.g. `info@example.com`). Leave the local part empty for a catch-all alias. + - **Destination Address(es):** One or more addresses to forward to. +5. Save. + +The source must belong to an existing domain. Destinations can be local users or external addresses. You can create multiple aliases with the same source and different destinations to forward to several recipients. + +![Alias Create](../images/admin/alias_create.png) + +## Edit an alias + +1. Open **Alias** in the menu. +2. Select the alias. +3. Change source or destination(s). +4. Save. + +## Delete an alias + +1. Open **Alias** in the menu. +2. Select the alias. +3. Confirm deletion. + +Deleting an alias only removes the forwarding rule; it does not delete user accounts or mail. + +## Examples + +- Generic addresses: `info@example.com` → `team@example.com`; `support@example.com` → `support1@example.com, support2@example.com`. +- Personal: `john.doe@example.com` → `john.doe@gmail.com`. +- Distribution: `announcements@example.com` → `user1@example.com, user2@example.com`. + +For access control, see [User roles reference](../reference/user-roles.md). diff --git a/docs/how-to/manage-domains.md b/docs/how-to/manage-domains.md new file mode 100644 index 00000000..2412d7f4 --- /dev/null +++ b/docs/how-to/manage-domains.md @@ -0,0 +1,29 @@ +# How to Manage Domains + +Domains define the email namespaces your mailserver handles. All addresses must belong to a configured domain. Only users with **Admin** role can add, edit, or delete domains; Domain Admins and regular users cannot. + +## Add a domain + +1. Log in to the management interface. +2. Open **Domain** in the menu. +3. Click **Add Domain**. +4. Enter the domain name (e.g. `example.com`). +5. Save. + +The domain must be a valid domain name. It is available for users and aliases immediately. + +![Domain List](../images/admin/domain_list.png) + +## Delete a domain + +1. Open **Domain** in the menu. +2. Select the domain to delete. +3. Confirm the deletion. + +Deleting a domain removes all associated users, aliases, and DKIM configuration. This cannot be undone. Back up data before deleting. + +## Changing a domain name + +Changing the domain name is not supported. To use a different name, delete the domain and add a new one with the new name (and reconfigure users/aliases as needed). + +For access control details, see [User roles reference](../reference/user-roles.md). diff --git a/docs/how-to/manage-fetchmail.md b/docs/how-to/manage-fetchmail.md new file mode 100644 index 00000000..a753609b --- /dev/null +++ b/docs/how-to/manage-fetchmail.md @@ -0,0 +1,45 @@ +# How to Manage Fetchmail Accounts + +Fetchmail retrieves mail from external servers (POP3/IMAP) and delivers it to local mailboxes. **Admin** can manage all fetchmail accounts; **Domain Admin** only for users in their domain; **User** only their own accounts. + +## Add a fetchmail account + +1. Log in to the management interface. +2. Open **Fetchmail** in the menu. +3. Click **Add Fetchmail Account**. +4. Enter: + - **User:** Local user that will receive the mail + - **Server:** Hostname or IP of the external mail server + - **Port:** 110 (POP3), 143 (IMAP), 995 (POP3S), 993 (IMAPS) + - **Protocol:** POP3 or IMAP + - **Username** and **Password** for the external server + - **SSL** and **SSL Verify** as needed +5. Save. + +![Fetchmail Create](../images/admin/fetchmail_create.png) + +## Edit a fetchmail account + +1. Open **Fetchmail** in the menu. +2. Select the account. +3. Change server, port, protocol, credentials, or SSL settings. +4. Save. + +The “Last run log” field shows the last transaction with the external server and helps with troubleshooting. + +## Delete a fetchmail account + +1. Open **Fetchmail** in the menu. +2. Select the account. +3. Confirm deletion. + +Deleting stops retrieval; mail already delivered to the local mailbox is not removed. + +## Security + +- Use strong, unique passwords for external accounts. +- Enable SSL to protect credentials in transit. +- Review and disable unused fetchmail accounts. +- Ensure the mailserver can reach the external servers (firewall, DNS). + +Fetchmail runs on a schedule defined at the mailserver level. For access control, see [User roles reference](../reference/user-roles.md). diff --git a/docs/how-to/manage-users.md b/docs/how-to/manage-users.md new file mode 100644 index 00000000..1087d9c2 --- /dev/null +++ b/docs/how-to/manage-users.md @@ -0,0 +1,50 @@ +# How to Manage Users + +Users are email accounts that can send and receive mail through the mailserver. Access depends on role: **Admin** can manage all users; **Domain Admin** only users in their domain; **User** can only change their own settings. + +## Add a user + +1. Log in to the management interface. +2. Open **User** in the menu. +3. Click **Add User**. +4. Enter: + - **Email Address** (e.g. `user@example.com`) + - **Password** + - **Quota** (optional, MB) + - **Admin** / **Domain Admin** / **Enabled** / **Send Only** as needed +5. Save. + +The email must belong to an existing domain. The password must meet the configured policy. + +![User List](../images/admin/user_list.png) + +## Edit a user + +1. Open **User** in the menu. +2. Select the user. +3. Change password, quota, Admin, Domain Admin, Enabled, or Send Only as needed. +4. Save. + +![User Edit](../images/admin/user_edit.png) + +Changing the email address is not supported. To use a new address, create a new user and migrate data if needed. + +## Delete a user + +1. Open **User** in the menu. +2. Select the user. +3. Confirm deletion. + +Deleting a user removes the account and all mail. This cannot be undone. Back up important mail first. + +## User properties + +- **Email Address:** Local part + domain; must be valid (RFC 5322). +- **Password:** Stored hashed; policies enforced by the mailserver. +- **Quota:** Mailbox size limit in MB. When exceeded, incoming mail can be rejected and the user cannot send until space is freed; warnings are sent. +- **Send Only:** User can only send; no IMAP/POP3/webmail. +- **Admin / Domain Admin:** See [User roles reference](../reference/user-roles.md). + +Users access mail via IMAP (143 with TLS), POP3 (110 with TLS), SMTP submission (587 with TLS), and webmail. They log in with full email and password. + +For roles and permissions, see [User roles reference](../reference/user-roles.md). diff --git a/docs/how-to/upgrade.md b/docs/how-to/upgrade.md new file mode 100644 index 00000000..858d1611 --- /dev/null +++ b/docs/how-to/upgrade.md @@ -0,0 +1,11 @@ +# How to Upgrade + +When upgrading docker-mailserver: + +1. Review [Upgrade changelog](../reference/upgrade-changelog.md) for your target version. +2. Update deployment manifests in `deploy/compose` and `deploy/kustomize` for any volume or configuration changes. +3. Update `.env` for new or changed environment variables. +4. Pull new images (Docker) or update image tags (Kubernetes) and redeploy. +5. Run any version-specific steps from the changelog (e.g. changing `DOVEADM_API_KEY` for v7.3). + +For version-by-version notes, see [Upgrade changelog](../reference/upgrade-changelog.md). diff --git a/docs/how-to/validate-dns.md b/docs/how-to/validate-dns.md new file mode 100644 index 00000000..b52c1f05 --- /dev/null +++ b/docs/how-to/validate-dns.md @@ -0,0 +1,20 @@ +# How to Validate DNS with the Wizard + +The DNS Validation Wizard in the management interface checks that MX, SPF, DKIM, and DMARC records for your domain are correctly configured. + +## Steps + +1. Log in to the management interface. +2. Open the DNS Validation Wizard (e.g. from the dashboard or menu). +3. Select the domain to check. +4. Review the validation result for each record type. + +![DNS Validation Wizard](../images/admin/dns_wizard.png) + +The wizard shows which records are correct and which need attention. Fix any failures in your DNS and run the wizard again. + +## Propagation + +DNS updates can take from a few minutes up to 48 hours to propagate. If the wizard fails immediately after adding or changing records, wait for propagation and run the wizard again. + +For required record types and formats, see [DNS records reference](../reference/dns-records.md). For step-by-step DNS setup, see [How to configure DNS for your domain](configure-dns.md). diff --git a/docs/installation.md b/docs/installation.md index 1626ebe7..738a9c54 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,212 +1,10 @@ -# Installation Guide +# Installation -This guide covers installation procedures for `docker-mailserver` on Docker and Kubernetes platforms. +For a step-by-step learning path, see the **[Tutorial: Getting Started](tutorials/getting-started.md)**. -## Prerequisites +For task-oriented installation: -- Docker and Docker Compose (for Docker deployment) -- Kubernetes cluster with kubectl configured (for Kubernetes deployment) -- Domain name with DNS records configured -- Basic understanding of email server administration +- **[How to install with Docker Compose](how-to/install-docker.md)** — Docker installation +- **[How to install on Kubernetes](how-to/install-kubernetes.md)** — Kubernetes deployment -## Download - -### Option 1: Release Archive - -Download the latest release from the [Releases](https://github.com/jeboehm/docker-mailserver/releases) page and unpack the archive (`release-vX.X.X.tar.gz`). - -### Option 2: Source Code - -For advanced users, clone the repository from GitHub: - -```bash -git clone https://github.com/jeboehm/docker-mailserver.git -cd docker-mailserver -``` - -### Container Image Tags - -**Important:** Do not use the `latest` container image tag for production deployments. Always use a specific version tag instead. - -- ✅ Use: `jeboehm/mailserver-mta:6.3` -- ❌ Avoid: `jeboehm/mailserver-mta:latest` - -## Docker Installation - -### Step 1: Configure Environment Variables - -1. Copy the example environment file to create your configuration: - -```bash -cp .env.dist .env -``` - -2. Open `.env` in a text editor and configure the variables according to your needs. See [Environment Variables](configuration/environment-variables.md) for detailed descriptions of all available options. - -### Step 2: Download Container Images - -Pull the required Docker images: - -```bash -bin/production.sh pull -``` - -### Step 3: Start Services - -Start all services in detached mode and wait for them to be ready: - -```bash -bin/production.sh up -d --wait -``` - -This command will: - -- Start all required containers -- Wait for health checks to pass -- Ensure services are ready before continuing - -### Step 4: Access Services - -After a few seconds, the services will be available on the ports listed in the [Ports Overview](#ports-overview) section. - -### Step 5: Run Installation Wizard - -Execute the setup script to configure the mailserver and create your first account: - -```bash -bin/production.sh run --rm web setup.sh -``` - -The wizard will: - -- Ask configuration questions -- Create your first email address -- Create an admin user for the management interface - -### Step 6: Access Management Interface - -Log in to the management interface using the credentials created during setup: - -- Management Interface: `http://127.0.0.1:81/manager/` -- Webmail: `http://127.0.0.1:81/webmail/` - -## Kubernetes Installation - -Kubernetes deployment requires an existing MySQL-compatible database (MySQL or Percona XtraDB). The provided kustomization does not provision a database. - -You can find a complete example configuration for Kubernetes in the [example-configs](https://github.com/jeboehm/docker-mailserver/tree/main/docs/example-configs/kustomize/external-db-and-https-ingress) folder. - -### Step 1: Configure Environment Variables to create a ConfigMap - -1. Copy the example environment file: - -```bash -cp .env.dist .env -``` - -2. Edit `.env` and configure variables as described in [Environment Variables](configuration/environment-variables.md). - -3. Create Kubernetes secrets for database credentials and other sensitive values before applying manifests. - -### Step 2: Create Namespace - -Create a dedicated namespace for the mailserver: - -```bash -kubectl create namespace mail -``` - -### Step 3: Generate TLS Certificates - -If you are not using a certificate management tool like `cert-manager`, generate self-signed TLS certificates: - -```bash -bin/create-tls-certs.sh -``` - -### Step 4: Create TLS Secret - -Create a Kubernetes secret for the TLS certificates: - -```bash -kubectl create -n mail secret tls tls-certs \ - --cert=config/tls/tls.crt \ - --key=config/tls/tls.key -``` - -### Step 5: Apply Kustomize Manifests - -Deploy the mailserver using Kustomize: - -```bash -kubectl apply -n mail -k . -``` - -### Step 6: Verify Pod Status - -Wait for all pods to be running and healthy: - -```bash -kubectl get pods -n mail -``` - -### Step 7: Run Installation Wizard - -Execute the setup script in the web pod's php-fpm container: - -```bash -kubectl exec -n mail -it deployment/web -c php-fpm -- setup.sh -``` - -The wizard will guide you through: - -- Initial configuration -- First email address creation -- Admin user setup - -### Step 8: Access Management Interface - -Access the management interface through your configured ingress using the admin credentials created during setup. - -## Ports Overview - -The following services are exposed on the specified ports: - -| Service | Address | -| ----------------------------------- | ---------------------------- | -| POP3 (STARTTLS required) | 127.0.0.1:110 | -| POP3S | 127.0.0.1:995 | -| IMAP (STARTTLS required) | 127.0.0.1:143 | -| IMAPS | 127.0.0.1:993 | -| SMTP | 127.0.0.1:25 | -| Mail Submission (STARTTLS required) | 127.0.0.1:587 | -| Management Interface | http://127.0.0.1:81/manager/ | -| Webmail | http://127.0.0.1:81/webmail/ | -| Rspamd web interface | http://127.0.0.1:81/rspamd/ | - -## Post-Installation - -After installation, consider: - -1. **DNS Configuration**: Ensure proper DNS records (MX, SPF, DKIM, DMARC) are configured for your domain -2. **TLS Certificates**: Replace self-signed certificates with valid certificates from a trusted CA -3. **Firewall Rules**: Configure firewall rules to allow necessary ports -4. **Backup Strategy**: Set up regular backups of persistent volumes -5. **Monitoring**: Configure monitoring and alerting for service health - -See the [Configuration](configuration/environment-variables.md) section for advanced configuration options. - -## Troubleshooting - -Common issues and solutions: - -- **Services not starting**: Check container logs with `docker-compose logs` or `kubectl logs` -- **Database connection errors**: Verify database credentials in `.env` and ensure the database is accessible -- **TLS certificate issues**: Ensure certificates are properly mounted and have correct permissions -- **Port conflicts**: Verify no other services are using the required ports - -For additional help, see: - -- [Architecture Documentation](development/architecture.md) -- [Development Guide](development/development.md) -- [GitHub Issues](https://github.com/jeboehm/docker-mailserver/issues) +For ports and post-installation steps, see [Ports reference](reference/ports.md) and the post-installation sections in the how-to guides. diff --git a/docs/observability/intro.md b/docs/observability/intro.md index dd9f447d..f81a0a25 100644 --- a/docs/observability/intro.md +++ b/docs/observability/intro.md @@ -1,45 +1,3 @@ # Observability -Observability is the ability to understand a system's internal state by examining its external outputs, crucial for complex, modern software systems. - -`mailserver-admin` provides observability features for monitoring the mailserver components, enabling administrators to monitor service health, message processing statistics, and operational metrics through web-based dashboards. - -## Overview - -The observability features integrate with the Rspamd filter service and Dovecot mail delivery agent to collect and display real-time statistics and historical trends. These dashboards provide visibility into message processing, spam filtering effectiveness, authentication patterns, and mail delivery rates. - -## Rspamd Statistics - -The Rspamd Statistics dashboard displays metrics from the Rspamd controller service, providing insights into spam filtering operations and message processing. - -![Rspamd Statistics](../images/admin/obs_rspamd.png) - -The dashboard includes: - -- **Service Status**: Health check indicator showing Rspamd controller availability and response time -- **Summary Metrics**: Key performance indicators including: - - Total messages scanned - - Spam messages detected - - Ham (clean) messages identified - - Messages used for machine learning - - Active connections to the service -- **Throughput Chart**: Time-series visualization of message processing rates per minute, showing action distributions including rejections, soft rejections, subject rewrites, header additions, greylisting, and no-action messages. Supports time aggregation for day, week, month, and year views -- **Action Distribution**: Donut chart showing the proportion of messages categorised by Rspamd actions (clean, rejected, temporarily rejected, probable spam, greylisted) -- **Configuration Details**: Displays action thresholds and top symbols used in spam scoring - -## Dovecot Statistics - -The Dovecot Statistics dashboard presents metrics from the Dovecot mail delivery agent via the Doveadm HTTP API, focusing on authentication and mail delivery operations. - -![Dovecot Statistics](../images/admin/obs_dovecot.png) - -The dashboard provides: - -- **API Status**: Connection status and authentication verification for the Doveadm HTTP API, including last update timestamp -- **Summary Metrics**: Overview cards showing: - - Authentication successes - - Authentication failures - - Index operations count -- **Authentication Rate Chart**: Time-series graph displaying authentication success and failure rates per minute, enabling identification of authentication patterns and potential security issues -- **Mail Deliveries Chart**: Time-series visualization of mail delivery rates per minute, showing message throughput to user mailboxes -- **Data Collection**: Charts are calculated from consecutive samples, with rates computed as deltas between measurements +See **[About observability](../explanation/observability.md)** for an overview of the observability features in mailserver-admin and how they work. diff --git a/docs/reference/dns-records.md b/docs/reference/dns-records.md new file mode 100644 index 00000000..9e66ebe7 --- /dev/null +++ b/docs/reference/dns-records.md @@ -0,0 +1,145 @@ +# DNS Records Reference + +DNS record types and formats required for the mailserver. Configure these in your domain's DNS zone. + +## Summary + +| Record Type | Name | Purpose | +| ----------- | -------------------- | ---------------------------------- | +| MX | `@` | Direct incoming mail | +| A | `mail` | Resolve mailserver hostname (IPv4) | +| AAAA | `mail` | Resolve mailserver hostname (IPv6) | +| TXT (SPF) | `@` | Authorize sending servers | +| TXT (DKIM) | `default._domainkey` | Email signature verification | +| TXT (DMARC) | `_dmarc` | Authentication policy | + +## MX Record + +Directs incoming mail to the mailserver. Use the value of `MAILNAME`. + +```text +Type: MX +Name: @ (or domain name) +Priority: 10 +Value: mail.example.com +``` + +Example for `example.com`: + +```text +example.com. IN MX 10 mail.example.com. +``` + +Lower priority values have higher precedence when multiple MX records exist. + +## A and AAAA Records + +Resolve the mailserver hostname to IP addresses. Required for the MX record to work. + +```text +Type: A +Name: mail (or hostname without domain) +Value: 192.0.2.1 + +Type: AAAA +Name: mail +Value: 2001:db8::1 +``` + +Example for `mail.example.com`: + +```text +mail.example.com. IN A 192.0.2.1 +mail.example.com. IN AAAA 2001:db8::1 +``` + +## SPF Record (TXT) + +Authorizes which servers may send mail for the domain. Published as a TXT record. + +```text +Type: TXT +Name: @ +Value: v=spf1 mx a ip4:192.0.2.1 ip6:2001:db8::1 ~all +``` + +Common mechanisms: + +- `mx`: Authorize MX hosts +- `a`: Authorize A record(s) for the domain +- `ip4:`, `ip6:`: Authorize specific IPs +- `include:domain`: Include another domain's SPF +- `~all`: Soft fail for others (testing) +- `-all`: Hard fail for others (production) + +Example: + +```text +example.com. IN TXT "v=spf1 mx a ip4:192.0.2.1 ~all" +``` + +## DKIM Record (TXT) + +Publishes the public key for DKIM verification. The management interface generates the exact record; the name uses a selector and `_domainkey`. + +```text +Type: TXT +Name: default._domainkey (or selector._domainkey) +Value: v=DKIM1; k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC... +``` + +Example for `example.com` with selector `default`: + +```text +default._domainkey.example.com. IN TXT "v=DKIM1; k=rsa; p=..." +``` + +## DMARC Record (TXT) + +Defines policy for messages that fail SPF/DKIM and optional reporting. + +```text +Type: TXT +Name: _dmarc +Value: v=DMARC1; p=none; rua=mailto:dmarc@example.com +``` + +Policy (`p=`): + +- `none`: Monitor only +- `quarantine`: Quarantine failures +- `reject`: Reject failures + +Common tags: + +- `v=DMARC1`: Version (required) +- `p=`: Policy (none, quarantine, reject) +- `rua=mailto:...`: Aggregate report address +- `ruf=mailto:...`: Forensic report address +- `aspf=r`, `adkim=r`: Alignment (relaxed or strict) + +Example monitoring policy: + +```text +_dmarc.example.com. IN TXT "v=DMARC1; p=none; rua=mailto:dmarc@example.com" +``` + +Example reject policy: + +```text +_dmarc.example.com. IN TXT "v=DMARC1; p=reject; rua=mailto:dmarc@example.com; aspf=r; adkim=r" +``` + +## Verification + +Use `dig` or `nslookup` to verify records: + +```bash +dig MX example.com +dig A mail.example.com +dig TXT example.com +dig TXT default._domainkey.example.com +dig TXT _dmarc.example.com +``` + +For context on why these records matter, see [DNS and email delivery](../explanation/dns-and-email.md). diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md new file mode 100644 index 00000000..22a80c22 --- /dev/null +++ b/docs/reference/environment-variables.md @@ -0,0 +1,95 @@ +# Environment Variables Reference + +Overview of environment variables used to configure docker-mailserver. Set these in your `.env` file or in the environment. + +## Basic Configuration + +### Database + +When using the MySQL service provided by docker-mailserver compose, you do not need to set host, port, or database. You must set `MYSQL_PASSWORD`. + +| Variable | Default | Description | +| ----------------------- | ------------------------------------ | ---------------------------------- | +| `MYSQL_HOST` | `db` | MySQL database hostname | +| `MYSQL_PORT` | `3306` | MySQL database port | +| `MYSQL_DATABASE` | `mailserver` | MySQL database name | +| `MYSQL_USER` | `root` (MTA/MDA), `mailserver` (Web) | MySQL database username | +| `MYSQL_PASSWORD` | _(empty)_ | MySQL database password | +| `MYSQL_TLS_VERIFY_CERT` | `no` | MySQL TLS certificate verification | + +### Mail Server Identity + +| Variable | Default | Description | +| --------------------- | ------------------------ | ----------------------------------------------------------------- | +| `MAILNAME` | `mail.example.com` | Primary mail server hostname | +| `POSTMASTER` | `postmaster@example.com` | Postmaster email address | +| `RECIPIENT_DELIMITER` | `-` | Character used for address extensions (e.g., user+tag@domain.com) | + +### Redis + +When using the Redis service provided by docker-mailserver compose or kustomize, you do not need to configure host or port. You must set `REDIS_PASSWORD`. + +| Variable | Default | Description | +| ---------------- | ------------ | --------------------- | +| `REDIS_HOST` | `redis` | Redis server hostname | +| `REDIS_PORT` | `6379` | Redis server port | +| `REDIS_PASSWORD` | _(required)_ | Redis server password | + +### Authentication + +| Variable | Default | Description | +| --------------------- | ------------ | ------------------------------------- | +| `CONTROLLER_PASSWORD` | _(required)_ | Password for RSpamd controller access | +| `DOVEADM_API_KEY` | _(required)_ | API key for Dovecot API access | + +### Relay + +| Variable | Default | Description | +| ------------------- | ------- | --------------------------------- | +| `RELAYHOST` | `false` | SMTP relay host for outgoing mail | +| `RELAY_PASSWD_FILE` | `false` | Path to relay authentication file | + +### Filter + +| Variable | Default | Description | +| ------------- | ------- | ---------------------------- | +| `FILTER_MIME` | `false` | Enable MIME header filtering | + +## Extended Configuration + +### Service Addresses + +| Variable | Default | Description | +| ----------------------------- | ------------------------ | --------------------------------------- | +| `FILTER_MILTER_ADDRESS` | `filter:11332` | RSpamd milter service address | +| `FILTER_WEB_ADDRESS` | `filter:11334` | RSpamd web interface address | +| `MDA_AUTH_ADDRESS` | `mda:2004` | Dovecot authentication service address | +| `MDA_IMAP_ADDRESS` | `mda:143` | Dovecot IMAP service address | +| `MDA_LMTP_ADDRESS` | `mda:2003` | Dovecot LMTP service address | +| `MDA_MANAGESIEVE_ADDRESS` | `mda:4190` | Dovecot ManageSieve service address | +| `MDA_DOVEADM_ADDRESS` | `mda:8080` | Dovecot API address (default: mda:8080) | +| `MTA_HOST` | `mta` | Postfix MTA hostname | +| `MTA_SMTP_ADDRESS` | `mta:25` | Postfix SMTP service address | +| `MTA_SMTP_SUBMISSION_ADDRESS` | `mta:587` | Postfix SMTP submission service address | +| `WEB_HTTP_ADDRESS` | `web:80` | Web interface HTTP address | +| `RSPAMD_DNS_SERVERS` | `round-robin:unbound:53` | DNS servers for RSpamd (Kubernetes) | + +### mailserver-admin + +See [mailserver-admin configuration reference](mailserver-admin-config.md). + +### PHP Sessions + +| Variable | Default | Description | +| -------------------------- | ---------------------------------------------------------- | -------------------- | +| `PHP_SESSION_SAVE_HANDLER` | `redis` | Session save handler | +| `PHP_SESSION_SAVE_PATH` | `tcp://${REDIS_HOST}:${REDIS_PORT}?auth=${REDIS_PASSWORD}` | Session save path | + +### Proxy Protocol + +| Variable | Default | Description | +| -------------------- | ------- | ---------------------------------------------------------------------------- | +| `MDA_UPSTREAM_PROXY` | `false` | Enable Traefik / HAProxy PROXY protocol for MDA (Dovecot) IMAP/POP3 services | +| `MTA_UPSTREAM_PROXY` | `false` | Enable Traefik / HAProxy PROXY protocol for MTA (Postfix) SMTP services | + +When set to `true`, the mail server accepts the HAProxy PROXY protocol to receive the original client IP when behind a load balancer or reverse proxy. diff --git a/docs/reference/local-address-extension.md b/docs/reference/local-address-extension.md new file mode 100644 index 00000000..b2b85655 --- /dev/null +++ b/docs/reference/local-address-extension.md @@ -0,0 +1,33 @@ +# Local Address Extension Reference + +Local address extension (RFC 5233 subaddressing) delivers mail to extended addresses at the same mailbox without extra configuration. A configurable delimiter plus a tag is appended to the local part; all such mail is delivered to the base mailbox. + +## Configuration + +| Variable | Default | Description | +| --------------------- | ------- | ------------------- | +| `RECIPIENT_DELIMITER` | `-` | Delimiter character | + +Example with default delimiter `-`: + +```text +user1-friends@example.com +user1-newsletter@example.com +``` + +Example with `RECIPIENT_DELIMITER=+`: + +```text +user1+friends@example.com +user1+newsletter@example.com +``` + +## Sieve + +Extended addresses can be matched in Sieve. Example for `user1-newsletter@example.com`: + +```sieve +if address :matches :localpart "to" "user1-newsletter*" { + fileinto "Newsletters"; +} +``` diff --git a/docs/reference/mailserver-admin-config.md b/docs/reference/mailserver-admin-config.md new file mode 100644 index 00000000..7832dab3 --- /dev/null +++ b/docs/reference/mailserver-admin-config.md @@ -0,0 +1,42 @@ +# mailserver-admin Configuration Reference + +Environment variables for the mailserver-admin (web) application. Set in `.env` or the environment. + +## General + +| Variable | Default | Description | +| ----------------- | -------- | --------------------------------- | +| `APP_ENV` | `prod` | Application environment | +| `APP_SECRET` | (random) | Secret key (e.g. CSRF) | +| `CSRF_ENABLED` | `true` | Enable CSRF protection | +| `TRUSTED_PROXIES` | — | Comma-separated trusted proxy IPs | + +## Database + +| Variable | Description | +| ---------------- | ------------------- | +| `MYSQL_USER` | MySQL user | +| `MYSQL_PASSWORD` | MySQL password | +| `MYSQL_HOST` | MySQL host | +| `MYSQL_DATABASE` | MySQL database name | +| `REDIS_HOST` | Redis host | +| `REDIS_PORT` | Redis port | +| `REDIS_PASSWORD` | Redis password | + +## OAuth2 + +| Variable | Default | Description | +| ------------------------- | ------------------------ | --------------------------------------------- | +| `OAUTH_ENABLED` | `false` | Enable OAuth2 login | +| `OAUTH_CLIENT_ID` | — | OAuth2 client ID | +| `OAUTH_CLIENT_SECRET` | — | OAuth2 client secret | +| `OAUTH_CLIENT_SCOPES` | `"email profile groups"` | Requested scopes | +| `OAUTH_AUTHORIZATION_URL` | — | Authorization URL | +| `OAUTH_ACCESS_TOKEN_URL` | — | Token URL | +| `OAUTH_INFOS_URL` | — | Userinfo URL | +| `OAUTH_ADMIN_GROUP` | — | Group name for admin rights | +| `OAUTH_BUTTON_TEXT` | `"Login with OIDC"` | Login button label | +| `OAUTH_PATHS_IDENTIFIER` | `sub` | Field containing user identifier (e.g. email) | +| `OAUTH_CREATE_USER` | `false` | Create user if no match | + +For setting up OAuth2, see [How to configure OAuth2](../how-to/configure-oauth2.md). diff --git a/docs/reference/ports.md b/docs/reference/ports.md new file mode 100644 index 00000000..35e00ce1 --- /dev/null +++ b/docs/reference/ports.md @@ -0,0 +1,15 @@ +# Ports Reference + +Services and ports exposed by docker-mailserver. + +| Service | Address | +| ----------------------------------- | ---------------------------- | +| POP3 (STARTTLS required) | 127.0.0.1:110 | +| POP3S | 127.0.0.1:995 | +| IMAP (STARTTLS required) | 127.0.0.1:143 | +| IMAPS | 127.0.0.1:993 | +| SMTP | 127.0.0.1:25 | +| Mail Submission (STARTTLS required) | 127.0.0.1:587 | +| Management Interface | http://127.0.0.1:81/manager/ | +| Webmail | http://127.0.0.1:81/webmail/ | +| Rspamd web interface | http://127.0.0.1:81/rspamd/ | diff --git a/docs/reference/service-architecture.md b/docs/reference/service-architecture.md new file mode 100644 index 00000000..7f49848f --- /dev/null +++ b/docs/reference/service-architecture.md @@ -0,0 +1,37 @@ +# Service Architecture Reference + +docker-mailserver consists of the following services: + +| Service | Component | Role | +| --------- | ----------------- | ---------------------------------- | +| MTA | Postfix | SMTP (send/receive) | +| MDA | Dovecot | IMAP/POP3 (mailbox access) | +| Web | Admin + Roundcube | Management UI and webmail | +| Filter | Rspamd | Spam filtering | +| SSL | — | Certificate generation | +| Database | MySQL | User and configuration data | +| Redis | Redis | Caching and sessions | +| Unbound | Unbound | DNS resolver for filter | +| Fetchmail | Fetchmail | External mail retrieval (optional) | + +## Persistent Volumes + +| Volume | Purpose | +| ------------- | ----------------------------------- | +| `data-db` | MySQL data (users, aliases, config) | +| `data-mail` | User mailboxes (maildir) | +| `data-tls` | TLS certificates and keys | +| `data-filter` | Rspamd data and statistics | +| `data-redis` | Redis data | +| `data-spool` | Postfix queue and spool | + +## Volume Mounts by Service + +- **db:** `data-db:/var/lib/mysql` +- **mta:** `data-tls:/etc/postfix/tls:ro`, `data-spool:/var/spool/postfix` +- **mda:** `data-mail:/srv/vmail`, `data-tls:/etc/dovecot/tls:ro` +- **filter:** `data-filter:/var/lib/rspamd` +- **redis:** `data-redis:/data` +- **SSL:** `data-tls:/media/tls:rw` + +For an overview of how these components work together, see [Architecture](../explanation/architecture.md). diff --git a/docs/reference/upgrade-changelog.md b/docs/reference/upgrade-changelog.md new file mode 100644 index 00000000..e31a9977 --- /dev/null +++ b/docs/reference/upgrade-changelog.md @@ -0,0 +1,46 @@ +# Upgrade Changelog + +Version-specific upgrade notes. When upgrading, update manifests in `deploy/compose` and `deploy/kustomize` to match the new version (volumes, configuration). Update `.env` for new or changed environment variables. + +## v7.3 + +Observability features in mailserver-admin. Set: + +- `MDA_DOVEADM_ADDRESS`: MDA address for Dovecot API (default: `mda:8080`) +- `DOVEADM_API_KEY`: API key for Dovecot API + +Change at least `DOVEADM_API_KEY` from the default. + +## v7.1 + +- **web:** mailserver-admin can generate mobileconfig files for iOS and macOS. Generation uses the same TLS certificate shown to clients. Mount that certificate into the web container to enable generation. + +## v6.x to v7.x + +- **web:** Image is Alpine-based and uses FrankenPHP instead of PHP-FPM. +- **web:** Roundcube path: `/var/www/html/webmail` → `/opt/roundcube` (symlink at `/var/www/html/webmail` to Roundcube `public_html`). +- **web:** Admin path: `/opt/admin`. +- **web:** Read-only operation supported; configure tmpfs mounts as in `deploy/compose/web.yaml`. + +## v5.x to v6.0 + +- Kubernetes deployment is supported via `kustomization.yaml`. Helm chart deprecated and archived. +- **virus:** Removed. Use [Rspamd antivirus](https://docs.rspamd.com/modules/antivirus/) for antivirus. +- **unbound:** Added as DNS resolver for the filter. +- **filter:** Base image `rspamd/rspamd`; no longer Alpine-based. +- **web:** `CSRF_ENABLED=false` disables CSRF (default: `true`). Rootless: web listens on 8080 internally. + +### MTA + +- TLS paths: `/etc/postfix/tls/tls.crt`, `/etc/postfix/tls/tls.key`. +- Submission only on port 587. + +### MDA + +- Base image: `dovecot/dovecot`; no longer Alpine-based. +- TLS paths: `/etc/dovecot/tls/tls.crt`, `/etc/dovecot/tls/tls.key`. No DH file. +- Mail storage: `/srv/vmail` (was `/var/vmail`). +- Rootless: runs as non-root; ensure mail storage and TLS are accessible by UID/GID 1000. +- Internal ports: IMAP 31143, POP3 31110, IMAPS 31993, POP3S 31995 (internal only). +- FTS enabled by default; `FTS_*` variables removed. +- POP3 and IMAP always enabled; `POP3_ENABLED` and `IMAP_ENABLED` removed. diff --git a/docs/reference/user-roles.md b/docs/reference/user-roles.md new file mode 100644 index 00000000..80b0d7bb --- /dev/null +++ b/docs/reference/user-roles.md @@ -0,0 +1,22 @@ +# User Roles Reference + +mailserver-admin defines three roles with different permissions. + +## Admin + +- Manage all domains, users, aliases, and DKIM +- Full access to all features + +## Domain Admin + +- Manage users, aliases, and fetchmail within their assigned domain only +- Cannot add, edit, or delete domains +- Cannot manage DKIM + +## User + +- Log in to the application +- Manage own fetchmail accounts +- Change own password (subject to password policy) +- Cannot manage users, aliases, or domains +- No access to DKIM or domain configuration diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md new file mode 100644 index 00000000..ef74a54b --- /dev/null +++ b/docs/tutorials/getting-started.md @@ -0,0 +1,86 @@ +# Getting Started + +This tutorial walks you through installing docker-mailserver with Docker Compose and creating your first mailbox. By the end you will have a running mailserver and access to the management interface. + +**What we will do:** Configure the environment, start the services, run the setup wizard, and log in to the management interface. + +## Prerequisites + +- Docker and Docker Compose installed +- A domain name (for later DNS configuration) +- Ports 25, 110, 143, 587, 993, 995, 81 available + +## Step 1: Obtain the project + +Download the latest release from the [Releases](https://github.com/jeboehm/docker-mailserver/releases) page and unpack the archive (`release-vX.X.X.tar.gz`), or clone the repository: + +```bash +git clone https://github.com/jeboehm/docker-mailserver.git +cd docker-mailserver +``` + +Do not use the `latest` container image tag for production. Use a specific version tag (e.g. `jeboehm/mailserver-mta:6.3`). + +## Step 2: Configure environment variables + +Copy the example environment file: + +```bash +cp .env.dist .env +``` + +Edit `.env` and set at least: + +- `MYSQL_PASSWORD` (required when using the included database) +- `REDIS_PASSWORD` (required when using the included Redis) +- `CONTROLLER_PASSWORD` (required for Rspamd) +- `DOVEADM_API_KEY` (required for Dovecot API) + +For a full list of variables, see [Environment variables reference](../reference/environment-variables.md). + +## Step 3: Pull and start services + +Pull the container images: + +```bash +bin/production.sh pull +``` + +Start all services and wait for them to be ready: + +```bash +bin/production.sh up -d --wait +``` + +You should see the containers start. Wait until health checks pass. You can check status with `bin/production.sh ps`. + +## Step 4: Run the setup wizard + +Run the setup script to create your first account and an admin user: + +```bash +bin/production.sh run --rm web setup.sh +``` + +The wizard will ask for configuration details, create your first email address, and create an admin user for the management interface. Follow the prompts. + +## Step 5: Open the management interface + +Open a browser and go to: + +- **Management interface:** `http://127.0.0.1:81/manager/` +- **Webmail:** `http://127.0.0.1:81/webmail/` + +Log in with the admin credentials you set in the wizard. You should see the dashboard. + +## Step 6: Check the dashboard + +On the dashboard you will see an overview of the mailserver: domains, users, and quick links. From here you can add domains, users, and aliases. + +## Next steps + +- Configure DNS records for your domain so other servers can deliver mail to you. See [DNS records reference](../reference/dns-records.md) and [How to configure DNS](../how-to/configure-dns.md). +- Replace self-signed TLS certificates with valid certificates. See [How to configure TLS certificates](../how-to/configure-tls.md). +- Add more users or domains via the management interface. See the [Administration how-to guides](../how-to/manage-domains.md). + +For a list of exposed ports and services, see [Ports reference](../reference/ports.md). diff --git a/docs/upgrade.md b/docs/upgrade.md index 08fa4561..2fdda06c 100644 --- a/docs/upgrade.md +++ b/docs/upgrade.md @@ -1,60 +1,3 @@ -# Upgrade Guide +# Upgrade -Upgrade guide for docker-mailserver. - -When upgrading, ensure that container configuration files are updated to match the requirements of the new version. Review the manifests in `deploy/compose` and `deploy/kustomize` for any changes to persistent volumes or configuration, and update them as necessary. If new environment variables have been introduced, update the `.env` file accordingly. - -## v7.3 - -`mailserver-admin` now provides observability features for the mailserver. To make sure the service to service communication works, the -following environment variables have been added: - -- `MDA_DOVEADM_ADDRESS`: The address of the MDA service for Dovecot API access. (default: `mda:8080`) -- `DOVEADM_API_KEY`: The API key for Dovecot API access. - -Please make sure to change at least `DOVEADM_API_KEY`. - -## v7.1 - -- **web**: mailserver-admin now includes a feature to generate mobileconfig files for iOS and macOS. These files are signed with the same TLS certificate that the mailserver displays to connecting clients. To generate these files, it’s necessary to mount the certificate to the web container. - -## v6.x to v7.x - -The web image is now based on Alpine Linux and uses FrankenPHP instead of PHP-FPM. -The installation path for Roundcube has changed from `/var/www/html/webmail` to `/opt/roundcube`. -A symbolic link is retained at `/var/www/html/webmail`, pointing to the `public_html` directory of Roundcube. -The admin interface is now installed in `/opt/admin` to have a more appropriate naming. -The container now supports read-only operation. Ensure that tmpfs mounts are configured as specified in `deploy/compose/web.yaml`. - -## v5.x to v6.0 - -Deployment on Kubernetes is now a first class citizen. You can use the `kustomization.yaml` file to deploy the mailserver to your Kubernetes cluster. -The Helm chart has been deprecated and archived. - -- **virus**: The virus service has been removed. To add antivirus functionality, see the [Rspamd antivirus documentation](https://docs.rspamd.com/modules/antivirus/). -- **unbound**: Added unbound as a DNS resolver for the filter service. -- **filter**: The base image has been changed to `rspamd/rspamd`. This image is no longer based on Alpine Linux. -- **web**: Set `CSRF_ENABLED=false` to disable CSRF protection in the web interface (default: `true`). -- **web**: To run rootless, the web interface now runs on port 8080 internally. - -### MTA (Mail Transfer Agent) - -- **TLS Certificate Paths**: Certificate paths have been updated to `/etc/postfix/tls/tls.crt` and `/etc/postfix/tls/tls.key`. -- **Mail Submission**: Mail submission is now only possible on port 587. - -### MDA (Mail Delivery Agent) - -- **Base Image**: Changed to `dovecot/dovecot`. This image is no longer based on Alpine Linux. -- **TLS Certificate Paths**: Updated to `/etc/dovecot/tls/tls.crt` and `/etc/dovecot/tls/tls.key`. A Diffie-Hellman file is no longer required. -- **Mail Storage**: Now mounted to `/srv/vmail` instead of `/var/vmail`. -- **Rootless Operation**: The container now runs as a non-root user. Ensure mail storage and TLS certificates are accessible by `UID 1000` and `GID 1000`. -- **Internal Ports**: IMAP/POP3 internal ports have been updated: - - IMAP: `31143` - - POP3: `31110` - - IMAPS: `31993` - - POP3S: `31995` - - These ports are only used for connections within the container network. - -- **Full Text Search**: Enabled by default. All `FTS_` environment variables have been removed. -- **Protocol Support**: POP3 and IMAP are always enabled. The `POP3_ENABLED` and `IMAP_ENABLED` environment variables have been removed. +See **[How to upgrade](how-to/upgrade.md)** for upgrade steps and **[Upgrade changelog](reference/upgrade-changelog.md)** for version-specific notes.