From cc62e0f3c2c6cf5401befdb29076945248117c16 Mon Sep 17 00:00:00 2001 From: andryyy Date: Mon, 19 Dec 2016 21:53:55 +0100 Subject: [PATCH] Some format changes --- README.md | 160 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 90 insertions(+), 70 deletions(-) diff --git a/README.md b/README.md index 5a3056e7..64a68a0c 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,55 @@ -# mailcow-dockerized 🐮 🐋 +# mailcow: dockerized - 🐮 + 🐋 = 💕 -mailcow dockerized comes with 11 containers linked in a mailcow network: -Dovecot, Memcached, Redis, MySQL, PowerDNS Recursor, PHP-FPM, Postfix, Nginx, Rmilter, Rspamd and SOGo. +[![Donate](https://img.shields.io/badge/Donate-PayPal-green.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=JWBSYHF4SMC68) -4 volumes to keep dynamic data. Feel free to use a 3rd-party driver to host your mail directory (vmail) in the cloud or whatever else: - vmail-vol-1, dkim-vol-1, redis-vol-1, mysql-vol-1 +## About mailcow: dockerized +mailcow dockerized comes with **11 containers** linked in a mailcow network: +- Dovecot +- Memcached +- Redis +- MySQL +- PowerDNS Recursor +- PHP-FPM +- Postfix +- Nginx +- Rmilter +- Rspamd +- SOGo -Important configuration files are mounted into the related containers from the host (`./data/conf`) and can be changed. Services should be restarted after they were changed (docker-compose restart x-mailcow). +**4** volumes to keep dynamic data - take care of them! +- vmail-vol-1 +- dkim-vol-1 +- redis-vol-1 +- mysql-vol-1 All configurations were written with security in mind. -### Containers and volumes +### Container and volume overview -| Type | Object name | Network names | External binding | Internal binding | Volumes | -|-----------|-------------------|------------------------------|----------------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Container | postfix-mailcow | ${MAILCOW_HOSTNAME}, postfix | 25/tcp, 465/tcp, 587/tcp | 588/tcp | ./data/conf/postfix:/opt/postfix/conf, ./data/assets/ssl:/etc/ssl/mail/:ro | -| Container | dovecot-mailcow | ${MAILCOW_HOSTNAME}, dovecot | 110/tcp, 143/tcp, 993/tcp, 995/tcp, 4190/tcp | 24/tcp, 10001/tcp | vmail-vol-1:/var/vmail, ./data/conf/dovecot:/etc/dovecot, ./data/assets/ssl:/etc/ssl/mail/:ro | -| Container | nginx-mailcow | nginx | 443/tcp | 80/tcp, 8081/tcp | Mounts from sogo-mailcow, ./data/web:/web:ro, ./data/conf/rspamd/dynmaps:/dynmaps:ro, ./data/assets/ssl/:/etc/ssl/mail/:ro, ./data/conf/nginx/:/etc/nginx/conf.d/:ro | -| Container | pdns-mailcow | pdns | - | 53/udp | ./data/conf/pdns/:/etc/powerdns/ | -| Container | rspamd-mailcow | rspamd | - | 11333/tcp, 11334/tcp | dkim-vol-1:/data/dkim, ./data/conf/rspamd/override.d/:/etc/rspamd/override.d:ro, ./data/conf/rspamd/local.d/:/etc/rspamd/local.d:ro, ./data/conf/rspamd/lua/:/etc/rspamd/lua/:ro | -| Container | mysql-mailcow | mysql | - | 3306/tcp | mysql-vol-1:/var/lib/mysql/, ./data/conf/mysql/:/etc/mysql/conf.d/:ro | -| Container | rmilter-mailcow | rmilter | - | 9000/tcp | ./data/conf/rmilter/:/etc/rmilter.conf.d/:ro | -| Container | phpfpm-mailcow | phpfpm | - | 9000/tcp | dkim-vol-1:/data/dkim, ./data/web:/web:ro, ./data/conf/rspamd/dynmaps:/dynmaps:ro | -| Container | sogo-mailcow | sogo | - | 20000/tcp | ./data/conf/sogo/:/etc/sogo/,exposes /usr/lib/GNUstep/SOGo/WebServerResources/ | -| Container | redis-mailcow | redis | - | 6379/tcp | redis-vol-1:/data/ | -| Container | memcached-mailcow | memcached | - | 11211/tcp | - | -| Volume | vmail-vol-1 | - | - | - | Mounts to dovecot | -| Volume | dkim-vol-1 | - | - | - | Mounts to rspamd + phpfpm | -| Volume | redis-vol-1 | - | - | - | Mounts to redis | -| Volume | mysql-vol-1 | - | - | - | Mounts to mysql | +| Type | Object name | Network names | External binding | Internal binding | Volumes | +|-----------|-------------------|------------------------------|----------------------------------------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Container | postfix-mailcow | ${MAILCOW_HOSTNAME}, postfix | 25/tcp, 465/tcp, 587/tcp | 588/tcp | ./data/conf/postfix => /opt/postfix/conf, ./data/assets/ssl => /etc/ssl/mail/:ro | +| Container | dovecot-mailcow | ${MAILCOW_HOSTNAME}, dovecot | 110/tcp, 143/tcp, 993/tcp, 995/tcp, 4190/tcp | 24/tcp, 10001/tcp | vmail-vol-1 => /var/vmail, ./data/conf/dovecot => /etc/dovecot, ./data/assets/ssl => /etc/ssl/mail/:ro | +| Container | nginx-mailcow | nginx | 443/tcp | 80/tcp, 8081/tcp | Mounts from sogo-mailcow, ./data/web => /web:ro, ./data/conf/rspamd/dynmaps => /dynmaps:ro, ./data/assets/ssl/ => /etc/ssl/mail/:ro, ./data/conf/nginx/ => /etc/nginx/conf.d/:ro | +| Container | pdns-mailcow | pdns | - | 53/udp | ./data/conf/pdns/ => /etc/powerdns/ | +| Container | rspamd-mailcow | rspamd | - | 11333/tcp, 11334/tcp | dkim-vol-1 => /data/dkim, ./data/conf/rspamd/override.d/ => /etc/rspamd/override.d:ro, ./data/conf/rspamd/local.d/ => /etc/rspamd/local.d:ro, ./data/conf/rspamd/lua/ => /etc/rspamd/lua/:ro | +| Container | mysql-mailcow | mysql | - | 3306/tcp | mysql-vol-1 => /var/lib/mysql/, ./data/conf/mysql/ => /etc/mysql/conf.d/:ro | +| Container | rmilter-mailcow | rmilter | - | 9000/tcp | ./data/conf/rmilter/ => /etc/rmilter.conf.d/:ro | +| Container | phpfpm-mailcow | phpfpm | - | 9000/tcp | dkim-vol-1 => /data/dkim, ./data/web => /web:ro, ./data/conf/rspamd/dynmaps => /dynmaps:ro | +| Container | sogo-mailcow | sogo | - | 20000/tcp | ./data/conf/sogo/ => /etc/sogo/,exposes /usr/lib/GNUstep/SOGo/WebServerResources/ | +| Container | redis-mailcow | redis | - | 6379/tcp | redis-vol-1 => /data/ | +| Container | memcached-mailcow | memcached | - | 11211/tcp | - | +| Volume | vmail-vol-1 | - | - | - | Mounts to dovecot | +| Volume | dkim-vol-1 | - | - | - | Mounts to rspamd + phpfpm | +| Volume | redis-vol-1 | - | - | - | Mounts to redis | +| Volume | mysql-vol-1 | - | - | - | Mounts to mysql | + +### Network All containers share a network "mailcow-network" with the subnet 172.22.1.0/24 - if you want to change it, set it in the composer file. IPs are dynamic except for PowerDNS resolver which has a static ip address 172.22.1.254. -### **FAQ** +**FAQ** - rspamd learns mail as spam or ham when you move a message in or out of the junk folder to any mailbox besides trash. - rspamd auto-learns mail when a high or low score is detected (see https://rspamd.com/doc/configuration/statistic.html#autolearning) @@ -52,127 +68,131 @@ Done. You can now access https://${MAILCOW_HOSTNAME} with the default credentials `admin` + password `moohoo`. The database will be initialized when you first visit the UI. ## Configuration after installation - ### Rspamd UI access -If you want to use Rspamds web UI, you need to set a Rspamd controller password: +At first you may want to setup Rspamds web interface which provides some useful features and information. +1. Set a Rspamd controller password: ``` # Generate hash docker-compose exec rspamd-mailcow rspamadm pw ``` - -Replace given hash in data/conf/rspamd/override.d/worker-controller.inc: +2. Replace the default hash in `data/conf/rspamd/override.d/worker-controller.inc` by your newly generated: ``` enable_password = "myhash"; ``` - -Restart rspamd: +3. Restart rspamd: ``` docker-compose restart rspamd-mailcow ``` - -Open https://${MAILCOW_HOSTNAME}/rspamd in a browser. +Open https://${MAILCOW_HOSTNAME}/rspamd in a browser and login! ### SSL (and: How to use Let's Encrypt) mailcow dockerized comes with a snakeoil CA "mailcow" and a server certificate in `data/assets/ssl`. Please use your own trusted certificates. -**Use Let's Encrypt** +mailcow uses 3 domain names that should be covered by your new certificate: +- ${MAILCOW_HOSTNAME} +- autodiscover.example.org (used for ActiveSync) +- autoconfig.example.org (used by Thunderbird and derivates) -Get the certbot client: +**Obtain multi-SAN certificate by Let's Encrypt** +This is just an example of how to obtain certificates with certbot. There are several methods! + +1. Get the certbot client: ``` wget https://dl.eff.org/certbot-auto -O /usr/local/sbin/certbot && chmod +x /usr/local/sbin/certbot ``` - -Please disable applications blocking port 80 and run certbot: +2. Disable applications blocking port 80 and run certbot: ``` +cd /path/to/git/clone/mailcow-dockerized source mailcow.conf certbot certonly \ --standalone \ --standalone-supported-challenges http-01 \ -d ${MAILCOW_HOSTNAME} \ + -d autodiscover.example.org \ + -d autoconfig.example.org \ --email you@example.org \ --agree-tos ``` - -Create hard links to the full path of the new certificates. Assuming you are still in the mailcow root folder: +3. Create hard links to the full path of the new certificates. Assuming you are still in the mailcow root folder: ``` mv data/assets/ssl/cert.{pem,pem.backup} mv data/assets/ssl/key.{pem,pem.backup} ln $(readlink -f /etc/letsencrypt/live/${MAILCOW_HOSTNAME}/fullchain.pem) data/assets/ssl/cert.pem ln $(readlink -f /etc/letsencrypt/live/${MAILCOW_HOSTNAME}/privkey.pem) data/assets/ssl/key.pem ``` - -Restart containers which use the certificate: +4. Restart containers which use the certificate: ``` docker-compose restart postfix-mailcow docker-compose restart dovecot-mailcow docker-compose restart nginx-mailcow ``` +When renewing certificates, run the last two steps (link + restart) as post-hook in a script. -When renewing certificates, run the last two steps (link + restart) as post-hook in certbot. +## Other useful commands and examples -## More useful commands and examples (todo: move to wiki soon) +All commands need to be run from within `/path/to/git/clone/mailcow-dockerized`. +### Get bash-completion for docker-compose +For the tab-tab... :-) +``` +curl -L https://raw.githubusercontent.com/docker/compose/$(docker-compose version --short)/contrib/completion/bash/docker-compose -o /etc/bash_completion.d/docker-compose +``` ### Logs - You can use `docker-compose logs $service-name` for almost all containers. Only rmilter does not log to stdout. You can check rspamd logs for rmilter responses. -### MySQL +Run `docker-compose logs` for all logs at once. -Connect to MySQL database: +### MySQL +Connect to the MySQL database: ``` source mailcow.conf docker-compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME} ``` - Reset mailcow admin to `admin:moohoo`: ``` +# 1. Drop admin table source mailcow.conf -docker-compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME} -e "DROP TABLE admin; DROP TABLE domain_admins" -# Open mailcow UI to auto-init the db +docker-compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME} -e "DROP TABLE admin;" +# 2. Open mailcow UI to auto-init the db ``` - -Backup database: +Backup the database: ``` source mailcow.conf -# Create DATE=$(date +"%Y%m%d_%H%M%S") docker-compose exec mysql-mailcow mysqldump --default-character-set=utf8mb4 -u${DBUSER} -p${DBPASS} ${DBNAME} > backup_${DBNAME}_${DATE}.sql ``` -### Backup maildir (simple tar): -``` -docker run --rm -it -v $(docker inspect --format '{{ range .Mounts }}{{ if eq .Destination "/var/vmail" }}{{ .Name }}{{ end }}{{ end }}' $(docker-compose ps -q dovecot-mailcow)):/vmail -v ${PWD}:/backup debian:jessie tar cvf /backup/backup_vmail.tar /vmail -``` - ### Redis - Connect to redis key store: ``` docker-compose exec redis-mailcow redis-cli ``` -### Use rspamadm: -``` -docker-compose exec rspamd-mailcow rspamadm --help -``` - -### Use rspamc: +### Rspamd: +Rspamd CLI tools: ``` docker-compose exec rspamd-mailcow rspamc --help +docker-compose exec rspamd-mailcow rspamadm --help ``` -### Use doveadm: +### Dovecot: +Run doveadm: ``` docker-compose exec dovecot-mailcow doveadm ``` - +Backup maildir (simple tar file): +``` +docker run --rm -it -v $(docker inspect --format '{{ range .Mounts }}{{ if eq .Destination "/var/vmail" }}{{ .Name }}{{ end }}{{ end }}' $(docker-compose ps -q dovecot-mailcow)):/vmail -v ${PWD}:/backup debian:jessie tar cvfz /backup/backup_vmail.tar.gz /vmail +``` ### Remove persistent data - -Remove volume mysql-vol-1 to get rid fo MySQL data. Do the same for volume redis-vol-1 to remove Redis data. +Remove volume `mysql-vol-1` to remove all MySQL data. +Remove volume `redis-vol-1` to remove all Redis data. +Remove volume `vmail-vol-1` to remove all contents of `/var/vmail` mounted to `dovecot-mailcow`. +Remove volume `dkim-vol-1` to remove all DKIM keys. ### Scale it - -You can scale services for mailcow: +You can scale some services for mailcow, which is much more useful on a multi-host system. Please do not scale MySQL or Redis containers. +This is insufficiently tested! ``` docker-compose scale rspamd-mailcow=2 docker-compose scale rmilter-mailcow=3