You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file gives AI agents and contributors the project conventions, documentation framework, and structure they need to work consistently on the codebase and docs.
4
+
5
+
## Documentation framework: Diátaxis
6
+
7
+
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:
|**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. |
12
+
|**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. |
13
+
|**Reference**| Look up facts | Application of skill (work) | Technical description: accurate, complete, neutral; structure mirrors the product; consulted, not read. |
14
+
|**Explanation**| Understand context and “why” | Acquisition of skill (study) | Background and discussion: design, trade-offs, connections; can include opinion and perspective. |
15
+
16
+
**Guidelines:**
17
+
18
+
-**Tutorials:** One or few. One main path; show the result early; avoid options and long explanations; link to reference/explanation for depth.
19
+
-**How-to guides:** One goal per guide; title = “How to …”; steps only; link to reference for options and formats.
20
+
-**Reference:** Describe the machinery (env vars, ports, record formats, APIs); austere; structured like the product; no instruction or opinion.
21
+
-**Explanation:** Answer “why?” and “how does it fit together?”; can compare alternatives and give context; do not mix in procedures or reference tables.
22
+
23
+
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?”
-**`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.
34
+
-**`configuration/`** — Legacy entry points; these files redirect to the appropriate how-to or reference.
-**`observability/`** — `intro.md` redirects to `explanation/observability.md`.
37
+
38
+
MkDocs config is **`.mkdocs.yaml`**; the `nav` there reflects this structure (Tutorial, How-to guides, Reference, Administration, Explanation, Recipes, Development).
39
+
40
+
## Documentation writing style
41
+
42
+
- Use **technical documentation language**, not marketing. Avoid subjective terms (“powerful”, “particularly useful”, “sophisticated”).
43
+
- Use **direct, factual** statements about what the software does. Include **technical references** (e.g. RFCs) and **concrete examples** where useful.
44
+
- Focus on **implementation and configuration**; keep prose concise and suitable for technical readers.
45
+
- Prefer **functional descriptions** over promotional copy.
46
+
47
+
## Project structure
48
+
49
+
-**Architecture:** The mailserver is made of multiple containers/pods (MTA, MDA, Web, Filter, SSL, Database, Redis, Unbound, Fetchmail) that together provide mail and management.
50
+
-**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 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.
55
+
56
+
## Quick reference for agents
57
+
58
+
-**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.
59
+
-**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.
60
+
-**Adding a new how-to:** Create under **`how-to/`** with a “How to …” title; add the page to **`.mkdocs.yaml`** under “How-to guides”.
61
+
-**Changing deployment (Compose or Kustomize):** Apply the same logical change in **`deploy/compose/`** and **`deploy/kustomize/`** where applicable.
Copy file name to clipboardExpand all lines: docs/README.md
+51-40Lines changed: 51 additions & 40 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,58 +8,69 @@
8
8
9
9
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.
10
10
11
-
## Key Features
12
-
13
-
-**Email Protocols**: POP3, IMAP, and SMTP with user authentication
14
-
-**Web Management**: Web-based interface for account, domain, and alias administration
15
-
-**Webmail**: Integrated webmail interface
16
-
-**External Mail Retrieval**: Fetchmail integration for retrieving emails from external providers
17
-
-**Email Authentication**: DKIM message signing for email authenticity
18
-
-**Spam Filtering**: Server-side mail filtering with configurable rules via web frontend
19
-
-**Spam Training**: Train spam filters by moving emails to or from the junk folder
20
-
-**Real-time Protection**: RBL (Real-Time Blackhole List) integration for spam prevention
21
-
-**Greylisting**: Selective greylisting for likely spam
22
-
-**Address Management**: Support for catch-all addresses and send-only accounts
23
-
-**Security**: Sender address restrictions and configurable address extensions
24
-
-**Quota Management**: Email quota management with notifications
25
-
-**TLS**: Enforced TLS for secure communication
26
-
-**Full-Text Search**: FTS support for efficient message searching
27
-
-**Health Monitoring**: Continuous self-monitoring via Docker healthcheck
28
-
29
-
## Quick Start
30
-
31
-
1.**[Installation Guide](installation.md)** - Get started with Docker or Kubernetes deployment
32
-
2.**[Upgrade Guide](upgrade.md)** - Upgrade procedures and version migration notes
33
-
34
-
## Service Architecture
11
+
## Documentation structure
12
+
13
+
The documentation is organised by purpose:
14
+
15
+
-**[Tutorial: Getting Started](tutorials/getting-started.md)** — A step-by-step lesson to install docker-mailserver with Docker Compose and create your first mailbox.
16
+
-**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.
17
+
-**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.
18
+
-**Explanation** — Background and context: [architecture](explanation/architecture.md), [DNS and email delivery](explanation/dns-and-email.md), [observability](explanation/observability.md).
19
+
20
+
## Key features
21
+
22
+
-**Email protocols:** POP3, IMAP, and SMTP with user authentication
23
+
-**Web management:** Web-based interface for account, domain, and alias administration
24
+
-**Webmail:** Integrated webmail interface
25
+
-**External mail retrieval:** Fetchmail integration for retrieving emails from external providers
26
+
-**Email authentication:** DKIM message signing for email authenticity
27
+
-**Spam filtering:** Server-side mail filtering with configurable rules via web frontend
28
+
-**Spam training:** Train spam filters by moving emails to or from the junk folder
29
+
-**Real-time protection:** RBL integration for spam prevention
30
+
-**Greylisting:** Selective greylisting for likely spam
-**Security:** Sender address restrictions and configurable address extensions
33
+
-**Quota management:** Email quota management with notifications
34
+
-**TLS:** Enforced TLS for secure communication
35
+
-**Full-text search:** FTS support for efficient message searching
36
+
-**Health monitoring:** Continuous self-monitoring via Docker healthcheck
37
+
38
+
## Quick start
39
+
40
+
1.**[Tutorial: Getting Started](tutorials/getting-started.md)** — Install with Docker Compose and create your first account
41
+
2.**[How to install with Docker](how-to/install-docker.md)** — Docker Compose installation steps
42
+
3.**[How to install on Kubernetes](how-to/install-kubernetes.md)** — Kubernetes deployment steps
43
+
4.**[How to upgrade](how-to/upgrade.md)** — Upgrade procedures and [upgrade changelog](reference/upgrade-changelog.md)
44
+
45
+
## Service architecture
35
46
36
47
The mailserver consists of multiple microservices:
37
48
38
-
-**MTA (Mail Transfer Agent)**- Postfix for SMTP
39
-
-**MDA (Mail Delivery Agent)**- Dovecot for IMAP/POP3
40
-
-**Web**- Admin interface and Roundcube webmail
41
-
-**Filter**- RSpamd for spam filtering
42
-
-**SSL**- Certificate generation and management
43
-
-**Database**- MySQL for user and configuration data
44
-
-**Redis**- Caching and session storage
45
-
-**Unbound**- DNS resolver for the filter service
46
-
-**Fetchmail**- External mail retrieval (optional)
49
+
-**MTA (Mail Transfer Agent)**— Postfix for SMTP
50
+
-**MDA (Mail Delivery Agent)**— Dovecot for IMAP/POP3
51
+
-**Web**— Admin interface and Roundcube webmail
52
+
-**Filter**— RSpamd for spam filtering
53
+
-**SSL**— Certificate generation and management
54
+
-**Database**— MySQL for user and configuration data
55
+
-**Redis**— Caching and session storage
56
+
-**Unbound**— DNS resolver for the filter service
57
+
-**Fetchmail**— External mail retrieval (optional)
47
58
48
-
See [Architecture Documentation](development/architecture.md) for detailed information.
59
+
See [Service architecture reference](reference/service-architecture.md) for a concise list and [About the service architecture](explanation/architecture.md) for context.
49
60
50
-
## Getting Help
61
+
## Getting help
51
62
52
-
-**[GitHub Issues](https://github.com/jeboehm/docker-mailserver/issues)**- Report bugs and request features
53
-
-**[Releases](https://github.com/jeboehm/docker-mailserver/releases)**- View release notes and changelog
63
+
-**[GitHub Issues](https://github.com/jeboehm/docker-mailserver/issues)**— Report bugs and request features
64
+
-**[Releases](https://github.com/jeboehm/docker-mailserver/releases)**— View release notes and changelog
[](https://www.star-history.com/#jeboehm/docker-mailserver&type=date&legend=top-left)
The dashboard is the main page of the administration tool. It provides a quick overview of the mailserverand the most important information.
3
+
The dashboard is the main page after login. It shows an overview of the mailserver: domains, users, and quick links to common tasks.
4
4
5
5
6
+
7
+
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.
0 commit comments