From 9d08bf388596fc759d5a9b44dd22320d7a156a30 Mon Sep 17 00:00:00 2001 From: andryyy Date: Thu, 2 Mar 2017 22:27:46 +0100 Subject: [PATCH] Fix docs --- docs/first_steps.md | 192 +++++++++++++++++++++----------------------- docs/install.md | 46 +++++------ docs/u_and_e.md | 22 +++-- 3 files changed, 121 insertions(+), 139 deletions(-) diff --git a/docs/first_steps.md b/docs/first_steps.md index 6e9e54ae..cb1e6b28 100644 --- a/docs/first_steps.md +++ b/docs/first_steps.md @@ -12,66 +12,62 @@ mailcow uses 3 domain names that should be covered by your new certificate: This is just an example of how to obtain certificates with certbot. There are several methods! -1. Get the certbot client: +1\. Get the certbot client: +``` +wget https://dl.eff.org/certbot-auto -O /usr/local/sbin/certbot && chmod +x /usr/local/sbin/certbot +``` - ``` - wget https://dl.eff.org/certbot-auto -O /usr/local/sbin/certbot && chmod +x /usr/local/sbin/certbot - ``` +2\. Make sure you set `HTTP_BIND=0.0.0.0` in `mailcow.conf` or setup a reverse proxy to enable connections to port 80. If you changed HTTP_BIND, then restart Nginx: +``` +docker-compose restart nginx-mailcow +``` -2. Make sure you set `HTTP_BIND=0.0.0.0` in `mailcow.conf` or setup a reverse proxy to enable connections to port 80. If you changed HTTP_BIND, then restart Nginx: `docker-compose restart nginx-mailcow`. +3\. Request the certificate with the webroot method: +``` +cd /path/to/git/clone/mailcow-dockerized +source mailcow.conf +certbot certonly \ + --webroot \ + -w ${PWD}/data/web \ + -d ${MAILCOW_HOSTNAME} \ + -d autodiscover.example.org \ + -d autoconfig.example.org \ + --email you@example.org \ + --agree-tos +``` + +4\. 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 +``` -3. Request the certificate with the webroot method: - - ``` - cd /path/to/git/clone/mailcow-dockerized - source mailcow.conf - certbot certonly \ - --webroot \ - -w ${PWD}/data/web \ - -d ${MAILCOW_HOSTNAME} \ - -d autodiscover.example.org \ - -d autoconfig.example.org \ - --email you@example.org \ - --agree-tos - ``` - -4. 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 - ``` - -5. Restart affected containers: - - ``` - docker-compose restart postfix-mailcow dovecot-mailcow nginx-mailcow - ``` +5\. Restart affected containers: +``` +docker-compose restart postfix-mailcow dovecot-mailcow nginx-mailcow +``` When renewing certificates, run the last two steps (link + restart) as post-hook in a script. # Rspamd Web UI At first you may want to setup Rspamds web interface which provides some useful features and information. -1. Generate a Rspamd controller password hash: +1\. Generate a Rspamd controller password hash: +``` +docker-compose exec rspamd-mailcow rspamadm pw +``` - ``` - docker-compose exec rspamd-mailcow rspamadm pw - ``` +2\. Replace the default hash in `data/conf/rspamd/override.d/worker-controller.inc` by your newly generated: +``` +enable_password = "myhash"; +``` -2. Replace the default hash in `data/conf/rspamd/override.d/worker-controller.inc` by your newly generated: - - ``` - enable_password = "myhash"; - ``` - -3. Restart rspamd: - - ``` - docker-compose restart rspamd-mailcow - ``` +3\. Restart rspamd: +``` +docker-compose restart rspamd-mailcow +``` Open https://${MAILCOW_HOSTNAME}/rspamd in a browser and login! @@ -80,61 +76,59 @@ Open https://${MAILCOW_HOSTNAME}/rspamd in a browser and login! You don't need to change the Nginx site that comes with mailcow: dockerized. mailcow: dockerized trusts the default gateway IP 172.22.1.1 as proxy. This is very important to control access to Rspamd's web UI. -1. Make sure you change HTTP_BIND and HTTPS_BIND in `mailcow.conf` to a local address and set the ports accordingly, for example: +1\. Make sure you change HTTP_BIND and HTTPS_BIND in `mailcow.conf` to a local address and set the ports accordingly, for example: +``` +HTTP_BIND=127.0.0.1 +HTTP_PORT=8080 +HTTPS_PORT=127.0.0.1 +HTTPS_PORT=8443 +``` - ``` - HTTP_BIND=127.0.0.1 - HTTP_PORT=8080 - HTTPS_PORT=127.0.0.1 - HTTPS_PORT=8443 - ``` +Recreate affected containers by running `docker-compose up -d`. - Recreate affected containers by running `docker-compose up -d`. +2\. Configure your local webserver as reverse proxy: +**Apache 2.4** +``` + + ServerName mail.example.org + ServerAlias autodiscover.example.org + ServerAlias autoconfig.example.org -2. Configure your local webserver as reverse proxy: + [...] + # You should proxy to a plain HTTP session to offload SSL processing + ProxyPass / http://127.0.0.1:8080 + ProxyPassReverse / http://127.0.0.1:8080 + ProxyPreserveHost On + your-ssl-configuration-here + [...] - **Apache 2.4** - ``` - - ServerName mail.example.org - ServerAlias autodiscover.example.org - ServerAlias autoconfig.example.org + # If you plan to proxy to a HTTPS host: + #SSLProxyEngine On + + # If you plan to proxy to an untrusted HTTPS host: + #SSLProxyVerify none + #SSLProxyCheckPeerCN off + #SSLProxyCheckPeerName off + #SSLProxyCheckPeerExpire off + +``` - [...] - # You should proxy to a plain HTTP session to offload SSL processing - ProxyPass / http://127.0.0.1:8080 - ProxyPassReverse / http://127.0.0.1:8080 - ProxyPreserveHost On - your-ssl-configuration-here - [...] +**Nginx** +``` +server { + listen 443; + server_name mail.example.org autodiscover.example.org autoconfig.example.org; - # If you plan to proxy to a HTTPS host: - #SSLProxyEngine On - - # If you plan to proxy to an untrusted HTTPS host: - #SSLProxyVerify none - #SSLProxyCheckPeerCN off - #SSLProxyCheckPeerName off - #SSLProxyCheckPeerExpire off - - ``` - - **Nginx** - ``` - server { - listen 443; - server_name mail.example.org autodiscover.example.org autoconfig.example.org; - - [...] - your-ssl-configuration-here - location / { - proxy_pass http://127.0.0.1:8080; - proxy_set_header Host $host; - proxy_set_header X-Real-IP $remote_addr; - proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; - proxy_set_header X-Forwarded-Proto $scheme; - } - [...] + [...] + your-ssl-configuration-here + location / { + proxy_pass http://127.0.0.1:8080; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; } - ``` + [...] +} +``` diff --git a/docs/install.md b/docs/install.md index 85917a50..d1ba349d 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,39 +1,29 @@ # Install mailcow -1. You need Docker. +You need Docker and Docker Compose. - Most systems can install Docker by running `wget -qO- https://get.docker.com/ | sh`. +1\. Learn how to install [Docker](https://docs.docker.com/engine/installation/linux/) and [Docker Compose](https://docs.docker.com/compose/install/). -2. You need Docker Compose +2\. Clone the master branch of the repository +``` +git clone https://github.com/andryyy/mailcow-dockerized && cd mailcow-dockerized +``` - Learn [how to install Docker Compose](https://docs.docker.com/compose/install/). - - -3. Clone the master branch of the repository - - ``` - git clone https://github.com/andryyy/mailcow-dockerized && cd mailcow-dockerized - ``` - -4. Generate a configuration file. Use a FQDN (`host.domain.tld`) as hostname when asked. - - ``` - ./generate_config.sh - ``` - -5. Change configuration if you want or need to. - - ``` - nano mailcow.conf - ``` +3\. Generate a configuration file. Use a FQDN (`host.domain.tld`) as hostname when asked. +``` +./generate_config.sh +``` +4\. Change configuration if you want or need to. +``` +nano mailcow.conf +``` If you plan to use a reverse proxy, you can, for example, bind HTTPS to 127.0.0.1 on port 8443 and HTTP to 127.0.0.1 on port 8080. -6. Run the composer file. - - ``` - docker-compose up -d - ``` +5\. Run the composer file. +``` +docker-compose up -d +``` Done! diff --git a/docs/u_and_e.md b/docs/u_and_e.md index 1ca66c4c..89d35428 100644 --- a/docs/u_and_e.md +++ b/docs/u_and_e.md @@ -263,18 +263,17 @@ Running `docker-compose down -v` will **destroy all mailcow: dockerized volumes* # Reset admin password Reset mailcow admin to `admin:moohoo`: -1. Drop admin table +1\. Drop admin table +``` +source mailcow.conf +docker-compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME} -e "DROP TABLE admin;" +``` - ``` - source mailcow.conf - docker-compose exec mysql-mailcow mysql -u${DBUSER} -p${DBPASS} ${DBNAME} -e "DROP TABLE admin;" - ``` - - 2. Open mailcow UI to auto-init the db +2\. Open mailcow UI to auto-init the db # Rspamd -**Learn spam and ham*** +**Learn spam and ham** Rspamd learns mail as spam or ham when you move a message in or out of the junk folder to any mailbox besides trash. This is archived by using the Dovecot plugin "antispam" and a simple parser script. @@ -372,8 +371,9 @@ docker-compose restart service-mailcow Mailbox users can tag their mail address like in `me+facebook@example.org` and choose between to setups to handle this tag: -1. Move this message to a subfolder "facebook" (will be created lower case if not existing) -2. Prepend the tag to the subject: "[facebook] Subject" +1\. Move this message to a subfolder "facebook" (will be created lower case if not existing) + +2\. Prepend the tag to the subject: "[facebook] Subject" # Two-factor authentication @@ -406,5 +406,3 @@ Most systems use either a public or a local caching DNS resolver. That's a very bad idea when it comes to filter spam using DNS-based blackhole lists (DNSBL) or similar technics. Most if not all providers apply a rate limit based on the DNS resolver that is used to query their service. Using a public resolver like Googles 4x8, OpenDNS or any other shared DNS resolver like your ISPs will hit that limit very soon. - -