mailcow / mailcow-dockerized-docs Goto Github PK

According to the SRV RFC[0] target records "MUST NOT be an alias" (see also [1]).

The documentation suggests a CNAME for autodiscover as well as autodiscover.example.org for the SRV record. I see two options:

• Despite CNAME's not being legal, it generally doesn't seem to matter in most implementations and will continue to work. Thus we can ignore, or document the point.
• Docs suggest A records for autodiscover

[0] https://tools.ietf.org/html/rfc2782
[1] https://en.wikipedia.org/wiki/SRV_record#Record_format

I am suggesting two things:

Migration

The first being improving upon the migration page by adding a section that goes over the basics of what one would do in the case they want to migrate off of mailcow, while keeping as much data as possible.
I understand this process would vary greatly depending on what service the user is migrating to, and it would not make sense to document for each service, I am simply suggesting providing an overall guideline, and resources the user can use to aid them in this process.

Service Documentation

There are already a few pages, however not all have an explanation page. For example Redis has it's own page, but from what I can tell Postfix does not. Postfix does have other information thoigh.

What I am suggesting is providing a new page, that outlines all of the services mailcow uses, in reasonable detail, how they work, what they are used for, etc. And then each of these can link to further reading pages which would link to the already existing guides.
Having one page would make it easier for newer users to identify each service quickly with ease, what they do, and more without having to click on each one to see what they do (like how the Redis page currently is).

File Locations

In relation to the above, I think it would be nice to provide detailed documentation on all the paths where the major/important Mailcow (services) files are stored.

The goal of all this is to provide users with a better understanding of how stuff is working and how to manage mailcow better. I also think it's simply just important to document how things work.

At firststeps-syslog.md file there is a workaround to use the /etc/default/docker file.
I think it could be better to use the /etc/docker/daemon.json file for the docker options like here: docker documentation

I tested this with the following content of /etc/docker/daemon.json:

{
  "log-driver": "syslog",
  "log-opts": {
    "syslog-address": "udp://127.0.0.1:514"
  }
}

So i would like to discuss it here before opening a pull request.

I'm setting up ejabberd for the first time.

From the XMPP guide I see that there needs to be a new certificate for XMPP. Since I'm not using the build in ACME client, I'll have to add my own certs. From the docs it is not entirely clear to me for what subdomains I have to request a cert.

A recent comment in one of the mailcow issues made me think that there is probably an easy way to rollback a mailcow release in case there's some issue.
Docker & docker compose support this anyway (you can usually use an image tag with an older version) so I thought there is probably something.
I wasn't able to find something in the docs but at least the update is described.

It seems that there are no releases or proper git tags neither so for now it seems like someone would have to tangle through merges and commits by trial and error for now.

PS: Not quite related but maybe it would be useful to track the last used revisions in a separate file when calling the update script (obviously before a newer revision is checked out) as a first step in some improvement of the file.

Just a question about this: https://mailcow.github.io/mailcow-dockerized-docs/prerequisite-system/#hetzner-cloud-and-probably-others

For what should this get changed? It's just a virtual network interface which only attaches the IPv6 address to the main interface.
And: it also works without the change

Every now and then there seem to arise misunderstandings about what knowledge one should have to set up and operate a mailserver(suite) like mailcow.
I'd like to add an overview recommendation what knowledge the users targeted by the docs are assumed to have acquired beforehand.
Also, I think it would be nice to provide some links as starting point for users research on these topics.

I've created this issue to collect community input on

• general (mail server related) technical terms or fields that should be mentioned
• useful links to guides or other resources for self education on these topics

We cannot of course go into detail too much and mention every single command, but provide a rough overview.

In the install docs[0] there are steps to change mailcow.conf (see step 4) but it is not source'd before docker-compose is called (step 5).

Similar notes should be made elsewhere (eg updating) when administering docker.

[0] https://mailcow.github.io/mailcow-dockerized-docs/install/

Dear,

Is it possible to add a section to describe :

• How to authorize an IP address without authentication to send an email through port 25 ?

• How to disable "Need fully-qualified hostname" only for the device because the printer, scanner not allowed to send this information when sending email ?
  NOQUEUE: reject: RCPT from unknown[192.168.0.227]: 504 5.5.2 <NPIF65E56>: Helo command rejected: need fully-qualified hostname; from=<[email protected]> to=<[email protected]> proto=ESMTP helo=<NPIF65E56>

Best Regards,

While it's great to have detailed and automated IMAP/EAS configs for the most popular clients, I believe it can be very useful to also document the manual client settings. For example:

• SMTP Port: 25
• SMT Port with SSL: 465

and so on.

Hello
I just noticed that if i click "Show configuration guides for email clients and smartphones" i get error "404 - Not found".

The url is:
https://mailcow.github.io/mailcow-dockerized-docs/client/#host=mailcow.lokalen.org&email=user%40domain.tld&name=User+Name&ui=mailcow.domain.tld&port=443

As of now, with the default configuration, it is not possible to edit users sieve filters from another client, because SOGo overwrite the configuration. This prevents edit from other clients (for example from Thunderbird or sieve-connect).

Related SOGo issues:

• https://sogo.nu/bugs/view.php?id=1178
• https://sogo.nu/bugs/view.php?id=4387
• https://sogo.nu/bugs/view.php?id=3636
• https://sogo.nu/bugs/view.php?id=3871

I hope this is the correct repo to report this.
While creating an alias via the API I came across the problem, that the alias was not visible in SoGO.
Only after some time I found out that this was due to not setting "sogo_visible".

This should be documented in the API documentation.

Thanks

The link at point 9 should href something like this:
href="https://__HOST__/thunderbird-plugins/sogo-integrator-__VERSION__-__DOMAIN__.xpi"

otherwise I get this link(404 Page):
https://mailcow.github.io/thunderbird-plugins/sogo-integrator-31.0.6-example.com.xpi
href="/thunderbird-plugins/sogo-integrator-__VERSION__-__DOMAIN__.xpi

https://mailcow.github.io/mailcow-dockerized-docs/client/client-thunderbird/

There are two source of documentation regarding the SOGo Integrator, one targeted at the admin and one targeted at the Thunderbird users.

For the admin-targeted one, the "Install it in Thunderbird" lacks quite a bit of detail. E.g. you have to set the default account correctly in Thunderbird before installing the plugin. I recommend to link to the user-targeted documentation instead, which contains more detailed instructions. This also avoids duplicate documentation.

The user-targeted documentation could take two minor improvements IMO:

• A note, that setting the default account is actually important for the plugin to work, and not just a recommendation.
• A note/warning, that the offline address books are automatically migrated as soon as the plugin is installed.

(Note: I might create a PR for that later, but I want to get my mail setup done first)

as Nextcloud needs to perform some cron related actions the documentation https://mailcow.github.io/mailcow-dockerized-docs/third_party/third_party-nextcloud/ should be extended to include a part on how to configure/enable the cron task.

see https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/background_jobs_configuration.html

I achieved it by adding this part to my docker-compose.override.yml and running docker-compose up -d && docker-compose restart ofelia

version: '2.1'
services:
  php-fpm-mailcow:
    labels:
      ofelia.enabled: "true"
      ofelia.job-exec.nextcloud-cron.schedule: "@every 5m"
      ofelia.job-exec.nextcloud-cron.command: "su www-data -s /bin/bash -c \"/usr/local/bin/php -f /web/nextcloud/cron.php\""

Hi, I'm a little confused by the docs.

The first feature described by the overview is "DKIM Key Management": https://mailcow.github.io/mailcow-dockerized-docs/#overview

But this page makes it look like DKIM (and all keys) are managed 100% manually: https://mailcow.github.io/mailcow-dockerized-docs/prerequesite-dns/#dkim-spf-and-dmarc

Is one or the other of these out of date?

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

This repository currently has no open or pending branches.

Detected dependencies

• Check this box to trigger a request for Renovate to run again on this repository

In the documentation for mail client configuration, STARTTLS and TLS configurations are shown, with STARTTLS listed first. While no explicit recommendation is made, the placement slightly implies preference. In any case, I suggest adding a mention that STARTTLS should not be used if TLS is known to be available.

STARTTLS is just an opportunistic encryption mechanism which tests at the initiation of each connection whether TLS is available. If this fails for any reason, it will by design downgrade to an unencrypted connection.

https://mailcow.github.io/mailcow-dockerized-docs/client/client-manual/
https://github.com/mailcow/mailcow-dockerized-docs/blob/master/docs/client/client-manual.md

This recommendation is currently made by, for example, Riseup: https://riseup.net/en/email/clients

Hi,

In the installation requirements there is a chapter that deals with firewalls and ports. It explains exactly which incoming ports Mailcow needs and how to check if they are free. However, outgoing ports are not covered in this chapter. Outgoing ports and destinations are only briefly touched in "Hetzner Cloud (and probably others)", as there are specialities for Hetzner.

Can we have a chapter that deals with outgoing destinations and ports during installation and operation?
E.g. for http/https towards GitHub (git clone), DNS towards root server and recursive resolution, etc.?

I think not every Mailcow instance is placed on the internet with the firewall completely open for outgoing connections.
For such installations, an overview of the required connections would be helpful.

Greetings
Stefomat

Hello,

In the backup page, you give an example on how to change the backup file name (which is rather simple) but not on how to change the backup file path:
"You can change the path by adjusting ${PWD} (which equals to the current directory) to any path you have write-access to."
https://mailcow.github.io/mailcow-dockerized-docs/u_e-backup_restore-maildir/

Could you please explicit this?

Thanks!

When starting rsyslog, the following warning is produced:

May 23 20:05:36 mail rsyslogd[1377]: warning: ~ action is deprecated, consider using the 'stop' statement instead [v8.1901.0 try https://www.rsyslog.com/e/2307 ]

docs/post_installation/firststeps-logging.en.md:

# For Rsyslog only:
# To move local3 input to /var/log/mailcow.log and stop processing, create a file "/etc/rsyslog.d/docker.conf":

local3.*        /var/log/mailcow.logs
& ~

# Restart rsyslog afterwards.

Used OS: debian-10
rsyslog-version: Version: 8.1901.0-1+deb10u1

When running the GUI-based DNS checker included in the admin interface (Configuration -> Mail Setup -> Domains -> small blue DNS button next to each domain entry), the checker complains about missing TLSA records, which are the records used by DANE. There is currently no information about DANE/TLSA-records in the documentation. This information should be added to the Prerequisites -> DNS Setup section in the documentation.

Hi,

What do you think about hosting localized versions of the documentation? I'm not sufficiently familiar with MkDocs functionalities but it would be a good improvement to serve some translated content to users. Especially the pages about clients, every end-user is not fluent in English.

If it is possible, I would really like to help translating the pages. We can even use a all-in-one solution (like Crowdin or Weblate) who offer free plans to OSS.

Thanks in advance for your feedbacks!
Best,

This applies both to the English and German documentation.

btnSize does not exist with the new Bootstrap 5 CSS. It should just use btn-xs-half like the SOGO login button.

sorry wronge page...

Summary

The documentation on the backup process for the mailcow is correct and the process works as expected. But it's missing one key fact that the restore documentation clearly states. For some components of the backup process the mailcow needs to be started via "docker-compose up -d". If it's not started for example the mysql backup is not possible and instead there are some messages like

docker: invalid reference format.
See 'docker run --help'.

As mailcow/mailcow-dockerized#4618 clearly shows there are issues when updating if still using Docker-compose v1. Maybe the update script will be updated to upgrade Docker compose to v2 for us or at least warn us better.

In the meantime, the update documentation page needs to refer to the manual Docker compose upgrade steps in the installation documentation page before upgrading if they still have Docker-compose v1 installed.

There is a typo in docs about doveadm for crypt, it's reported like "doveadm fs get compress lz4:0:...." but 0 isn't a valid value, you need to change it with a value between 1 to 9

For easier DAV configuration we could suggest to set up SRV records. eg:

_carddavs._tcp IN SRV 10 1 443 mail.example.com.
_carddavs._tcp IN TXT "path=/SOGo/dav/"
_caldavs._tcp IN SRV 10 1 443 mail.example.com.
_caldavs._tcp IN TXT "path=/SOGo/dav/"

The documentation here tells me to edit a domain and to assign a relayhost to it. When editing a domain though, all I have is a checkbox to enable relaying of the domain, I can't "assign" a relayhost. I later found this issue, which clarifies that checking the checkbox makes Mailcow relay mails to the primary mail service it finds by looking at the MX DNS-records of the domain.

Please clarify that

1. checking the checkbox really does all the magic and you don't have to mess e.g. with transport maps (which is what I did first)
2. Mailcow selects the destination by selecting the primary MX entry from DNS

(Note: I might create a PR for that later, but I want to get my mail setup done first)

Hey, many of the code blocks within reverse proxy section are broken:

https://mailcow.github.io/mailcow-dockerized-docs/de/post_installation/firststeps-rp/

However, the source of the files itself seems to be fine.
I guess the problem occurs within the compilation process of the static content - probably a misconfiguration within MkDocs.

edit wrong forum for issue

Try going here

This is the link from the menu in the documentation under Backup & Restore -> mailcow-internal backups -> Recover accidentally deleted data.

Hi, thanks a lot for bringing SOGo-themeing back!

I don't know if its missing in documentation or its just me not understanding it right or my configuration - but theming works for me only if I manually add SOGoUIxDebugEnabled = YES; to data/conf/sogo/sogo.conf. (Tested on two different servers).

Hello,

in the Quik Install part of https://mailcow.github.io/mailcow-dockerized-docs/install/
at Point 1, after

chmod +x /usr/local/bin/docker-compose

Add the following for make it easier for docker newbies.

For example on Centos 7
systemctl enable docker
systemctl start docker

Thanks :)

Hey,

i use gitea via mailcow and had problems cloning repositories via ssh. Now it works with a small change in the configuration I think in the instructions is a small error.

Under step 3 following is written:

Open mailcow.conf and define the binding you want gitea to use for SSH. Example:
GITEA_SSH_PORT=127.0.0.1:4000
but i think the variable should be:
GITEA_SSH_PORT=4000

with this its works propperly for me

Similarly to how you provide instructions for Roundcube or NextCloud, could there be instructions on how to use mailcow with ONLYOFFICE Mail, including OAuth2?

Relevant issue in the docker repos: docker/for-linux#844

Short summary of the issue: enabling docker IPv6 support can drop the default route if the route was obtained via router advertisement, rendering IPv6 on the host unusable. This is due to the fact that docker enables IPv6 forwarding, which in turn drops routes obtained via router advertisement, unless net.ipv6.conf.<iface>.accept_ra=2 is set during boot.

This is not the fault of mailcow, but could affect mailcow users (like me) and send them on an hourlong hunt (again, like me :D), so I'd appreciate that being added to the documentation, possibly in the "General Troubleshooting" section.

A post explaining a different solution: https://strugglers.net/~andy/blog/2011/09/04/linux-ipv6-router-advertisements-and-forwarding/

my docker deamon completly disable ipv6 so nginx also sould be fixed

nginx: [emerg] socket() [::]:8081 failed (97: Address family not supported by protocol)
nginx: configuration file /etc/nginx/nginx.conf test failed

grep '::' data/conf/nginx/*
data/conf/nginx/dynmaps.conf:  listen [::]:8081;
grep: data/conf/nginx/includes: Is a directory
data/conf/nginx/listen_plain.active:listen [::]:80;
data/conf/nginx/listen_ssl.active:listen [::]:443 ssl http2;

this document not mention it;
mailcow-dockerized-docs/docs/post_installation/firststeps-disable_ipv6.en.md

Hi André,
this repo is missing a license. Is this on purpose or just an oversight?

Mailcow's client documentation link (e.g. https://mailcow.github.io/mailcow-dockerized-docs/client/#host=example.com&email=name%40example.com&name=Name&port=443 ) imposes a serious problem as clicking it exposes highly personal data to a third party. I was quite surprised when I clicked that link and saw my private mail address on a github query string. Apart from personal preference this is most likely a GDPR relevant problem. Self hosting would be a solution to this problem.

Looking at mailcow's license the GNU FDL comes to my mind but this article suggests the Creative Commons' CC-BY-SA license might be a better choice.

in the section : third_party

I wonder if it's possible to explain how to add a generic domain / subdomain
like howto make server_name mywebsite.com;
pointing to root ./mywebsite;

Regards!

Actually it says:

I just installed Docker and did docker-compose pull. I was wondering why the first try ended in "no space left on device". I freed some space and pulled again. Result:

# du -sh /var/lib/docker
22G     /var/lib/docker

Hello Andre,
I saw that you removed the Rainloop instructions, why did you remove them? I think a lot of people will actually like to use Rainloop :)

6183ef3

Best wishes,
Timo

removed

Maybe only blank lines are missing for the markdown renderer, to correctly render the code bloks

I'm not very familiar with modern email suites. I was aware of DNSBL, but was surprised to find that, for example, rspamd is constantly downloading fuzzy data from its and Mailcow servers.
It seems I'm not the only one: @immanuelfodor in his post wrote:

Rspamd accessing an external Internet resource in every 5-7s seems fairly bogus to me, not to mention the possible load on the destination site originating from all other Mailcow instances if it's not only mine (DoS).

@andryyy considered that statement ridiculous and toxic, however I find it totally valid: I'd ask the same question because I'm not aware of how often should DNSBL queries perform and what amount of data to expect from it and rspamd, and would think that something misbehaves.

I'd like to add all external resources which Mailcow use in the documentation, its type, query frequency and estimated amount of data transfer. Right now I found the following:

1. RBL/SURBL/URIBL are listed in default rspamd configuration and added by mailcow configuration.
   Rspamd refreshes the list of whitelisted domains from https://maps.rspamd.com/rspamd/surbl-whitelist.inc.zst
2. Phishing lists are loaded in default rspamd configuration: (https://www.openphish.com/feed.txt, https://maps.rspamd.com/rspamd/redirectors.inc.zst). Phishtank module is disabled in maincow configuration.
3. Message ID lists for some domains are updated from https://maps.rspamd.com/rspamd/mid.inc.zst [reference]
4. ASN lookups are performed via asn.rspamd.com, asn6.rspamd.com (rspamd config, mailcow config)
5. Abuse URL maps are downloaded from https://urlhaus.abuse.ch/downloads/text_online/, ttps://bazaar.abuse.ch/export/txt/md5/recent/ [maincow config]
6. Rspamd fuzzy servers: default rspamd server (uzzy1.rspamd.com:11335,fuzzy2.rspamd.com:11335) and Mailcow server (fuzzy.mailcow.email:11445)

Is this list correct and full, did I miss anything? If everything seems right, I'll prepare documentation update.

May I request an update for this file:

• https://github.com/mailcow/mailcow-dockerized-docs/blob/master/docs/install.md - (Line 36)

The docker-compose.yml-snippet from https://mailcow.github.io/mailcow-dockerized-docs/firststeps-logging/#logging-drivers doesn't work:

ERROR: The Compose file './docker-compose.yml' is invalid because:
services.unbound-mailcow.logging value Additional properties are not allowed ('log_driver' was unexpected)

The following definition must be added for each service instead:

      logging:
        driver: gelf
        options:
          gelf-address: "udp://localhost:12201"
          tag: "mailcow-logs"

followed the document to install Roundcube but it is not working, it was installed but not able to compose the new email.

Please someone need to update the document on https://mailcow.github.io/mailcow-dockerized-docs/third_party-roundcube/