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

Dieser Commit ist enthalten in:
andryyy 2021-04-28 22:37:35 +02:00
Commit e975c24a29
10 geÀnderte Dateien mit 293 neuen und 17 gelöschten Zeilen

27
.github/workflows/gh-pages.yml gevendort Normale Datei
Datei anzeigen

@ -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.

Datei anzeigen

@ -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

Datei anzeigen

@ -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 # mailcow: dockerized documentation

Datei anzeigen

@ -77,9 +77,17 @@ MariaDB [(none)]> FLUSH PRIVILEGES;
## Remove Two-Factor Authentication ## 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: This works similar to resetting a MySQL password, now we do it from the host without connecting to the MySQL CLI:
``` ```
source mailcow.conf source mailcow.conf
docker-compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME} -e "DELETE FROM tfa WHERE username='YOUR_USERNAME';" 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}'
```

Datei anzeigen

@ -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`. 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 !!! warning
Make sure you run `generate_config.sh` before you enable any site configuration examples below. 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. 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.

247
docs/third_party-borgmatic.md Normale Datei
Datei anzeigen

@ -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.

Datei anzeigen

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

Datei anzeigen

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

Datei anzeigen

@ -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. 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. As soon as a domain is enabled for XMPP, the container will be restarted and ejabberd bootstrapped.

Datei anzeigen

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