Skip to content

Commit 8379fe9

Browse files
jeboehmjeboehm
committed
docs: publish documentation to github pages 🥳
1 parent 3fc6c17 commit 8379fe9

10 files changed

Lines changed: 405 additions & 99 deletions

File tree

‎.github/workflows/build.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ on:
88
pull_request:
99
paths:
1010
- ".env.dist"
11-
- ".github/**"
11+
- ".github/workflows/build.yml"
1212
- "bin/**"
1313
- "deploy/**"
1414
- "docker-compose*.yml"

‎.github/workflows/docs.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Build and deploy documentation
2+
on:
3+
push:
4+
branches:
5+
- main
6+
pull_request:
7+
paths:
8+
- "docs/**"
9+
- ".github/workflows/docs.yml"
10+
- ".mkdocs.yaml"
11+
concurrency:
12+
group: "${{ github.workflow }}-${{ github.ref }}"
13+
cancel-in-progress: true
14+
permissions:
15+
contents: write
16+
jobs:
17+
build_documentation:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6
21+
- uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6
22+
with:
23+
python-version: "3.14"
24+
cache: "pip"
25+
cache-dependency-path: docs/requirements.txt
26+
- name: Install mkdocs
27+
run: pip install -r docs/requirements.txt
28+
- name: Build documentation
29+
if: ${{ github.event_name == 'pull_request' }}
30+
run: mkdocs build --strict -f .mkdocs.yaml
31+
- name: Configure git
32+
if: ${{ github.event_name != 'pull_request' }}
33+
run: |
34+
git config --global user.name "GitHub Actions"
35+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
36+
- name: Publish documentation
37+
if: ${{ github.event_name != 'pull_request' }}
38+
run: mkdocs gh-deploy --strict --force -f .mkdocs.yaml

‎.github/workflows/release.yml‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,15 @@ jobs:
3636
run: |
3737
python3 .github/bin/update_image_tags.py "${{ steps.changelog.outputs.tag }}" --verbose
3838
echo "${{ steps.changelog.outputs.tag }}" > VERSION
39-
tar --exclude='.github' --exclude='.cursor' --exclude='.git' --exclude='renovate.json' \
40-
-czvf /tmp/release-${{ steps.changelog.outputs.tag }}.tar.gz .
39+
tar \
40+
--exclude='.github' \
41+
--exclude='.cursor' \
42+
--exclude='.git' \
43+
--exclude='.gitignore' \
44+
--exclude='.mkdocs.yaml' \
45+
--exclude='docs/requirements.txt' \
46+
--exclude='renovate.json' \
47+
-czf /tmp/release-${{ steps.changelog.outputs.tag }}.tar.gz .
4148
- name: Create GitHub Release
4249
uses: ncipollo/release-action@b7eabc95ff50cbeeedec83973935c8f306dfcd0b # v1
4350
if: ${{ steps.changelog.outputs.skipped == 'false' }}

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,5 @@
22
docker-compose.override.yml
33
/config/
44
node_modules/
5+
site/
6+
.mypy_cache

‎.mkdocs.yaml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
site_name: docker-mailserver
2+
site_description: A Dockerized mail server with a web interface for managing your email infrastructure.
3+
site_url: https://jeboehm.github.io/docker-mailserver/
4+
repo_name: jeboehm/docker-mailserver
5+
repo_url: https://github.com/jeboehm/docker-mailserver
6+
remote_branch: gh-pages
7+
theme: readthedocs
8+
markdown_extensions:
9+
- codehilite
10+
- admonition
11+
exclude_docs: |
12+
example-configs/**
13+
requirements.txt
14+
15+
nav:
16+
- Welcome: README.md
17+
- Quick Start:
18+
- INSTALLATION.md
19+
- UPGRADE.md
20+
- Configuration:
21+
- DKIM_SIGNING.md
22+
- ENVIRONMENT_VARIABLES.md
23+
- EXTERNAL_MYSQL.md
24+
- RELAYHOST.md
25+
- LOCAL_ADDRESS_EXTENSION.md
26+
- PHP_SESSIONS.md
27+
- REVERSE_PROXY.md
28+
- ROUNDCUBE.md
29+
- TLS.md
30+
- Recipes:
31+
- Docker:
32+
- Traefik Reverse Proxy: https://github.com/jeboehm/docker-mailserver/tree/main/docs/example-configs/compose/traefik-reverse-proxy
33+
- Kubernetes:
34+
- External Database and HTTPS Ingress: https://github.com/jeboehm/docker-mailserver/tree/main/docs/example-configs/kustomize/external-db-and-https-ingress
35+
- Development:
36+
- ARCHITECTURE.md
37+
- DEVELOPMENT.md
38+
- Issues: https://github.com/jeboehm/docker-mailserver/issues

‎Makefile‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,3 +122,11 @@ kind-load: build
122122
popeye-score:
123123
popeye
124124
.github/bin/popeye_score.sh
125+
126+
.PHONY: docs-build
127+
docs-build:
128+
mkdocs build --strict -f .mkdocs.yaml
129+
130+
.PHONY: docs-serve
131+
docs-serve:
132+
mkdocs serve --strict -f .mkdocs.yaml

‎README.md‎

Lines changed: 27 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -7,107 +7,45 @@ This project lets you run your own email services, giving you independence from
77

88
Container images are built on [Alpine Linux](https://alpinelinux.org) or vendor base images and are kept lightweight.
99

10-
[Changelog](https://github.com/jeboehm/docker-mailserver/releases)
11-
[Upgrade Guide](docs/UPGRADE.md)
12-
1310
[![Build & Tests](https://github.com/jeboehm/docker-mailserver/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/jeboehm/docker-mailserver/actions/workflows/build.yml)
1411

12+
## 📚 Documentation
13+
14+
**Full documentation is available at: [https://jeboehm.github.io/docker-mailserver/](https://jeboehm.github.io/docker-mailserver/)**
15+
16+
The documentation includes:
17+
18+
- Complete installation guides for Docker and Kubernetes
19+
- Configuration reference for all environment variables
20+
- Deployment examples and recipes
21+
- Architecture and development guides
22+
1523
## Features
1624

1725
- Secure email protocols: POP3, IMAP, and SMTP with user authentication
1826
- Web-based management interface for account, domain, and alias administration
19-
- Intuitive webmail interface
20-
- Fetchmail integration to retrieve emails from external providers
21-
- DKIM message signing for email authenticity
22-
- Server-side mail filtering with configurable rules via a web frontend
23-
- Spam filter training by simply moving emails to or from the junk folder
27+
- Integrated webmail interface
28+
- DKIM message signing and spam filtering with Rspamd
2429
- Real-time spam prevention using RBLs (Real-Time Blackhole Lists)
25-
- Selective greylisting for likely spam
26-
- Support for catch-all email addresses
27-
- Support for send-only accounts restricted from receiving emails
30+
- Fetchmail integration for external mail retrieval
31+
- Quota management, catch-all addresses, and send-only accounts
2832
- Restriction of sender addresses for enhanced security
29-
- Configurable address extensions using the '-' delimiter
30-
- Quota management with notifications when quotas are exceeded
31-
- Enforced TLS for secure communication
32-
- Full-text search (FTS) support for efficient message searching
33-
- Continuous self-monitoring via Docker healthcheck
34-
- Developed with a strong focus on quality assurance
33+
- Full-text search and enforced TLS
34+
- Continuous health monitoring
3535

36-
## Installation
36+
See the [documentation](https://jeboehm.github.io/docker-mailserver/) for a complete feature list.
3737

38-
### Download
38+
## Quick Start
3939

40-
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).
41-
If you are an advanced user, you can also download the source code from GitHub:
40+
Download the latest release from the [Releases](https://github.com/jeboehm/docker-mailserver/releases) page, or clone the repository:
4241

4342
```bash
4443
git clone https://github.com/jeboehm/docker-mailserver.git
4544
```
4645

47-
Do not use the `latest` container image tag for production deployments. Use a specific version instead.
48-
For example, use `jeboehm/mailserver-mta:6.3` instead of `jeboehm/mailserver-mta:latest`.
49-
50-
### Run on Docker
51-
52-
1. Copy the file `.env.dist` to `.env` and open it in a text editor.
53-
Change the variables in it according to your needs. They are described in the [docs](docs/ENVIRONMENT_VARIABLES.md).
54-
2. To download the Docker images, run `bin/production.sh pull`.
55-
3. To start the services, run `bin/production.sh up -d --wait`. This will wait for all services to be ready before continuing.
56-
4. After a few seconds, you can access the services listed in the section [Ports overview](#ports-overview).
57-
5. Start the installation wizard by running `bin/production.sh run --rm web setup.sh`. This will ask you a few questions to set everything up and create your first email address and an admin user.
58-
6. Now you can log in to the management interface with your new account credentials.
59-
60-
### Run On Kubernetes (K8s)
61-
62-
Kubernetes deployment is fully supported. You can use the `kustomization.yaml` file to deploy the mailserver to your Kubernetes cluster.
63-
64-
**Important:** Installing on Kubernetes requires an existing MySQL-compatible database (for example, MySQL or Percona XtraDB).
65-
The provided kustomization does not provision a database. Configure the database connection in your `.env` and supply
66-
credentials as Kubernetes Secrets before applying the manifests. See the
67-
[Kustomize External Database and HTTPS Ingress Example](docs/example-configs/kustomize/external-db-and-https-ingress/README.md)
68-
and the documentation [Use another MySQL instance](docs/EXTERNAL_MYSQL.md) for details.
69-
70-
1. Copy the file `.env.dist` to `.env` and open it in a text editor.
71-
Change the variables in it according to your needs. They are described in the [docs](docs/ENVIRONMENT_VARIABLES.md).
72-
2. Create a namespace for the mailserver by running `kubectl create namespace mail`.
73-
3. To create self-signed TLS certificates, run `bin/create-tls-certs.sh`. You'll need them when you don't plan to use tools like `cert-manager`.
74-
4. Create a Kubernetes secret for the TLS certificates by running `kubectl create -n mail secret tls tls-certs --cert=config/tls/tls.crt --key=config/tls/tls.key`.
75-
5. Apply the kustomize manifests by running `kubectl apply -n mail -k .`.
76-
6. When the pods are up and healthy, start the installation wizard by executing `setup.sh` in the php-fpm container of the web pod. This will ask you a few questions to set everything up and create your first email address and an admin user.
77-
7. Now you can log in to the management interface with your new account credentials on the configured ingress.
78-
79-
## Ports overview
80-
81-
| Service | Address |
82-
| ----------------------------------- | ---------------------------- |
83-
| POP3 (STARTTLS required) | 127.0.0.1:110 |
84-
| POP3S | 127.0.0.1:995 |
85-
| IMAP (STARTTLS required) | 127.0.0.1:143 |
86-
| IMAPS | 127.0.0.1:993 |
87-
| SMTP | 127.0.0.1:25 |
88-
| Mail Submission (STARTTLS required) | 127.0.0.1:587 |
89-
| Management Interface | http://127.0.0.1:81/manager/ |
90-
| Webmail | http://127.0.0.1:81/webmail/ |
91-
| Rspamd web interface | http://127.0.0.1:81/rspamd/ |
92-
93-
## Documentation
94-
95-
- [Upgrade Guide](docs/UPGRADE.md)
96-
- [Service Architecture](docs/ARCHITECTURE.md)
97-
- Installation:
98-
- [Kustomize External Database and HTTPS Ingress Example](docs/example-configs/kustomize/external-db-and-https-ingress/README.md)
99-
- [Compose Traefik Reverse Proxy Example](docs/example-configs/compose/traefik-reverse-proxy/README.md)
100-
- Configuration:
101-
- [DKIM Signing](docs/DKIM_SIGNING.md)
102-
- [Environment Variables](docs/ENVIRONMENT_VARIABLES.md)
103-
- [External MySQL](docs/EXTERNAL_MYSQL.md)
104-
- [External relay host](docs/RELAYHOST.md)
105-
- [Local Address Extension](docs/LOCAL_ADDRESS_EXTENSION.md)
106-
- [PHP Sessions](docs/PHP_SESSIONS.md)
107-
- [Reverse Proxy](docs/REVERSE_PROXY.md)
108-
- [Roundcube](docs/ROUNDCUBE.md)
109-
- [TLS](docs/TLS.md)
110-
- [Developer Guide](docs/DEVELOPMENT.md)
46+
**Important:** Do not use the `latest` container image tag for production deployments. Use a specific version instead (e.g., `jeboehm/mailserver-mta:6.3`).
47+
48+
For detailed installation instructions, see the [Installation Guide](https://jeboehm.github.io/docker-mailserver/INSTALLATION/) in the documentation.
11149

11250
## Screenshots
11351

@@ -125,16 +63,9 @@ and the documentation [Use another MySQL instance](docs/EXTERNAL_MYSQL.md) for d
12563

12664
## Links
12765

128-
- [Issues](https://github.com/jeboehm/docker-mailserver/issues)
66+
- [Documentation](https://jeboehm.github.io/docker-mailserver/) - Complete documentation and guides
67+
- [Issues](https://github.com/jeboehm/docker-mailserver/issues) - Report bugs and request features
68+
- [Releases](https://github.com/jeboehm/docker-mailserver/releases) - Release notes and changelog
12969
- Container Images:
130-
- [ghcr.io](https://github.com/jeboehm?tab=packages&repo_name=docker-mailserver)
70+
- [GitHub Container Registry](https://github.com/jeboehm?tab=packages&repo_name=docker-mailserver)
13171
- [Docker Hub](https://hub.docker.com/u/jeboehm?page=1&search=mailserver)
132-
- Components:
133-
- [dovecot](https://doc.dovecot.org/2.4.1/)
134-
- [fetchmailmgr](https://github.com/jeboehm/fetchmailmgr)
135-
- [mailserver-admin](https://github.com/jeboehm/mailserver-admin)
136-
- [postfix](https://www.postfix.org/documentation.html)
137-
- [redis](https://redis.io/docs/latest/)
138-
- [roundcube](https://docs.roundcube.net/doc/help/1.1/en_US/)
139-
- [rspamd](https://docs.rspamd.com/)
140-
- [unbound](https://unbound.docs.nlnetlabs.nl/en/latest/)

0 commit comments

Comments
 (0)