Merge branch 'master' of github.com:mailcow/mailcow-dockerized-docs

.github/workflows/gh-pages.yml

@@ -0,0 +1,27 @@
+name: Build and deploy to gh-pages
+on:
+   push:
+     branches:
+       - master
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout 📥
+        uses: actions/checkout@v2.3.4
+
+      - name: Install dependencies 🐄
+        run: |
+          sudo apt-get -y update
+          sudo apt-get -y install python3-pip
+          pip install mkdocs-material pygments==2.8.1 mkdocs-redirects
+
+      - name: Build site 🔧
+        run: |
+          mkdocs build --verbose --clean
+
+      - name: Deploy 🚀
+        uses: JamesIves/github-pages-deploy-action@4.1.1
+        with:
+          branch: gh-pages # The branch the action should deploy to.
+          folder: site # The folder the action should deploy.

.travis.yml

@@ -1,14 +0,0 @@
-language: python
-install:
-- pip install mkdocs-material pygments mkdocs-redirects
-script:
-- mkdocs build --verbose --clean
-deploy:
- provider: pages
- skip_cleanup: true
- github_token: $GITHUB_TOKEN
- local_dir: site
- name: $BOT_NAME
- email: $BOT_EMAIL
- on:
-   branch: master

README.md

@@ -1,4 +1,4 @@
-![TRAVIS-CI](https://api.travis-ci.org/mailcow/mailcow-dockerized-docs.svg?branch=master)
+[![Build and deploy to gh-pages](https://github.com/mailcow/mailcow-dockerized-docs/actions/workflows/gh-pages.yml/badge.svg)](https://github.com/mailcow/mailcow-dockerized-docs/actions/workflows/gh-pages.yml)
 
 # mailcow: dockerized documentation
 

docs/debug-reset_pw.md

@@ -77,9 +77,17 @@ MariaDB [(none)]> FLUSH PRIVILEGES;
 
 ## Remove Two-Factor Authentication
 
+### For mailcow WebUI:
+
 This works similar to resetting a MySQL password, now we do it from the host without connecting to the MySQL CLI:
 
 ```
 source mailcow.conf
 docker-compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME} -e "DELETE FROM tfa WHERE username='YOUR_USERNAME';"
 ```
+
+### For SOGo:
+
+```
+docker-compose exec -u sogo sogo-mailcow sogo-tool user-preferences set defaults user@example.com SOGoGoogleAuthenticatorEnabled '{"SOGoGoogleAuthenticatorEnabled":0}'
+```

docs/firststeps-rp.md

@@ -15,6 +15,11 @@ This will also change the bindings inside the Nginx container! This is important
 
 Recreate affected containers by running `docker-compose up -d`.
 
+**Important information, please read them carefully!**
+
+!!! info
+    If you plan to use a reverse proxy and want to use another server name that is **not** MAILCOW_HOSTNAME, you need to read **Adding additional server names for mailcow UI** at the bottom of this page.
+
 !!! warning
     Make sure you run `generate_config.sh` before you enable any site configuration examples below.
     The script `generate_config.sh` copies snake-oil certificates to the correct location, so the services will not fail to start due to missing files.

docs/third_party-borgmatic.md

@@ -0,0 +1,247 @@
+# Borgmatic Backup
+
+## Introduction
+
+Borgmatic is a great way to run backups on your Mailcow setup as it securely encrypts your data and is extremely easy to
+set up.
+
+Due to it's deduplication capabilities you can store a great number of backups without wasting large amounts of disk
+space. This allows you to run backups in very short intervals to ensure minimal data loss when the need arises to
+recover data from a backup.
+
+This document guides you through the process to enable continuous backups for mailcow with borgmatic. The borgmatic
+functionality is provided by the [borgmatic Docker image by b3vis](https://github.com/b3vis/docker-borgmatic). Check out
+the `README` in that repository to find out about the other options (such as push notifications) that are available.
+This guide only covers the basics.
+
+## Setting up borgmatic
+
+### Create or amend `docker-compose.override.yml`
+
+In the mailcow-dockerized root folder create or edit `docker-compose.override.yml` and insert the following
+configuration:
+
+```yaml
+version: '2.1'
+services:
+  borgmatic-mailcow:
+    image: b3vis/borgmatic
+    restart: always
+    dns: ${IPV4_NETWORK:-172.22.1}.254
+    volumes:
+      - vmail-vol-1:/mnt/source/vmail:ro
+      - mysql-socket-vol-1:/var/run/mysqld/:z
+      - ./data/conf/borgmatic/etc:/etc/borgmatic.d:Z
+      - ./data/conf/borgmatic/state:/root/.config/borg:Z
+      - ./data/conf/borgmatic/ssh:/root/.ssh:Z
+    environment:
+      - TZ=${TZ}
+      - BORG_PASSPHRASE=YouBetterPutSomethingRealGoodHere
+    networks:
+      mailcow-network:
+        aliases:
+          - borgmatic
+```
+
+Ensure that you change the `BORG_PASSPHRASE` to a secure passphrase of your choosing.
+
+For security reasons we mount the maildir as read-only. If you later want to restore data you will need to remove
+the `ro` flag prior to restoring the data. This is described in the section on restoring backups.
+
+### Create `data/conf/borgmatic/etc/config.yaml`
+
+Next, we need to create the borgmatic configuration.
+
+```shell
+source mailcow.conf
+cat <<EOF > data/conf/borgmatic/etc/config.yaml
+location:
+    source_directories:
+        - /mnt/source
+    repositories:
+        - user@rsync.net:mailcow
+    remote_path: borg1
+
+retention:
+    keep_hourly: 24
+    keep_daily: 7
+    keep_weekly: 4
+    keep_monthly: 6
+
+hooks:
+    mysql_databases:
+        - name: ${DBNAME}
+          username: ${DBUSER}
+          password: ${DBPASS}
+          options: --default-character-set=utf8mb4
+EOF
+```
+
+Creating the file in this way ensures the correct MySQL credentials are pulled in from `mailcow.conf`.
+
+This file is a minimal example for using borgmatic with an account `user` on the cloud storage provider `rsync.net` for
+a repository called `mailcow` (see `repositories` setting). It will backup both the maildir and MySQL database, which is
+all you should need to restore your mailcow setup after an incident. The retention settings will keep one archive for
+each hour of the past 24 hours, one per day of the week, one per week of the month and one per month of the past half
+year.
+
+Check the [borgmatic documentation](https://torsion.org/borgmatic/) on how to use other types of repositories or
+configuration options. If you choose to use a local filesystem as a backup destination make sure to mount it into the
+container. The container defines a volume called `/mnt/borg-repository` for this purpose.
+
+!!! note
+    If you do not use rsync.net you can most likely drop the `remote_path` element from your config.
+
+### Create a crontab
+
+Create a new text file in `data/conf/borgmatic/etc/crontab.txt` with the following content:
+
+```
+14 * * * * PATH=$PATH:/usr/bin /usr/bin/borgmatic --stats -v 0 2>&1
+```
+
+This file expects crontab syntax. The example shown here will trigger the backup to run every hour at 14 minutes past
+the hour and log some nice stats at the end.
+
+### Place SSH keys in folder
+
+Place the SSH keys you intend to use for remote repository connections in `data/conf/borgmatic/ssh`. OpenSSH expects the
+usual `id_rsa`, `id_ed25519` or similar to be in this directory. Ensure the file is `chmod 600` and not world readable
+or OpenSSH will refuse to use the SSH key.
+
+### Bring up the container
+
+For the next step we need the container to be up and running in a configured state. To do that run:
+
+```shell
+docker-compose up -d
+```
+
+### Initialize the repository
+
+By now your borgmatic container is up and running, but the backups will currently fail due to the repository not being
+initialized.
+
+To initialize the repository run:
+
+```shell
+docker-compose exec borgmatic-mailcow borgmatic init --encryption repokey-blake2
+```
+
+You will be asked you to authenticate the SSH host key of your remote repository server. See if it matches and confirm
+the prompt by entering `yes`. The repository will be initialized with the passphrase you set in the `BORG_PASSPHRASE`
+environment variable earlier.
+
+When using any of the `repokey` encryption methods the encryption key will be stored in the repository itself and not on
+the client, so there is no further action required in this regard. If you decide to use a `keyfile` instead of
+a `repokey` make sure you export the key and back it up separately. Check the [Exporting Keys](#exporting-keys) section
+for how to retrieve the key.
+
+### Restart container
+
+Now that we finished configuring and initializing the repository restart the container to ensure it is in a defined
+state:
+
+```shell
+docker-compose restart borgmatic-mailcow
+```
+
+## Restoring from a backup
+
+Restoring a backup assumes you are starting off with a fresh installation of mailcow, and you currently do not have
+any custom data in your maildir or your mailcow database.
+
+### Restore maildir
+
+!!! warning
+    Doing this will overwrite files in your maildir! Do not run this unless you actually intend to recover mail
+    files from a backup.
+
+!!! note "If you use SELinux in Enforcing mode"
+    If you are using mailcow on a host with SELinux in Enforcing mode you will have to temporarily disable it during
+    extraction of the archive as the mailcow setup labels the vmail volume as private, belonging to the dovecot container
+    exclusively. SELinux will (rightfully) prevent any other container, such as the borgmatic container, from writing to
+    this volume.
+
+Before running a restore you must make the vmail volume writeable in `docker-compose.override.yml` by removing
+the `ro` flag from the volume.
+Then you can use the following command to restore the maildir from a backup:
+
+```shell
+docker-compose exec borgmatic-mailcow borgmatic extract --path mnt/source --archive latest
+```
+
+Alternatively you can specify any archive name from the list of archives (see
+[Listing all available archives](#listing-all-available-archives))
+
+### Restore MySQL
+
+!!! warning
+    Running this command will delete and recreate the mailcow database! Do not run this unless you actually
+    intend to recover the mailcow database from a backup.
+
+To restore the MySQL database from the latest archive use this command:
+
+```shell
+docker-compose exec borgmatic-mailcow borgmatic restore --archive latest
+```
+
+Alternatively you can specify any archive name from the list of archives (see
+[Listing all available archives](#listing-all-available-archives))
+
+### After restoring
+
+After restoring you need to restart mailcow. If you disabled SELinux enforcing mode now would be a good time to
+re-enable it.
+
+To restart mailcow use the follwing command:
+
+```shell
+docker-compose down && docker-compose up -d
+```
+
+If you use SELinux this will also trigger the re-labeling of all files in your vmail volume. Be patient, as this may
+take a while if you have lots of files.
+
+## Useful commands
+
+### Manual archiving run (with debugging output)
+
+```shell
+docker-compose exec borgmatic-mailcow borgmatic -v 2
+```
+
+### Listing all available archives
+
+```shell
+docker-compose exec borgmatic-mailcow borgmatic list
+```
+
+### Break lock
+
+When borg is interrupted during an archiving run it will leave behind a stale lock that needs to be cleared before any
+new operations can be performed:
+
+```shell
+docker-compose exec borgmatic-mailcow borg break-lock user@rsync.net:mailcow
+```
+
+Where `user@rsync.net:mailcow` is the URI to your repository.
+
+Now would be a good time to do a manual archiving run to ensure it can be successfully performed.
+
+### Exporting keys
+
+When using any of the `keyfile` methods for encryption you **MUST** take care of backing up the key files yourself. The
+key files are generated when you initialize the repository. The `repokey` methods store the key file within the
+repository, so a manual backup isn't as essential.
+
+Note that in either case you also must have the passphrase to decrypt any archives.
+
+To fetch the keyfile run:
+
+```shell
+docker-compose exec borgmatic-mailcow borg key export --paper user@rsync.net:mailcow
+```
+
+Where `user@rsync.net:mailcow` is the URI to your repository.

docs/u_e-nginx.md

@@ -16,6 +16,7 @@ server {
   include /etc/nginx/conf.d/listen_plain.active;
   include /etc/nginx/conf.d/listen_ssl.active;
   server_name mysite.example.org;
+  server_tokens off;
 
   location ^~ /.well-known/acme-challenge/ {
     allow all;
@@ -40,6 +41,7 @@ server {
   include /etc/nginx/conf.d/listen_plain.active;
   include /etc/nginx/conf.d/listen_ssl.active;
   server_name example.domain.tld;
+  server_tokens off;
 
   location ^~ /.well-known/acme-challenge/ {
     allow all;

docs/u_e-webmail-site.md

@@ -14,7 +14,7 @@ server {
   include /etc/nginx/conf.d/listen_plain.active;
   include /etc/nginx/conf.d/listen_ssl.active;
   server_name webmail.example.org;
-
+  server_tokens off;
   location ^~ /.well-known/acme-challenge/ {
     allow all;
     default_type "text/plain";

docs/u_e-xmpp-faq.md

@@ -6,7 +6,7 @@ Please find the most frequently asked questions with their corresponding configu
 
 No, there is not. But you don't need one either.
 
-The xmppd behaves the same way as SOGo or Solr do when disabled. A shell will be idling and ejabberd will **not** be started.
+The xmppd behaves the same way as SOGo or Solr do when disabled. A shell will be idling and ejabberd will **not** be started (but open unconnected ports).
 
 As soon as a domain is enabled for XMPP, the container will be restarted and ejabberd bootstrapped.
 

mkdocs.yml

@@ -120,6 +120,7 @@ nav:
   - 'Windows Phone': 'client/client-windowsphone.md'
   - 'Manual configuration': 'client/client-manual.md'
 - 'Third party apps':
+  - 'Borgmatic Backup': 'third_party-borgmatic.md'
   - 'Exchange Hybrid Setup': 'third_party-exchange_onprem.md'
   - 'Gitea': 'third_party-gitea.md'
   - 'Gogs': 'third_party-gogs.md'