From acc17755255fad1399742ac9c038009da8cb7873 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Wed, 15 Nov 2023 09:51:14 +0200 Subject: [PATCH] Add notes about interoperability Fixes https://github.com/mother-of-all-self-hosting/mash-playbook/issues/118 --- docs/README.md | 4 ++++ docs/configuring-playbook.md | 2 ++ docs/interoperability.md | 36 ++++++++++++++++++++++++++++++++++++ docs/services/traefik.md | 17 ++++++++++++++++- examples/vars.yml | 3 +++ 5 files changed, 61 insertions(+), 1 deletion(-) create mode 100644 docs/interoperability.md diff --git a/docs/README.md b/docs/README.md index c75d9ee..1b3656e 100644 --- a/docs/README.md +++ b/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) diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index f27330d..5df648d 100644 --- a/docs/configuring-playbook.md +++ b/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). diff --git a/docs/interoperability.md b/docs/interoperability.md new file mode 100644 index 0000000..b009df4 --- /dev/null +++ b/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 +``` diff --git a/docs/services/traefik.md b/docs/services/traefik.md index 9299ec5..2e9a406 100644 --- a/docs/services/traefik.md +++ b/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 diff --git a/examples/vars.yml b/examples/vars.yml index 90fa27b..d05b975 100644 --- a/examples/vars.yml +++ b/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