Merge branch 'master' of github.com:mailcow/mailcow-dockerized-docs
Dieser Commit ist enthalten in:
Commit
e975c24a29
10 geÀnderte Dateien mit 293 neuen und 17 gelöschten Zeilen
27
.github/workflows/gh-pages.yml
gevendort
Normale Datei
27
.github/workflows/gh-pages.yml
gevendort
Normale Datei
|
@ -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.
|
14
.travis.yml
14
.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
|
|
|
@ -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
|
||||||
|
|
||||||
|
|
|
@ -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}'
|
||||||
|
```
|
||||||
|
|
|
@ -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
247
docs/third_party-borgmatic.md
Normale Datei
|
@ -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.
|
|
@ -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;
|
||||||
|
|
|
@ -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";
|
||||||
|
|
|
@ -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.
|
||||||
|
|
||||||
|
|
|
@ -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'
|
||||||
|
|
Laden âŠ
In neuem Issue referenzieren