Commit graph

2445 commits

Author SHA1 Message Date
wernerfred 1a8552b96c docs(refactor): Restructure document hierarchy
Additionally rename `installation-examples.md` and split
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 95983cbebc docs(ci): Add workflow to build and deploy docs
Separate workflows for `push` and `pull_request` events. This avoids a `skipped` job status (`Check Run`?) always being presented for the `deploy` job in Pull Requests.

---

chore(`.gitignore`): Ignore the `docs/site/` build output

Ignore to avoid local builds output appearing in git as unstaged.
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
Georg Lauterbach 4afebda64d
fix for #1808 (#1864) 2021-03-24 20:42:00 +01:00
Stephan c214cba981
Make directory with parent directories (#1862) 2021-03-23 13:50:29 +00:00
Casper b26ad3409b
Update bug_report.md (#1860) 2021-03-23 13:24:09 +00:00
Casper b39b5c633c
yaml base-60 float warning added (#1859) 2021-03-23 14:22:40 +01:00
Casper b46e48f278
Use timezone from host (#1852) 2021-03-14 20:45:08 +01:00
Semir Patel 4b9328b23e
Fix update docs to use setup.sh help (#1851) 2021-03-13 19:55:32 +01:00
Casper 37770c5618
comment updated 2021-03-13 15:48:02 +01:00
Georg Lauterbach 4ba2315058
corrected dkim keysize argument in help pages, closing #1845 2021-03-10 11:21:24 +01:00
Casper df54750d02
Typo fixed 2021-03-02 21:49:55 +01:00
Frederic Werner 55daef4820
Merge pull request #1827 from polarathene/docs/migrate-docs
docs: Migrate wiki docs to main repo
2021-02-28 12:04:38 +01:00
Georg Lauterbach 941e7acdae
fix variable expansion in ERR trap for setup.sh 2021-02-27 14:26:04 +01:00
polarathene b84dfb3e6d docs: Migrate wiki docs into main repo
Migrating Github Wiki docs into the main repo with the following commands:

```sh
# Clone the two repositories to combine:
git clone https://github.com/docker-mailserver/docker-mailserver
git clone https://github.com/docker-mailserver/docker-mailserver.wiki

# Navigate to repository we want to migrate files from.
# `git-filter-repo` relocates the wiki docs from project root to sub-directory, while retaining author commit history:
cd docker-mailserver.wiki
git-filter-repo --path-rename ':website/docs/'

# Switch to main repo, create a branch for PR, add the other local repo as a remote:
cd ../docker-mailserver
git checkout -b docs/migrate-docs
git remote add wiki-local ../docker-mailserver.wiki

# Transfer the remotes files with commit history in tact to main repo:
# `git pull` to perform `git fetch` and `git merge` together.
git pull wiki-local master --allow-unrelated-histories
```

Note: Above command is roughly accurate but has been modified, see PR for this commit for more details.
2021-02-26 17:08:25 +13:00
Georg Lauterbach 3c664952b3
Update README to v9.0.1 2021-02-25 11:26:56 +01:00
Georg Lauterbach 0d9fb096b7
adjusting _seup_supervisor to not restart when wrong log-level given 2021-02-25 10:57:20 +01:00
Georg Lauterbach 0fa5c1ef9d
revamping the notify function (#1836) 2021-02-24 17:28:59 +01:00
Georg Lauterbach 1ef66fd5c5
first (may-be) fixes for v9.0.0 startup problems (#1835)
* first (may-be) fixes for v9.0.0 startup problems
* adjust grep showing an error when it shouldn't
2021-02-24 10:12:20 +01:00
wernerfred 365ecf5935 chore: prepare v9.0.0 2021-02-23 21:29:09 +01:00
Georg Lauterbach c881facbd2
start-mailserver.sh split (#1820)
* splitting start-mailserver.sh

* refactoring part 2

* refactored setup-stack.sh
* stzarted adjusting target/bin/*.sh to use new usage format

* corrected lowercase-uppercase test error

* better handling of .bashrc variable export

* linting tests and fix for default assignements

* last stylistic changes and rebase
2021-02-23 20:03:01 +01:00
Casper 2262d354db
Merge pull request #1832 from docker-mailserver/casperklein-patch-1
install_linters improved
2021-02-23 20:02:04 +01:00
Casper 16d3988a73
formatting fixed 2021-02-23 16:56:30 +01:00
Casper b2a091aa85
install_linters improved 2021-02-23 16:49:00 +01:00
Georg Lauterbach b4b4538bd3
Merge pull request #1831 from ap-wtioit/master-install_linters_without_sudo
linting: use local scripts to remove sudo need
2021-02-23 16:18:32 +01:00
Andreas Perhab 9df60f62ce linting: use local scripts to remove sudo need
install linting tools locally to remove the need for
sudo curling scripts and installing them for all users
2021-02-23 14:45:06 +01:00
Georg Lauterbach 73ca77e7df
Merge pull request #1830 from landergate/patch-1 2021-02-22 23:27:55 +01:00
landergate a8d7d1802b
Fixed REPORT_RECIPIENT=1 behavior
Condition never matched, so reports were sent to 1@ instead of postmaster@
2021-02-23 00:17:01 +03:00
Casper c1a6bd9d3d
Merge pull request #1823 from polarathene/chore/consistent-sed-delimiters
chore: Use consistent `sed` substitution delimiters in `start-mailserver.sh`
2021-02-22 00:36:44 +01:00
Casper ea307c7178
Merge pull request #1822 from docker-mailserver/casperklein-patch-1
Remove fix-missing
2021-02-22 00:13:44 +01:00
polarathene 867cac6707 chore: Consistent sed substitution delimiter +
This additionally converts `+` delimited to `|` standardizing it throughout the file.
2021-02-22 11:59:59 +13:00
polarathene 75aefa3bdf chore: Consistent sed substitution delimiter
My `~` substitution and any usage of `/` within `start-mailserver.sh` has been replaced with the `|` delimiter instead as advised for matching style guide preference. Note there are other `sed` substitution delimiters still in use such as `+`.

Also added warning for empty `SSL_TYPE` ENV var that may result in an internal state config persist bug when changing `SSL_TYPE` depending on how a container is restarted.
2021-02-22 11:55:10 +13:00
Brennan Kinney d02ebc922c
Dual certificate support (eg ECDSA with RSA fallback) (#1801)
* feat: Change Postfix smtpd_tls key and cert files to chain_files

Since Postfix 3.4, `smtpd_tls_cert_file` and `smtpd_tls_key_file` have been deprecated in favor of `smtpd_tls_chain_files` which supports a list of values where a single or sequence of file paths provide a private key followed by it's certificate chain.

* feat: Dual certificate support

`smtpd_tls_chain_files` allows for multiple key+cert bundles so that you can provide different key types, such as ECDSA and RSA.

To maintain compatibility with the current CERT/KEY ENV vars only a 2nd certificate is supported.

Since Dovecot 2.2.31 a related feature is also available, but it is limited to only providing one alternative certificate via separate cert and key settings.

---

This feature enables support for multiple certificates, eg for serving modern ECDSA certs with RSA as fallback.

* chore: Refactor variable names to meet style guide

Improved some comments too.

* chore: Have function definitions respect style guide

* chore: Minor edits to comments

* chore: Expand on comments for maintenance, alert of insecure config

When `SSL_TYPE` isn't properly setup, we're still offering SSL connections but not warning in logs about the insecurity of such, or why a misconfiguration may have occurred.

This commit more clearly communicates to the user that they should look into the issue before considering deploying to production.

The `TODO` comments communicate to any future maintainer to consider treating these improper configs as disabling TLS instead.

* fix: Use `snakeoil` cert

I mistakenly thought this was placeholder text, which broke some tests. This adds the two files in the correct order (private key followed by cert/chain), to fix that issue.

* fix: Disable alt cert for Dovecot if necessary

Certain scenarios may persist state of previously configured alt cert via ENV vars that are removed from a future run. If the config is not reset to original immutable state, this will correctly disable the config from using alt cert unintentionally.

* fix: Satisfy ShellCheck lint

By switching from string var to array / list expansion, this better stores the extracted result and applies it in a manner that ShellCheck linting approves, removing the need to disable the rule.

* feat: Support dual cert test

Few tweaks to the test script allows re-purposing it for covering dual cert support as well.

* chore: Rearranged cert and key lines

A little reorganization, mostly placing private key ahead of related cert lines.

* chore: Refactor `_set_certificate`

This should make the parameters a little less confusing.

Previously was 3 parameters, but the Postfix parameter (1st) may look like two variables if you don't pay attention to the surrounding quotes; while the Dovecot parameters (2nd + 3rd) would have an opposing order. There was also a variant where the `FULLKEYCHAIN` var was passed in three times.

Now it's two params, with the 2nd param as an optional one. If the 2nd param is provided, then the two params are in the order of private key then certificate, otherwise if only a single parameter it's a single PEM file with the full cert chain and private key bundled.

This avoids implying that Postfix and Dovecot might use different files.

* chore: Document current state of `SSL_TYPE` logic better

Inlined for the benefit of anyone else maintaining this section if I'm unable to address the concerns within my own time.

* docs: ENV vars

`TLS_LEVEL=old` isn't in the codebase anymore, not likely to be relevant to retain.

No point in documenting what is considered invalid / unsupported config value in the first place for `SSL_TYPE`.

`SSL_TYPE=manual` was missing documentation for both related file path ENV vars, they've been added along with their alt fallback variants.

* chore: Update Dovecot LMTP SSL test config

Not sure how relevant this is, the file isn't complete sync with the main dovecot `10-ssl.conf` config, adding the support just in case.

* chore: Rename `FULLKEYCHAIN` to avoid confusion

There doesn't appear to be a standardized name for this type of file bundle, and `keychain` may be misleading (fullkeychain often provides macOS keychain  results on search engines).

Opting for a more explicit `KEY_WITH_FULLCHAIN` name instead.

* fix: Invalid var name

`_set_certificate` refactor commit accidentally changed a var name and committed that breaking the dual cert support (thanks tests!).

* test: Refactor `mail_ssl_manual.bats`

Proper test return values instead of `wc -l` based checking.

Tests with dual cert support active, tests that feature (to better detect failure case.

Third test case was unable to verify new self-signed certificate, added new certs signed with self-signed root CA.

Adjusted openssl `CApath` parameter to use `CAfile` instead as `letsencrypt` cert was replaced thus CA cert is missing from the system trust store.

* test: Properly check for files in `mail_ssl_manual.bats`

Fixes lint error.

Also realized I was accidentally asserting a file exists in the test environment, not within the container.

Resolved that and also added an additional test case to ensure the ENV var files are valid when passed in, in the event a change misconfigures them and that the issue is identified earlier.

* chore: Apply PR review feedback

Better format some strings that had mixed quotes when they weren't necessary.

Additionally DRYed up the config path for Postfix and Dovecot within the `_setup_ssl` method.

Co-authored-by: Georg Lauterbach <infrastructure@itbsd.com>
2021-02-21 23:43:41 +01:00
Casper 2740e0fa0c
Remove fix-missing 2021-02-21 23:36:09 +01:00
Astro a7ecb0ea8b
feat/enable custom dkim selector (#1811)
* let dkim generator accept selector as parameter

* test dkim-generator with selector parameter

* fix: correct name of domain argument in usage

* fix: adapt command to new syntax

* tests: use different quotes

* tests: use different quotes

* tests: remove domains that were never added

* style: change test name

* refactor: dkim setup

* style: remove trailing whitespace

* tests: remove test of removed dummy file

Co-authored-by: Frederic Werner <20406381+wernerfred@users.noreply.github.com>
2021-02-21 22:05:35 +01:00
Georg Lauterbach 9efa94ce6f
follow up on ed1bd0cc24 2021-02-19 10:37:28 +01:00
Georg Lauterbach ed1bd0cc24
making 'using the correction version of setup.sh' even clearer 2021-02-19 10:29:26 +01:00
Frederic Werner 788d718fa0
Add manual workflow trigger 2021-02-18 22:56:13 +01:00
Frederic Werner d182d65377
fix: dkim help message test (#1817) 2021-02-18 22:55:17 +01:00
Frederic Werner 6e6b5be1ee
chore: change argument name and parameter shift 2021-02-18 19:20:48 +01:00
Georg Lauterbach d221c585c2
inform about proper setup.sh usage between versions 2021-02-18 14:01:01 +01:00
Georg Lauterbach f3f38db0f9
adjust test to use new script output from openDKIM 2021-02-18 13:11:45 +01:00
Georg Lauterbach 27f6ad73cf
re-write setup.sh's help message to use the new style (#1814) 2021-02-18 11:09:29 +01:00
Georg Lauterbach 6e7ef698d4
re-enable test in Makefile 2021-02-18 10:40:35 +01:00
Georg Lauterbach 1005bb3b09
Provide complete refactoring of openDKIM script (#1812)
* provide complete refactoring of openDKIM usage and tests

* fix leftover linting errors

* correct defualt key size and README usage

* provide independent order for arguments

* added `config` and adjusted usage information

* fixing shift in setup.sh

* adjust usage information to use new style and rename script

* use updated argument keysize instead of size
2021-02-18 10:29:34 +01:00
Brennan Kinney 432f96b3a6
Use best practice cipher suites for 2021 (#1802)
Update cipherlist to sync with OWASP B and Mozilla Intermediate
2021-02-18 10:24:34 +01:00