docs: Improve documentation with quick start guide and clarifications (#705)

Author: jeboehm

README.md

@@ -41,11 +41,37 @@ The documentation includes:
 
 See the [documentation](https://jeboehm.github.io/docker-mailserver/) for a complete feature list.
 
+## Quick start
+
+```bash
+# 1. Clone the repository or download a release
+git clone https://github.com/jeboehm/docker-mailserver.git
+cd docker-mailserver
+
+# 2. Copy and edit the environment file (set passwords for MYSQL_PASSWORD,
+#    REDIS_PASSWORD, CONTROLLER_PASSWORD, and DOVEADM_API_KEY)
+cp .env.dist .env
+
+# 3. Pull images and start services
+bin/production.sh pull
+bin/production.sh up -d --wait
+
+# 4. Create the first email account and admin user
+bin/production.sh run --rm web setup.sh
+```
+
+After setup, access the management interface at
+`http://127.0.0.1:81/manager/` and webmail at `http://127.0.0.1:81/webmail/`.
+
+For a complete walkthrough, see the
+[Getting Started tutorial](docs/tutorials/getting-started.md).
+
 ## Setup
 
 `docker-mailserver` can be set up using Docker or Kubernetes.
 
-For detailed installation instructions, see the [Installation Guide](https://jeboehm.github.io/docker-mailserver/installation/) in the documentation.
+For detailed installation instructions, see the
+[Installation Guide](docs/installation.md).
 
 ## Screenshots
 

docs/README.md

@@ -13,7 +13,7 @@ This project enables you to operate your own email services, providing independe
 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.
+- **How-to guides** — Task-oriented guides for specific goals: [install with Docker](how-to/install-docker.md), [install on Kubernetes](how-to/install-kubernetes.md), [configure DNS](how-to/configure-dns.md), [configure TLS](how-to/configure-tls.md), [manage users](how-to/manage-users.md), and more.
 - **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).
 

docs/how-to/configure-tls.md

@@ -1,6 +1,8 @@
 # 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.
+This guide covers TLS for mail protocols (SMTP, IMAP, POP3) served by the MTA (Postfix) and MDA (Dovecot) containers. To terminate TLS for the web interface (port 81), use a reverse proxy — see [How to configure a reverse proxy](configure-reverse-proxy.md).
+
+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
 

docs/how-to/install-docker.md

@@ -2,11 +2,13 @@
 
 This guide describes how to install docker-mailserver using Docker Compose.
 
+If you are setting up docker-mailserver for the first time, the [Getting Started tutorial](../tutorials/getting-started.md) provides a step-by-step walkthrough that covers these same steps with more explanation.
+
 ## Prerequisites
 
-- Docker and Docker Compose
-- Domain name with DNS configured
-- Basic familiarity with email server administration
+- Docker and Docker Compose installed on the host
+- A domain name
+- Root or sudo access on the host
 
 ## Steps
 

docs/how-to/install-kubernetes.md

@@ -1,8 +1,10 @@
 # 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.
+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).
+A full example is in [example-configs/kustomize/external-db-and-https-ingress](../example-configs/kustomize/external-db-and-https-ingress/).
 
 ## Prerequisites
 
@@ -12,9 +14,16 @@ A full example is in [example-configs/kustomize/external-db-and-https-ingress](h
 
 ## Steps
 
-### 1. Configure environment (ConfigMap)
+### 1. Configure environment (ConfigMap and Secrets)
 
-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).
+Use `.env.dist` as a reference for required variables. Create a Kubernetes
+ConfigMap for non-sensitive values and Secrets for sensitive values
+(credentials, passwords, API keys). See [Environment variables reference](../reference/environment-variables.md) for the full list.
+
+See the
+[example-configs/kustomize/external-db-and-https-ingress](../example-configs/kustomize/external-db-and-https-ingress/)
+directory for a sample configuration showing how to structure these
+resources.
 
 ### 2. Create namespace
 
@@ -28,6 +37,10 @@ kubectl create namespace mail
 bin/create-tls-certs.sh
 ```
 
+This writes a self-signed certificate to `config/tls/tls.crt` and key to
+`config/tls/tls.key`. For production, use CA certificates (e.g.
+cert-manager with Let's Encrypt) instead.
+
 ### 4. Create TLS secret
 
 ```bash
@@ -58,13 +71,24 @@ Wait until all pods are running and healthy.
 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.
+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).
+- Configure DNS and TLS like Docker deployment. 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+).
+
+## Troubleshooting
+
+- **Pods not starting:** Check logs with `kubectl logs -n mail <pod-name>`
+  and events with `kubectl describe pod -n mail <pod-name>`.
+- **Database errors:** Verify database connectivity and that the
+  `MYSQL_*` variables in ConfigMap/Secrets are correct.
+- **TLS errors:** Confirm the `tls-certs` secret exists in the `mail`
+  namespace and certificate paths are correct.
+- **Setup wizard fails:** Ensure the web pod is running (`kubectl get pods -n mail`) before running the exec command.

docs/reference/environment-variables.md

@@ -44,16 +44,18 @@ When using the Redis service provided by docker-mailserver compose or kustomize,
 
 ### Relay
 
-| Variable            | Default | Description                       |
-| ------------------- | ------- | --------------------------------- |
-| `RELAYHOST`         | `false` | SMTP relay host for outgoing mail |
-| `RELAY_PASSWD_FILE` | `false` | Path to relay authentication file |
+Set `RELAYHOST` to `[hostname]:port` to route all outgoing mail through an external SMTP server. Leave unset to deliver directly.
+
+| Variable            | Default      | Description                                                       |
+| ------------------- | ------------ | ----------------------------------------------------------------- |
+| `RELAYHOST`         | _(disabled)_ | SMTP relay host for outgoing mail (e.g. `[smtp.example.com]:587`) |
+| `RELAY_PASSWD_FILE` | _(disabled)_ | Path to relay authentication file (inside the MTA container)      |
 
 ### Filter
 
-| Variable      | Default | Description                  |
-| ------------- | ------- | ---------------------------- |
-| `FILTER_MIME` | `false` | Enable MIME header filtering |
+| Variable      | Default      | Description                  |
+| ------------- | ------------ | ---------------------------- |
+| `FILTER_MIME` | _(disabled)_ | Enable MIME header filtering |
 
 ## Extended Configuration
 

docs/reference/ports.md

@@ -13,3 +13,9 @@ Services and ports exposed by docker-mailserver.
 | 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/  |
+
+## Binding and exposure
+
+The base `docker-compose.yml` creates no host port bindings. `bin/production.sh` includes `docker-compose.production.yml`, which binds all mail and web ports to `0.0.0.0` — making them accessible from the internet. Use host firewall rules to control which source IPs can reach these ports.
+
+The management interface, webmail, and Rspamd web interface (port 81) use plain HTTP. Terminate TLS at a reverse proxy before exposing these to a network. See [How to configure a reverse proxy](../how-to/configure-reverse-proxy.md).

docs/tutorials/getting-started.md

@@ -36,6 +36,8 @@ Edit `.env` and set at least:
 - `CONTROLLER_PASSWORD` (required for Rspamd)
 - `DOVEADM_API_KEY` (required for Dovecot API)
 
+Use strong, unique values for each password — do not leave them empty or use the same value for all. These credentials protect internal service communication.
+
 For a full list of variables, see [Environment variables reference](../reference/environment-variables.md).
 
 ## Step 3: Pull and start services
@@ -73,6 +75,8 @@ Open a browser and go to:
 
 Log in with the admin credentials you set in the wizard. You should see the dashboard.
 
+> **Note:** Port 81 uses plain HTTP. For production, place the mailserver behind a reverse proxy that terminates TLS. See [How to configure a reverse proxy](../how-to/configure-reverse-proxy.md).
+
 ## 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.