Add notes about interoperability

Fixes https://github.com/mother-of-all-self-hosting/mash-playbook/issues/118

docs/README.md

@@ -2,10 +2,14 @@
 
 - [Prerequisites](prerequisites.md) - go here to a guided installation using this Ansible playbook
 
+- [Configuring DNS](configuring-dns.md)
+
 - [Getting this playbook's source code](getting-the-playbook.md)
 
 - [Configuring the playbook](configuring-playbook.md)
 
+- [Configuring interoperability with other services](interoperability.md)
+
 - [Installing](installing.md)
 
 - [Importing an existing Postgres database (from another installation)](services/postgres.md#importing) (optional)

docs/configuring-playbook.md

@@ -17,4 +17,6 @@ You can then follow these steps inside the playbook directory:
 
 5. edit the inventory hosts file (`inventory/hosts`) to your liking
 
+If you're installing services on the same server using another playbook (like [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy)) or you already have [Traefik](./services/traefik.md) or [Docker](./services/docker.md) installed on the server, consult our [Interoperability](./interoperability.md) documentation.
+
 When you're done with all the configuration you'd like to do, continue with [Installing](installing.md).

docs/interoperability.md

@@ -0,0 +1,36 @@
+# Configuring interoperability with other services
+
+This playbook tries to get you up and running with minimal effort and provided you have followed the [example `vars.yml` file](../examples/vars.yml), will install the [Traefik](services/traefik.md) reverse-proxy server by default.
+
+Sometimes, you're using a server which already has Traefik. In such cases these are undesirable:
+
+- the playbook trying to run its own Traefik instance and running into a conflict with your other Traefik instance over ports (`tcp/80` and `tcp/443`)
+
+- multiple playbooks trying to install Docker, etc.
+
+Below, we offer some suggestions for how to make this playbook more interoperable. Feel free to cherry-pick the parts that make sense for your setup.
+
+
+## Disabling Traefik installation
+
+If you're installing [Traefik](services/traefik.md) on your server in another way, you can use your already installed Traefik instance and [disable the Traefik instance installed by MASH](services/traefik.md#using-another-traefik-instance-not-installing-traefik).
+
+If you are using the [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy) playbook, it already runs its own Traefik instance (`matrix-traefik`). We recommend that you [disable the Traefik instance installed by MASH](services/traefik.md#using-another-traefik-instance-not-installing-traefik), because the Traefik instance installed by the Matrix playbook does the same, but also contains additional configuration for handling the Matrix federation port (`8448`).
+
+
+## Disabling Docker installation
+
+If you're installing [Docker](https://www.docker.com/) on your server in another way, disable this component from the playbook:
+
+```yaml
+mash_playbook_docker_installation_enabled: false
+```
+
+
+## Disabling timesyncing (systemd-timesyncd / ntp) installation
+
+If you're installing `systemd-timesyncd` or `ntp` on your server in another way, disable this component from the playbook:
+
+```yaml
+devture_timesync_installation_enabled: false
+```

docs/services/traefik.md

@@ -2,7 +2,7 @@
 
 [Traefik](https://doc.traefik.io/traefik/) is a container-aware reverse-proxy server.
 
-Many of the services installed by this playbook need to be exposed to the web (HTTP/HTTPS). This is handled by Traefik.
+Many of the services installed by this playbook need to be exposed to the web (HTTP/HTTPS). This is handled by Traefik, which is installed by default if you have used the [example `vars.yml` file](../../examples/vars.yml).
 
 Enabling the Traefik service will automatically wire all other services to use it.
 
@@ -42,6 +42,21 @@ This [Ansible role we use for Traefik](https://github.com/devture/com.devture.an
 
 Below, you can find some guidance about common tweaks you may wish to do.
 
+## Using another Traefik instance (not installing Traefik)
+
+Sometimes you may already have a Traefik instance running on the server and you may wish to not have the playbook install Traefik.
+
+To tell the playbook that you're running a Traefik instance and you'd still like all services installed by the playbook to be connected to that Traefik instance, you need the following configuration:
+
+```yml
+# Tell the playbook you're using Traefik installed in another way.
+# It won't bother installing Traefik.
+nextcloud_playbook_reverse_proxy_type: other-traefik-container
+
+# Tell the playbook to attach services which require reverse-proxying to an additional network by default (e.g. traefik)
+# This needs to match your Traefik network.
+mash_playbook_reverse_proxyable_services_additional_network: traefik
+```
 
 ## Increase logging verbosity
 

examples/vars.yml

@@ -70,6 +70,9 @@ devture_timesync_installation_enabled: true
 # Most services require a reverse-proxy, so we enable Traefik here.
 #
 # Learn more about the Traefik service in docs/services/traefik.md
+#
+# If your server already runs Traefik, you will run into port conflicts by installing it twice.
+# See docs/interoperability.md for solutions.
 
 mash_playbook_reverse_proxy_type: playbook-managed-traefik