Commit graph

42 commits

Author SHA1 Message Date
Roy Sindre Norangshol deb0d2d09a
docs: Guidance for binding outbound SMTP with multiple interfaces available (#3465)
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2024-01-19 14:58:20 +13:00
Georg Lauterbach 068ceb1d1a
docs: misc improvements (#3773)
* correct misc typos

We also seem to be favoring `behavior` over `behaviour`.

* bump MkDocs version

* resolve errors shown when buildg docs

* improve the Rspamd page

* behaviour -> behavior

Streamline the usage of this word. The majority used behavior, so I
opted to go with this way of spelling it.

* Apply suggestions from code review

---------

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2024-01-16 08:38:08 +00:00
Joerg Sonnenberger e3331b0f44
feat: Add MTA-STS support for outbound mail (#3592)
* feat: add support for MTA-STS for outgoing mails

* Hook-up mta-sts-daemon into basic process handling test

* fix: Call python script directly

The python3 shebang will run it, which will now meet the expectations of the process testing via pgrep. fail2ban has the same approach.

---------

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2024-01-13 21:37:20 +13:00
Keval Kapdee 52c4582f7b
feat: Auth - OAuth2 (Dovecot PassDB) (#3480)
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2024-01-13 09:45:14 +13:00
Brennan Kinney 5e28c17cf4
docs: SpamAssassin ENV docs refactor (#3756)
* chore: Log `SPAMASSASSIN_SPAM_TO_INBOX=1` ENV correctly

ENV name logged was incomplete.

* docs: Update SA related ENV docs

* fix: Log level `warning` should be `warn`

* docs: FAQ - Revise outdated SA entry

* chore: Antispam / Antivirus => Anti-spam / Anti-virus

* docs: ENV - Additional revisions to SA ENV

* docs: ENV - Move `ENABLE_SPAMASSASSIN_KAM`
2024-01-08 03:07:38 +01:00
Jean-Kevin KPADEY cedd360ebd
docs: add a new example explaining how to integrate crowdsec with (#3651) 2023-11-25 11:02:42 +01:00
Zepmann 290355cf5a
docs: Add Dovecot Lua auth guide + required package (#3579)
* Dovecot: add deb package dovecot-lua to support Lua scripting
* Adding documentation for Lua authentication
* Updated documentation and made a better distinction between Dovecot packages for officially supported features and for community supported features.

---------

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2023-11-09 10:18:17 +13:00
René Plötz 3d5f6aeec4
docs: Add documentation for iOS mail push support (#3513)
* Add documentation for iOS mail push support

---------

Signed-off-by: René Plötz <reneploetz@users.noreply.github.com>
2023-08-30 09:40:54 +12:00
LucidityCrash 7af7546d88
feature: adding getmail as an alternative to fetchmail (#2803)
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
Co-authored-by: Georg Lauterbach <44545919+georglauterbach@users.noreply.github.com>
Co-authored-by: Casper <casperklein@users.noreply.github.com>
2023-05-23 17:25:08 +02:00
Casper 7cc05581d1
docs: Restore missing edit button (#3338) 2023-05-14 23:54:53 +02:00
Georg Lauterbach 34a1fd613f
docs: Combine DKIM/DMARC/SPF pages (#3231)
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2023-04-10 22:08:58 +12:00
Georg Lauterbach 1e20e7c332
Image registry and setup update (#3233)
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2023-04-10 11:37:25 +02:00
Georg Lauterbach 2b7cab28f7
compress & improve user management docs (#3232)
The user management docs are now one page, because the division between
accounts and aliases is useless because there simply isn't enough
content to justify the split. I improved and updated the text a bit.
2023-04-09 09:27:00 +00:00
Georg Lauterbach cf8e555212
docs: miscellaneous improvements (#3219)
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2023-04-08 11:54:16 +02:00
Georg Lauterbach 853301338c
completely refactor README & parts of docs (#3097)
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2023-02-19 13:25:14 +01:00
Georg Lauterbach 555fbb78c4
feature: provide better rspamd suppport (#3016)
* added options to toggle OpenDKIM & OpenDMARC

rspamd can provide DKIM signing and DMARC checking itself, so users
should be able to disable OpenDKIM & OpenDMARC. The default is left at
1, so users have to to opt-in when the want to disable the features.

* misc small enhancements

* adjusted start of rspamd

The order of starting redis + rspamd was reversed (now correct) and
rspamd now starts with the correct user.

* adjusted rspamd core configuration

The main configuration was revised. This includes AV configuration as
well as worker/proxy/controller configuration used to control the main
rspamd processes.

The configuration is not tested extensively, but well enough that I am
confident to go forward with it until we declare rspamd support as
stable.

* update & improve the documentation

* add tests

These are some initial tests which test the most basic functionality.

* tests(refactor): Improve consistency and documentation for test helpers (#3012)

* added `ALWAYS_RUN` target `Makefile` recipies (#3013)

This ensures the recipies are always run.

Co-authored-by: georglauterbach <44545919+georglauterbach@users.noreply.github.com>

* adjusted rspamd test to refactored test helper functions

* improve documentation

* apply suggestions from code review (no. 1 by @polarthene)

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>

* streamline heredoc (EOM -> EOF)

* adjust rspamd test (remove unnecessary run arguments)

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2023-01-25 10:28:59 +01:00
Georg Lauterbach 7eeb9c33ab
docs: add a dedicated page for tests with more information (#3019) 2023-01-24 23:10:49 +01:00
Georg Lauterbach fe2197ff7c
update contributing documentation (#2789) 2022-09-23 08:23:20 +02:00
Andrew Cornford 2f3cbfc144
feat: Support for Dovecot master accounts (#2535)
Dovecot master accounts can now be configured in DMS via `setup.sh`.
A master account is useful for administration purposes, or to perform mailbox backups of every user account over IMAP.
Upstream Docs: https://doc.dovecot.org/configuration_manual/authentication/master_users/

Co-authored-by: Casper <casperklein@users.noreply.github.com>
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2022-05-08 00:28:32 +02:00
wolkenschieber d858669dd4
Update README.md (#2425)
Co-authored-by: casperklein <casperklein@users.noreply.github.com>
2022-02-21 12:05:39 +01:00
Frederic Werner 358df6ada2
docs(deps): bump mkdocs-material to v8.2.1 (#2422)
* docs(deps): bump mkdocs-material to v8.2.1

* feat(docs): enable mermaid integration

Configuration based on https://squidfunk.github.io/mkdocs-material/reference/diagrams/?h=mermaid#configuration

* fix: allow yaml value mapping

* chore: Adopt mkdocs-material mermaid integration support

Supported by the docs generator now, we no longer need to rely on external image generator or live editor link (both relied on large base64 encoding of mermaid markup). SVG will be rendered by docs now, although a little different style (can be fixed with custom CSS).

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2022-02-19 21:26:56 +01:00
Frederic Werner 7f731ebca0
docs(deps): bump mkdocs-material to new major version 8 (#2311)
* docs(deps): bump mkdocs-material to 8.0.2

* docs(deps): bump mkdocs-material to 8.0.3

* chore: add default version of docs

* feat: add version warning

* fix: remove version warning

* docs(deps): bump mkdocs-material to 8.0.5

* added code annotation feature

We can introduce new annotation with new PRs in the future. I'd advise against overhauling all code blocks with this feature in this PR - this PR should just introduce the feature.

* docs(deps): bump mkdocs-material to 8.1.0

* fix: remove unnecessary default value

re-add if version warning gets a thing in the future. See https://github.com/docker-mailserver/docker-mailserver/pull/2311#issuecomment-991805830

Co-authored-by: Georg Lauterbach <44545919+georglauterbach@users.noreply.github.com>
2021-12-13 08:43:01 +01:00
Michael Jensen 88a1619dd5
document pre-docker build command (#2164)
Co-authored-by: Georg Lauterbach <44545919+georglauterbach@users.noreply.github.com>
2021-09-27 09:01:41 +02:00
Brennan Kinney a0ee472501
docs(chore): Normalize for consistency (#2206)
"Brief" summary/overview of changes. See the PR discussion or individual commits from the PR for more details.

---

Only applies to the `docs/content/**` content (_and `setup` command_). `target/` and `test/` can be normalized at a later date.

* Normalize to `example.com`

- Domains normalized to `example.com`: `mywebserver.com`, `myserver.tld`, `domain.com`, `domain.tld`, `mydomain.net`, `my-domain.tld`, `my-domain.com`, `example.org`, `whoami.com`.
- Alternative domains normalized to `not-example.com`: `otherdomain.com`, `otherdomain.tld`, `domain2.tld`, `mybackupmx.com`, `whoareyou.org`.
- Email addresses normalized to `admin@example.com` (in `ssl.md`): `foo@bar.com`, `yourcurrentemail@gmail.com`, `email@email.com`, `admin@domain.tld`.
- Email addresses normalized to `external-account@gmail.com`: `bill@gates321boom.com`, `external@gmail.com`, `myemail@gmail.com`, `real-email-address@external-domain.com`.
- **`faq.md`:** A FAQ entry title with `sample.domain.com` changed to `subdomain.example.com`.
- **`mail-fetchmail.md`:** Config examples with FQDNs for `imap`/`pop3` used `example.com` domain for a third-party, changed to `gmail.com` as more familiar third-party/external MTA.

* Normalize config volume path

- Normalizing local config path references to `./docker-data/dms/config/`: `./config/`, `config/`, \``config`\`, `/etc/` (_volume mount src path prefix_).
- Normalize DMS volume paths to `docker-data/dms/mail-{data,state,log}`: `./mail`, `./mail-state` `./data/mail`, `./data/state`, `./data/logs`, `./data/maildata`, `./data/mailstate`, `./data/maillogs`, (_dropped/converted data volumes: `maildata`, `mailstate`_).
- Other docker images also adopt the `docker-data/{service name}/` prefix.

* `ssl.md` - Use `dms/custom-certs` where appropriate.

* Apply normalizations to README and example `docker-compose.yml`

---

Common terms, sometimes interchangeably used or now invalid depending on context: `mail`, `mail container`, `mail server`, `mail-server`, `mailserver`,`docker-mailserver`, `Docker Mailserver`.

Rough transformations applied to most matches (_conditionally, depending on context_):

- 'Docker Mailserver' => '`docker-mailserver`'
- 'mail container' => '`docker-mailserver`' (_optionally retaining ' container'_)
- 'mail server' => 'mail-server' / '`docker-mailserver`'
- 'mail-server' => '`docker-mailserver`'
- 'mailserver' => 'mail-server' / '`docker-mailserver`'

Additionally I checked `docker run` (_plus `exec`, `logs`, etc, sub-commands_) and `docker-compose` commands. Often finding usage of `mail` instead of the expected `mailserver`

Additionally changes `mailserver` hostname in k8s to `mail` to align with other non-k8s examples.

---

* drive-by revisions

Mostly minor revisions or improvements to docs that aren't related to normalization effort.
2021-09-23 11:29:37 +12:00
Orville Q. Song ddd97274e0
feat: rootless Podman with documentation (#2179)
Co-authored-by: Georg Lauterbach <44545919+georglauterbach@users.noreply.github.com>
2021-09-19 18:55:51 +02:00
Brennan Kinney f8a621dadb
docs(fix): Update external registry links (#2186) 2021-09-13 07:03:40 +00:00
Georg Lauterbach c7e4981945
Move setup process via script into container (#2174)
Decoupling setup process from `setup.sh` script by introducing a setup script _inside_ the container that coordinates the setup process.

**This is not a breaking change**. This way, we do not have to keep track of versions of `setup.sh`.

This change brings the additional benefit for Kubernetes users to be able to make use of `setup` now, without the need for `setup.sh`.

---

* move setup process into container; setup.sh versioning not needed anymore

* add tilde functionality to docs

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
Co-authored-by: Casper <casperklein@users.noreply.github.com>
2021-09-12 11:29:02 +12:00
Frederic Werner f33374023f
docs: add blog posts section (#2107)
* docs: add blog posts section

* docs: add blog posts site
2021-07-30 13:38:46 +02:00
hnws 630e083c9a
docs: Add example for customizing IMAP folders (#2045)
* docs: Add example for customizing IMAP folders (mailboxes)

* chore: Update `15-mailboxes.conf` to sync with upstream

This config has not been updated since 2016 (ignoring the Junk autosubscribe addition).

Synced to upstream equivalent at https://github.com/dovecot/core/blob/master/doc/example-config/conf.d/15-mailboxes.conf

Retains the `Archive` example definition from this PR and prior `auto = subscribe` additions.

---

Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2021-06-23 10:28:43 +12:00
Brennan Kinney cf22475382
docs(ci): Deploy Previews (#1988)
* docs(ci): Support deploy previews for documentation

Each PR that contributes to docs will generate a unique (to that PR) URL to preview the PR live for review.

* docs(ci): Split workflow

To support previews from non-collaborators PR contributions, we cannot rely on secrets access from workflows triggered by the `pull_request` event.

To do so securely, according to official advice from Github, we must run the third-party contribution in the restricted `pull_request` context, and then use a 2nd workflow to deploy the build (which requires secrets access).

* docs(ci): Rename doc workflows + add commit status

Better naming convention for documentation workflows.

Split workflow only indicated status on PR of the 1st stage (building the preview to deploy), not the deployment progress/result. This needs to be managed more directly until the action better supports split-workflow scenario.

* docs(ci): Add concurrency limit to preview deploy workflow

This would be more ideal on the 2nd phase workflow (`workflow_run`), however keeping it simple for now.

Limits the concurrency of the initial pull request workflow for documentation contributions that have PRs with multiple event triggers in a small time span (before the workflow triggered would complete). The main benefit is to avoid redundant deploys if the initial workflow has been triggered again to build the PR once more. It only will work against concurrent workflows for that PR in the 1st stage, if an existing `workflow_run` (2nd stage) is active for that PR it will not be cancelled.

* docs(ci): Add sponsor branding for deploy preview service

A requirement from Netlify for the [sponsored OSS organization plan](https://www.netlify.com/legal/open-source-policy).

* docs(ci): Use a shared build script

Production and Deploy Preview builds are now maintained via the same shell command, so version updates of docker image is in one place.

Additionally deletes unnecessary build output which upstream provides no support to exclude.

* docs: Add a custom 404 page

This is used by the preview deploys on Netlify. Production deploys on Github Pages require a top-level 404 page manually deployed (since all are deployed to a version subpath).

This 404 page was custom built and optimized by me. This is the final minified output, separate source to build is available if needed.

---

Likewise the `favicon.ico` is a fallback for browsers that implicitly check the domain root for this file if the SVG isn't supported/preferred. Browsers check for this file without it being present in the HTML head meta elements.

On Github Pages the `favicon.ico` isn't likely to be picked up by even top-level as typical deployment has the project name as a subpath. The docs however reference a PNG favicon which should be widely supported.

The `favicon.ico` was generated by RealFaviconGenerator online tool with SVG source input. It contains 16px, 32px and 48px sizes. Quality is better than the `favicon.io` generator.

* chore: Optimized logo

SVG source cleaned up and optimized with SVGO 2.3.

Minified versions (`.min.svg` extension) remove unnecessary data and white-space to reduce size further for production use. This extension better differentiates by filename that it's different from the `src` version.
2021-05-20 22:24:46 +12:00
Georg Lauterbach 5449efd8d4
chore(docs): outsourcing environment vars to the documentation (#1948)
Co-authored-by: Frederic Werner <20406381+wernerfred@users.noreply.github.com>
Co-authored-by: Casper <casperklein@users.noreply.github.com>
Co-authored-by: Brennan Kinney <5098581+polarathene@users.noreply.github.com>
2021-05-11 22:15:34 +12:00
Frederic Werner c6dd79dbca
docs: include mail_crypt (#1916) 2021-04-18 02:12:36 +02:00
Frederic Werner b60b294be1
docs: minor adjustments (#1889)
* docs: add version to mkdocs docker image

* docs: add version tag to build image

* feat(docs): add back-to-top button

* feat(docs): add back-to-top button

* feat(docs): add dark theme
2021-04-08 12:27:37 +02:00
Georg Lauterbach 65622c56e9
Better incorporate the new, great documentation (#1878) 2021-04-02 09:44:31 +13:00
polarathene bbaca9a468 docs(config): Tidy up and better document mkdocs.yml 2021-03-25 11:49:24 +13:00
wernerfred 724fe72d20 docs: Update metadata and links to new locations
Also removed the FAQ inline heading link for Rancher. It's not a relevant link (as the question already expects knowledge of Rancher), and breaks out of the bg colour heading style due to the HTML generation logic from mkdocs.
2021-03-25 11:49:24 +13:00
wernerfred 237a932f8e docs(config): Add the nav section
Various PR commits related to the nav section have been merged together:

docs: Fix indentation for linter check
docs: update edit uri to content subdirectory
docs: add ghcr link
docs: shorten nav entry name
docs: quote ghcr nav entry
docs(config): update nav section for relocated documents

Additional nav section fixes:

- consistent usage of quotes
- eclint padding error
- wrong indentation of pop3
- remove a leading slash from a filepath
2021-03-25 11:49:24 +13:00
polarathene 021e942c4c docs(refactor): Large refactor + additions + fixes
Consistency pass, formatting cleanup and fixes, introduce admonitions, add front-matter.

---

docs: Add front-matter

---

docs: Fix and format links

- Some links were invalid (eg files moved or renamed)
- Some were valid but had invalid section headers (content removed or migrated)
- Some use `http://` instead of `https://` when the website supports a secure connection.
- Some already used the `[name][reference]` convention but often with a number that wasn't as useful for maintenance.
- All referenced docs needed URLs replaced. Opted for the `[name][reference]` approach to group them all clearly at the bottom of the doc, especially with the relative URLs and in some cases many duplicate entries.
- All `tomav` references from the original repo prior to switch to an organization have been corrected.
- Minor cosmetic changes to the `name` part of the URL, such as for referencing issues to be consistent.
- Some small changes to text body, usually due to duplicate URL reference that was unnecessary (open relay, youtous)
- Switched other links to use the `[name][reference]` format when there was a large group of URLs such as wikipedia or kubernetes. Github repos that reference projects related to `docker-mailserver` also got placed here so they're noticed better by maintainers. This also helped quite a bit with `mermaid` external links that are very long.
- There was a Github Wiki supported syntax in use `[[name | link]]` for `fetchmail` page that isn't compatible by default with MkDocs (needs a plugin), converted to `[name][reference]` instead since it's a relative link.

---

docs: Update commit link for LDAP override script

Logic moved to another file, keeping the permalink commit reference so it's unaffected by any changes in the file referenced in future.

---

docs: Heading corrections

Consistency pass. Helps with the Table of Contents (top-right UI) aka Document Outline.
docs: codefence cleanup

---

docs: misc cleanup

---

docs: Add Admonitions

Switches `<details>` usage for collapsible admonitions (`???`) while other text content is switched to the visually more distinct admoniton (`!!!` or `???+`) style.

This does affect editor syntax highlighting a bit and markdown linting as it's custom non-standard markdown syntax.
2021-03-25 11:49:24 +13:00
polarathene f13df19b87 docs(styles): Add external link icon workaround
Adds some third-party CSS as`mkdocs-material` doesn't seem interested in a PR to upstream this feature to the community.

---

Uses a font icon approach for the external link as alternatives like SVG was reported in PR as breaking on Chrome.

The logo has been made larger than theme default, it needs a little push from the left to align well with the tabs below it.

---

Unrelated: Additionally experiment with the Instant Navigation feature.

---

docs(styles): Various improvements

Multiple related commits from original PR have been squashed into this. Some messages may be redundant due to loss of history.

---

docs(styles): Minor improvements

- Use relative path for external-link
- UI enhancement for version selector
- Improve inline documentation for `customizations.css`

Make separate styling sections more evident (since we're not using multiple files or build tools).

---

docs(styles): Replace permalink to fix UX bug

---

docs(styles): Replace permalink feature for alternative approach

Previous commit already switched `permalink` for `anchorlink` option, but the `#` symbol had UI concerns regarding font-size/scale and fitting into the gutter.

Gutter change reverted, switch to REM units and symbol replaced by thin vertical rectangle scaled by font height, far better consistency for placement.

---

docs(styles): Refactor the heading link style

Effectively ended up making a border-left line style, just not as consistent and more complicated. Fixed that by adjusting styles.

Adds optional background fill and restores inline code style for headings.
2021-03-25 11:49:24 +13:00
polarathene 251a87e622 docs(ci): Add versioning support without using 'mike'
It seems it may have be simpler to just use 'mike'..

Additionally squashes related commits providing minor fixes + improvements:

- Use a job dependency (`needs`) to avoid `push` event race conditions due to parallel jobs.
- Improve workflow file documentation via inline comments.
- Make ShellCheck linting happy.
- `chown` doesn't seem to work unless on the default branch for CI. Opted to use the docker `--user` approach instead.
2021-03-25 11:49:24 +13:00
polarathene 48cf6ffeb0 docs(assets): Add SVG logo and ICO favicon.
Adds the SVG logo I created (composited rather) in mid-feb in one of my PRs that went slightly off-topic about migrating docs from Github Wiki.

Enables the logo and favicon in `mkdocs.yml`. SVG sources for both full colour and simplified monochromatic are included along with PNG images for use anywhere else, such as the organization logo.

The two SVG of the same names from `src` dir, are used by the docs and have been processed through SVGOMG, an SVG file size optimizer. Any future modifications should use the source files.
2021-03-25 11:49:24 +13:00
polarathene b6d8ce371c docs(config): Add initial mkdocs.yml config 2021-03-25 11:49:24 +13:00