hosting/mash-playbook
1
0
Fork 0
Code Pull requests Activity

Add support for KeyDB and do not recommend Redis anymore

Browse source 
Fixes https://github.com/mother-of-all-self-hosting/mash-playbook/issues/175
This commit is contained in:
Slavi Pantaleev 2024-03-26 17:19:03 +02:00
parent 0cc9223391
commit 9109b0badc
14 changed files with 310 additions and 232 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
docs/running-multiple-instances.md
View file

@ -4,11 +4,11 @@ The way this playbook is structured, each Ansible role can only be invoked once
If you need multiple instances (of whichever service), you'll need some workarounds as described below. If you need multiple instances (of whichever service), you'll need some workarounds as described below.
The example below focuses on hosting multiple [Redis](services/redis.md) instances, but you can apply it to hosting multiple instances or whole stacks of any kind. The example below focuses on hosting multiple [KeyDB](services/keydb.md) instances, but you can apply it to hosting multiple instances or whole stacks of any kind.
Let's say you're managing a host called `mash.example.com` which installs both [PeerTube](services/peertube.md) and [NetBox](services/netbox.md). Both of these services require a [Redis](services/redis.md) instance. If you simply add `redis_enabled: true` to your `mash.example.com` host's `vars.yml` file, you'd get a Redis instance (`mash-redis`), but it's just one instance. As described in our [Redis](services/redis.md) documentation, this is a security problem and potentially fragile as both services may try to read/write the same data and get in conflict with one another. Let's say you're managing a host called `mash.example.com` which installs both [PeerTube](services/peertube.md) and [NetBox](services/netbox.md). Both of these services require a [KeyDB](services/keydb.md) instance. If you simply add `keydb_enabled: true` to your `mash.example.com` host's `vars.yml` file, you'd get a KeyDB instance (`mash-keydb`), but it's just one instance. As described in our [KeyDB](services/keydb.md) documentation, this is a security problem and potentially fragile as both services may try to read/write the same data and get in conflict with one another.
We propose that you **don't** add `redis_enabled: true` to your main `mash.example.com` file, but do the following: We propose that you **don't** add `keydb_enabled: true` to your main `mash.example.com` file, but do the following:
## Re-do your inventory to add supplementary hosts ## Re-do your inventory to add supplementary hosts
@ -40,7 +40,7 @@ When running Ansible commands later on, you can use the `-l` flag to limit which
## Adjust the configuration of the supplementary hosts to use a new "namespace" ## Adjust the configuration of the supplementary hosts to use a new "namespace"
Multiple hosts targetting the same server as described above still causes conflicts, because services will use the same paths (e.g. `/mash/redis`) and service/container names (`mash-redis`) everywhere. Multiple hosts targetting the same server as described above still causes conflicts, because services will use the same paths (e.g. `/mash/keydb`) and service/container names (`mash-keydb`) everywhere.
To avoid conflicts, adjust the `vars.yml` file for the new hosts (`mash.example.com-netbox-deps` and `mash.example.com-peertube-deps`) To avoid conflicts, adjust the `vars.yml` file for the new hosts (`mash.example.com-netbox-deps` and `mash.example.com-peertube-deps`)
and set non-default and unique values in the `mash_playbook_service_identifier_prefix` and `mash_playbook_service_base_directory_name_prefix` variables. Examples below: and set non-default and unique values in the `mash_playbook_service_identifier_prefix` and `mash_playbook_service_base_directory_name_prefix` variables. Examples below:
@ -73,15 +73,15 @@ mash_playbook_service_base_directory_name_prefix: 'netbox-'
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
``` ```
@ -114,30 +114,30 @@ mash_playbook_service_base_directory_name_prefix: 'peertube-'
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
``` ```
The above configuration will create **2** Redis instances: The above configuration will create **2** KeyDB instances:
- `mash-netbox-redis` with its base data path in `/mash/netbox-redis` - `mash-netbox-keydb` with its base data path in `/mash/netbox-keydb`
- `mash-peertube-redis` with its base data path in `/mash/peertube-redis` - `mash-peertube-keydb` with its base data path in `/mash/peertube-keydb`
These instances reuse the `mash` user and group and the `/mash` data path, but are not in conflict with each other. These instances reuse the `mash` user and group and the `/mash` data path, but are not in conflict with each other.
## Adjust the configuration of the base host ## Adjust the configuration of the base host
Now that we've created separate Redis instances for both PeerTube and NetBox, we need to put them to use by editing the `vars.yml` file of the main host (the one that installs PeerTbue and NetBox) to wire them to their Redis instances. Now that we've created separate KeyDB instances for both PeerTube and NetBox, we need to put them to use by editing the `vars.yml` file of the main host (the one that installs PeerTbue and NetBox) to wire them to their KeyDB instances.
You'll need configuration (`inventory/host_vars/mash.example.com/vars.yml`) like this: You'll need configuration (`inventory/host_vars/mash.example.com/vars.yml`) like this:
@ -152,17 +152,17 @@ netbox_enabled: true
# Other NetBox configuration here # Other NetBox configuration here
# Point NetBox to its dedicated Redis instance # Point NetBox to its dedicated KeyDB instance
netbox_environment_variable_redis_host: mash-netbox-redis netbox_environment_variable_redis_host: mash-netbox-keydb
netbox_environment_variable_redis_cache_host: mash-netbox-redis netbox_environment_variable_redis_cache_host: mash-netbox-keydb
# Make sure the NetBox service (mash-netbox.service) starts after its dedicated Redis service (mash-netbox-redis.service) # Make sure the NetBox service (mash-netbox.service) starts after its dedicated KeyDB service (mash-netbox-keydb.service)
netbox_systemd_required_services_list_custom: netbox_systemd_required_services_list_custom:
- mash-netbox-redis.service - mash-netbox-keydb.service
# Make sure the NetBox container is connected to the container network of its dedicated Redis service (mash-netbox-redis) # Make sure the NetBox container is connected to the container network of its dedicated KeyDB service (mash-netbox-keydb)
netbox_container_additional_networks_custom: netbox_container_additional_networks_custom:
- mash-netbox-redis - mash-netbox-keydb
######################################################################## ########################################################################
# # # #
@ -180,16 +180,16 @@ netbox_container_additional_networks_custom:
# Other PeerTube configuration here # Other PeerTube configuration here
# Point PeerTube to its dedicated Redis instance # Point PeerTube to its dedicated KeyDB instance
peertube_config_redis_hostname: mash-peertube-redis peertube_config_redis_hostname: mash-peertube-keydb
# Make sure the PeerTube service (mash-peertube.service) starts after its dedicated Redis service (mash-peertube-redis.service) # Make sure the PeerTube service (mash-peertube.service) starts after its dedicated KeyDB service (mash-peertube-keydb.service)
peertube_systemd_required_services_list_custom: peertube_systemd_required_services_list_custom:
- "mash-peertube-redis.service" - "mash-peertube-keydb.service"
# Make sure the PeerTube container is connected to the container network of its dedicated Redis service (mash-peertube-redis) # Make sure the PeerTube container is connected to the container network of its dedicated KeyDB service (mash-peertube-keydb)
peertube_container_additional_networks_custom: peertube_container_additional_networks_custom:
- "mash-peertube-redis" - "mash-peertube-keydb"
######################################################################## ########################################################################
# # # #
@ -201,9 +201,9 @@ peertube_container_additional_networks_custom:
## Questions & Answers ## Questions & Answers
**Can't I just use the same Redis instance for multiple services?** **Can't I just use the same KeyDB instance for multiple services?**
> You may or you may not. See the [Redis](services/redis.md) documentation for why you shouldn't do this. > You may or you may not. See the [KeyDB](services/keydb.md) documentation for why you shouldn't do this.
**Can't I just create one host and a separate stack for each service** (e.g. Nextcloud + all dependencies on one inventory host; PeerTube + all dependencies on another inventory host; with both inventory hosts targetting the same server)? **Can't I just create one host and a separate stack for each service** (e.g. Nextcloud + all dependencies on one inventory host; PeerTube + all dependencies on another inventory host; with both inventory hosts targetting the same server)?

16
docs/services/authelia.md
View file

@ -16,9 +16,9 @@ This service requires the following other services:
- (optional) a MySQL / [MariaDB](mariadb.md) database - if enabled for your Ansible inventory host (and you don't also enable Postgres), Authelia will be connected to the MariaDB server automatically - (optional) a MySQL / [MariaDB](mariadb.md) database - if enabled for your Ansible inventory host (and you don't also enable Postgres), Authelia will be connected to the MariaDB server automatically
- or SQLite, used by default when none of the above database choices is enabled for your Ansible inventory host - or SQLite, used by default when none of the above database choices is enabled for your Ansible inventory host
- (optional, but recommended) [Redis](redis.md) - (optional, but recommended) [KeyDB](keydb.md)
- for storing session information in a persistent manner - for storing session information in a persistent manner
- if Redis is not enabled, session information is stored in-memory and restarting Authelia destroys user sessions - if KeyDB is not enabled, session information is stored in-memory and restarting Authelia destroys user sessions
- a [Traefik](traefik.md) reverse-proxy server - a [Traefik](traefik.md) reverse-proxy server
- for serving the Authelia portal website - for serving the Authelia portal website
@ -87,11 +87,11 @@ authelia_config_access_control_rules:
- domain: 'service1.example.com' - domain: 'service1.example.com'
policy: one_factor policy: one_factor
# The configuration below connects Authelia to the Redis instance, for session storage purposes. # The configuration below connects Authelia to the KeyDB instance, for session storage purposes.
# You may wish to run a separate Redis instance for Authelia, because Redis is not multi-tenant. # You may wish to run a separate KeyDB instance for Authelia, because KeyDB is not multi-tenant.
# Read more in docs/services/redis.md. # Read more in docs/services/redis.md.
# If Redis is not available, session data will be stored in memory and will be lost on container restart. # If KeyDB is not available, session data will be stored in memory and will be lost on container restart.
authelia_config_session_redis_host: "{{ redis_identifier if redis_enabled else '' }}" authelia_config_session_redis_host: "{{ keydb_identifier if keydb_enabled else '' }}"
######################################################################## ########################################################################
# # # #
@ -111,9 +111,9 @@ On the Authelia base URL, there's a portal website where you can log in and mana
### Session storage ### Session storage
As mentioned in the default configuration above (see `authelia_config_session_redis_host`), you may wish to run [Redis](redis.md) for storing session data. As mentioned in the default configuration above (see `authelia_config_session_redis_host`), you may wish to run [KeyDB](keydb.md) for storing session data.
You may wish to run a separate Redis instance for Authelia, because Redis is not multi-tenant. See [our Redis documentation page](redis.md) for additional details. When running a separate instance of Redis, you may need to connect Authelia to the Redis instance's container network via the `authelia_container_additional_networks_custom` variable. You may wish to run a separate KeyDB instance for Authelia, because KeyDB is not multi-tenant. See [our KeyDB documentation page](keydb.md) for additional details. When running a separate instance of KeyDB, you may need to connect Authelia to the KeyDB instance's container network via the `authelia_container_additional_networks_custom` variable.
### Authentication storage providers ### Authentication storage providers

60
docs/services/authentik.md
View file

@ -10,7 +10,7 @@
This service requires the following other services: This service requires the following other services:
- a [Postgres](postgres.md) database - a [Postgres](postgres.md) database
- a [Redis](redis.md) data-store, installation details [below](#redis) - a [KeyDB](keydb.md) data-store, installation details [below](#keydb)
- a [Traefik](traefik.md) reverse-proxy server - a [Traefik](traefik.md) reverse-proxy server
@ -32,7 +32,7 @@ authentik_hostname: authentik.example.com
# Put a strong secret below, generated with `pwgen -s 64 1` or in another way # Put a strong secret below, generated with `pwgen -s 64 1` or in another way
authentik_secret_key: '' authentik_secret_key: ''
# Redis configuration, as described below # KeyDB configuration, as described below
######################################################################## ########################################################################
# # # #
@ -41,28 +41,28 @@ authentik_secret_key: ''
######################################################################## ########################################################################
``` ```
### Redis ### KeyDB
As described on the [Redis](redis.md) documentation page, if you're hosting additional services which require Redis on the same server, you'd better go for installing a separate Redis instance for each service. See [Creating a Redis instance dedicated to authentik](#creating-a-redis-instance-dedicated-to-authentik). As described on the [KeyDB](keydb.md) documentation page, if you're hosting additional services which require KeyDB on the same server, you'd better go for installing a separate KeyDB instance for each service. See [Creating a KeyDB instance dedicated to authentik](#creating-a-keydb-instance-dedicated-to-authentik).
If you're only running authentik on this server and don't need to use Redis for anything else, you can [use a single Redis instance](#using-the-shared-redis-instance-for-authentik). If you're only running authentik on this server and don't need to use KeyDB for anything else, you can [use a single KeyDB instance](#using-the-shared-keydb-instance-for-authentik).
#### Using the shared Redis instance for authentik #### Using the shared KeyDB instance for authentik
To install a single (non-dedicated) Redis instance (`mash-redis`) and hook authentik to it, add the following **additional** configuration: To install a single (non-dedicated) KeyDB instance (`mash-keydb`) and hook authentik to it, add the following **additional** configuration:
```yaml ```yaml
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
@ -75,16 +75,16 @@ redis_enabled: true
# Base configuration as shown above # Base configuration as shown above
# Point authentik to the shared Redis instance # Point authentik to the shared KeyDB instance
authentik_config_redis_hostname: "{{ redis_identifier }}" authentik_config_redis_hostname: "{{ keydb_identifier }}"
# Make sure the authentik service (mash-authentik.service) starts after the shared Redis service (mash-redis.service) # Make sure the authentik service (mash-authentik.service) starts after the shared KeyDB service (mash-keydb.service)
authentik_systemd_required_services_list_custom: authentik_systemd_required_services_list_custom:
- "{{ redis_identifier }}.service" - "{{ keydb_identifier }}.service"
# Make sure the authentik container is connected to the container network of the shared Redis service (mash-redis) # Make sure the authentik container is connected to the container network of the shared KeyDB service (mash-keydb)
authentik_container_additional_networks_custom: authentik_container_additional_networks_custom:
- "{{ redis_identifier }}" - "{{ keydb_identifier }}"
######################################################################## ########################################################################
# # # #
@ -93,12 +93,12 @@ authentik_container_additional_networks_custom:
######################################################################## ########################################################################
``` ```
This will create a `mash-redis` Redis instance on this host. This will create a `mash-keydb` KeyDB instance on this host.
This is only recommended if you won't be installing other services which require Redis. Alternatively, go for [Creating a Redis instance dedicated to authentik](#creating-a-redis-instance-dedicated-to-authentik). This is only recommended if you won't be installing other services which require KeyDB. Alternatively, go for [Creating a KeyDB instance dedicated to authentik](#creating-a-keydb-instance-dedicated-to-authentik).
#### Creating a Redis instance dedicated to authentik #### Creating a KeyDB instance dedicated to authentik
The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation. The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation.
@ -134,20 +134,20 @@ mash_playbook_service_base_directory_name_prefix: 'authentik-'
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
``` ```
This will create a `mash-authentik-redis` instance on this host with its data in `/mash/authentik-redis`. This will create a `mash-authentik-keydb` instance on this host with its data in `/mash/authentik-keydb`.
Then, adjust your main inventory host's variables file (`inventory/host_vars/authentik.example.com/vars.yml`) like this: Then, adjust your main inventory host's variables file (`inventory/host_vars/authentik.example.com/vars.yml`) like this:
@ -160,16 +160,16 @@ Then, adjust your main inventory host's variables file (`inventory/host_vars/aut
# Base configuration as shown above # Base configuration as shown above
# Point authentik to its dedicated Redis instance # Point authentik to its dedicated KeyDB instance
authentik_config_redis_hostname: mash-authentik-redis authentik_config_redis_hostname: mash-authentik-keydb
# Make sure the authentik service (mash-authentik.service) starts after its dedicated Redis service (mash-authentik-redis.service) # Make sure the authentik service (mash-authentik.service) starts after its dedicated KeyDB service (mash-authentik-keydb.service)
authentik_systemd_required_services_list_custom: authentik_systemd_required_services_list_custom:
- "mash-authentik-redis.service" - "mash-authentik-keydb.service"
# Make sure the authentik container is connected to the container network of its dedicated Redis service (mash-authentik-redis) # Make sure the authentik container is connected to the container network of its dedicated KeyDB service (mash-authentik-keydb)
authentik_container_additional_networks_custom: authentik_container_additional_networks_custom:
- "mash-authentik-redis" - "mash-authentik-keydb"
######################################################################## ########################################################################
# # # #
@ -181,7 +181,7 @@ authentik_container_additional_networks_custom:
## Installation ## Installation
If you've decided to install a dedicated Redis instance for authentik, make sure to first do [installation](../installing.md) for the supplementary inventory host (e.g. `authentik.example.com-deps`), before running installation for the main one (e.g. `authentik.example.com`). If you've decided to install a dedicated KeyDB instance for authentik, make sure to first do [installation](../installing.md) for the supplementary inventory host (e.g. `authentik.example.com-deps`), before running installation for the main one (e.g. `authentik.example.com`).
## Usage ## Usage

60
docs/services/funkwhale.md
View file

@ -8,7 +8,7 @@
This service requires the following other services: This service requires the following other services:
- a [Postgres](postgres.md) database - a [Postgres](postgres.md) database
- a [Redis](redis.md) data-store, installation details [below](#redis) - a [KeyDB](keydb.md) data-store, installation details [below](#keydb)
- a [Traefik](traefik.md) reverse-proxy server - a [Traefik](traefik.md) reverse-proxy server
@ -30,7 +30,7 @@ funkwhale_hostname: mash.example.com
# Put a strong secret below, generated with `pwgen -s 64 1` or in another way # Put a strong secret below, generated with `pwgen -s 64 1` or in another way
funkwhale_django_secret_key: '' funkwhale_django_secret_key: ''
# Redis configuration, as described below # KeyDB configuration, as described below
######################################################################## ########################################################################
# # # #
@ -39,28 +39,28 @@ funkwhale_django_secret_key: ''
######################################################################## ########################################################################
``` ```
### Redis ### KeyDB
As described on the [Redis](redis.md) documentation page, if you're hosting additional services which require Redis on the same server, you'd better go for installing a separate Redis instance for each service. See [Creating a Redis instance dedicated to funkwhale](#creating-a-redis-instance-dedicated-to-funkwhale). As described on the [KeyDB](keydb.md) documentation page, if you're hosting additional services which require KeyDB on the same server, you'd better go for installing a separate KeyDB instance for each service. See [Creating a KeyDB instance dedicated to funkwhale](#creating-a-keydb-instance-dedicated-to-funkwhale).
If you're only running funkwhale on this server and don't need to use Redis for anything else, you can [use a single Redis instance](#using-the-shared-redis-instance-for-funkwhale). If you're only running funkwhale on this server and don't need to use KeyDB for anything else, you can [use a single KeyDB instance](#using-the-shared-keydb-instance-for-funkwhale).
#### Using the shared Redis instance for funkwhale #### Using the shared KeyDB instance for funkwhale
To install a single (non-dedicated) Redis instance (`mash-redis`) and hook funkwhale to it, add the following **additional** configuration: To install a single (non-dedicated) KeyDB instance (`mash-keydb`) and hook funkwhale to it, add the following **additional** configuration:
```yaml ```yaml
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
@ -73,16 +73,16 @@ redis_enabled: true
# Base configuration as shown above # Base configuration as shown above
# Point funkwhale to the shared Redis instance # Point funkwhale to the shared KeyDB instance
funkwhale_config_redis_hostname: "{{ redis_identifier }}" funkwhale_config_redis_hostname: "{{ keydb_identifier }}"
# Make sure the funkwhale API service (mash-funkwhale-api.service) starts after the shared Redis service # Make sure the funkwhale API service (mash-funkwhale-api.service) starts after the shared KeyDB service
funkwhale_api_systemd_required_services_list_custom: funkwhale_api_systemd_required_services_list_custom:
- "{{ redis_identifier }}.service" - "{{ keydb_identifier }}.service"
# Make sure the funkwhale API service (mash-funkwhale-api.service) is connected to the container network of the shared Redis service # Make sure the funkwhale API service (mash-funkwhale-api.service) is connected to the container network of the shared KeyDB service
funkwhale_api_container_additional_networks_custom: funkwhale_api_container_additional_networks_custom:
- "{{ redis_container_network }}" - "{{ keydb_container_network }}"
######################################################################## ########################################################################
# # # #
@ -91,12 +91,12 @@ funkwhale_api_container_additional_networks_custom:
######################################################################## ########################################################################
``` ```
This will create a `mash-redis` Redis instance on this host. This will create a `mash-keydb` KeyDB instance on this host.
This is only recommended if you won't be installing other services which require Redis. Alternatively, go for [Creating a Redis instance dedicated to funkwhale](#creating-a-redis-instance-dedicated-to-funkwhale). This is only recommended if you won't be installing other services which require KeyDB. Alternatively, go for [Creating a KeyDB instance dedicated to funkwhale](#creating-a-keydb-instance-dedicated-to-funkwhale).
#### Creating a Redis instance dedicated to funkwhale #### Creating a KeyDB instance dedicated to funkwhale
The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation. The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation.
@ -132,20 +132,20 @@ mash_playbook_service_base_directory_name_prefix: 'funkwhale-'
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
``` ```
This will create a `mash-funkwhale-redis` instance on this host with its data in `/mash/funkwhale-redis`. This will create a `mash-funkwhale-keydb` instance on this host with its data in `/mash/funkwhale-keydb`.
Then, adjust your main inventory host's variables file (`inventory/host_vars/funkwhale.example.com/vars.yml`) like this: Then, adjust your main inventory host's variables file (`inventory/host_vars/funkwhale.example.com/vars.yml`) like this:
@ -158,16 +158,16 @@ Then, adjust your main inventory host's variables file (`inventory/host_vars/fun
# Base configuration as shown above # Base configuration as shown above
# Point funkwhale to its dedicated Redis instance # Point funkwhale to its dedicated KeyDB instance
funkwhale_config_redis_hostname: mash-funkwhale-redis funkwhale_config_redis_hostname: mash-funkwhale-keydb
# Make sure the funkwhale API service (mash-funkwhale-api.service) starts after its dedicated Redis service # Make sure the funkwhale API service (mash-funkwhale-api.service) starts after its dedicated KeyDB service
funkwhale_api_systemd_required_services_list_custom: funkwhale_api_systemd_required_services_list_custom:
- "mash-funkwhale-redis.service" - "mash-funkwhale-keydb.service"
# Make sure the funkwhale API service (mash-funkwhale-api.service) is connected to the container network of its dedicated Redis service # Make sure the funkwhale API service (mash-funkwhale-api.service) is connected to the container network of its dedicated KeyDB service
funkwhale_api_container_additional_networks_custom: funkwhale_api_container_additional_networks_custom:
- "mash-funkwhale-redis" - "mash-funkwhale-keydb"
######################################################################## ########################################################################
# # # #
@ -179,7 +179,7 @@ funkwhale_api_container_additional_networks_custom:
## Installation ## Installation
If you've decided to install a dedicated Redis instance for funkwhale, make sure to first do [installation](../installing.md) for the supplementary inventory host (e.g. `funkwhale.example.com-deps`), before running installation for the main one (e.g. `funkwhale.example.com`). If you've decided to install a dedicated KeyDB instance for funkwhale, make sure to first do [installation](../installing.md) for the supplementary inventory host (e.g. `funkwhale.example.com-deps`), before running installation for the main one (e.g. `funkwhale.example.com`).
## Usage ## Usage

39
docs/services/keydb.md Normal file
View file

@ -0,0 +1,39 @@
# KeyDB
[KeyDB](https://docs.keydb.dev/) is an open source, in-memory data store used by millions of developers as a database, cache, streaming engine, and message broker.
We used to advocate for using [Redis](redis.md), but since [Redis is now "source available"](https://redis.com/blog/redis-adopts-dual-source-available-licensing/) we recommend that you use KeyDB instead. KeyDB is compatible with Redis, so switching should be straightforward. You can learn more about the switch from Redis to KeyDB in [this changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/50813c600db1c47b1f3e76707b81fe05d6c46ef5/CHANGELOG.md#backward-compatibility-break-the-playbook-now-defaults-to-keydb-instead-of-redis) for [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy).
Some of the services installed by this playbook require a KeyDB data store.
**Warning**: Because KeyDB is not as flexible as [Postgres](postgres.md) when it comes to authentication and data separation, it's **recommended that you run separate KeyDB instances** (one for each service). KeyDB supports multiple database and a [SELECT](https://docs.keydb.dev/docs/commands/#select) command for switching between them. However, **reusing the same KeyDB instance is not good enough** because:
- if all services use the same KeyDB instance and database (id = 0), services may conflict with one another
- the number of databases is limited to [16 by default](https://github.com/Snapchat/KeyDB/blob/0731a0509a82af5114da1b5aa6cf8ba84c06e134/keydb.conf#L342-L345), which may or may not be enough. With configuration changes, this is solveable.
- some services do not support switching the KeyDB database and always insist on using the default one (id = 0)
- KeyDB [does not support different authentication credentials for its different databases](https://stackoverflow.com/a/37262596), so each service can potentially read and modify other services' data
If you're only hosting a single service (like [PeerTube](peertube.md) or [NetBox](netbox.md)) on your server, you can get away with running a single instance. If you're hosting multiple services, you should prepare separate instances for each service.
## Configuration
To enable this service, add the following configuration to your `vars.yml` file and re-run the [installation](../installing.md) process to **host a single instance of the KeyDB service**:
```yaml
########################################################################
# #
# keydb #
# #
########################################################################
keydb_enabled: true
########################################################################
# #
# /keydb #
# #
########################################################################
```
To **host multiple instances of the KeyDB service**, follow the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation or the **KeyDB** section (if available) of the service you're installing.

58
docs/services/lago.md
View file

@ -8,7 +8,7 @@
This service requires the following other services: This service requires the following other services:
- a [Postgres](postgres.md) database - a [Postgres](postgres.md) database
- a [Redis](redis.md) data-store, installation details [below](#redis) - a [KeyDB](keydb.md) data-store, installation details [below](#keydb)
- a [Traefik](traefik.md) reverse-proxy server - a [Traefik](traefik.md) reverse-proxy server
@ -34,7 +34,7 @@ lago_api_environment_variable_lago_rsa_private_key: ''
# unless you'd like to run a server with public registration enabled. # unless you'd like to run a server with public registration enabled.
lago_front_environment_variable_lago_disable_signup: false lago_front_environment_variable_lago_disable_signup: false
# Redis configuration, as described below # KeyDB configuration, as described below
######################################################################## ########################################################################
# # # #
@ -63,28 +63,28 @@ We recommend installing with public registration enabled at first, creating your
It should be noted that disabling public signup with this variable merely disables the Sign-Up page in the web interface, but [does not actually disable signups due to a Lago bug](https://github.com/getlago/lago/issues/220). It should be noted that disabling public signup with this variable merely disables the Sign-Up page in the web interface, but [does not actually disable signups due to a Lago bug](https://github.com/getlago/lago/issues/220).
### Redis ### KeyDB
As described on the [Redis](redis.md) documentation page, if you're hosting additional services which require Redis on the same server, you'd better go for installing a separate Redis instance for each service. See [Creating a Redis instance dedicated to Lago](#creating-a-redis-instance-dedicated-to-lago). As described on the [KeyDB](keydb.md) documentation page, if you're hosting additional services which require KeyDB on the same server, you'd better go for installing a separate KeyDB instance for each service. See [Creating a KeyDB instance dedicated to Lago](#creating-a-keydb-instance-dedicated-to-lago).
If you're only running Lago on this server and don't need to use Redis for anything else, you can [use a single Redis instance](#using-the-shared-redis-instance-for-lago). If you're only running Lago on this server and don't need to use KeyDB for anything else, you can [use a single KeyDB instance](#using-the-shared-keydb-instance-for-lago).
#### Using the shared Redis instance for Lago #### Using the shared KeyDB instance for Lago
To install a single (non-dedicated) Redis instance (`mash-redis`) and hook Lago to it, add the following **additional** configuration: To install a single (non-dedicated) KeyDB instance (`mash-keydb`) and hook Lago to it, add the following **additional** configuration:
```yaml ```yaml
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
@ -97,16 +97,16 @@ redis_enabled: true
# Base configuration as shown above # Base configuration as shown above
# Point Lago to the shared Redis instance # Point Lago to the shared KeyDB instance
lago_redis_hostname: "{{ redis_identifier }}" lago_redis_hostname: "{{ keydb_identifier }}"
# Make sure the Lago service (mash-lago.service) starts after the shared Redis service (mash-redis.service) # Make sure the Lago service (mash-lago.service) starts after the shared KeyDB service (mash-keydb.service)
lago_api_systemd_required_services_list_custom: lago_api_systemd_required_services_list_custom:
- "{{ redis_identifier }}.service" - "{{ keydb_identifier }}.service"
# Make sure the Lago container is connected to the container network of the shared Redis service (mash-redis) # Make sure the Lago container is connected to the container network of the shared KeyDB service (mash-keydb)
lago_api_container_additional_networks_custom: lago_api_container_additional_networks_custom:
- "{{ redis_identifier }}" - "{{ keydb_identifier }}"
######################################################################## ########################################################################
# # # #
@ -115,11 +115,11 @@ lago_api_container_additional_networks_custom:
######################################################################## ########################################################################
``` ```
This will create a `mash-redis` Redis instance on this host. This will create a `mash-keydb` KeyDB instance on this host.
This is only recommended if you won't be installing other services which require Redis. Alternatively, go for [Creating a Redis instance dedicated to Lago](#creating-a-redis-instance-dedicated-to-lago). This is only recommended if you won't be installing other services which require KeyDB. Alternatively, go for [Creating a KeyDB instance dedicated to Lago](#creating-a-keydb-instance-dedicated-to-lago).
#### Creating a Redis instance dedicated to Lago #### Creating a KeyDB instance dedicated to Lago
The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation. The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation.
@ -155,20 +155,20 @@ mash_playbook_service_base_directory_name_prefix: 'lago-'
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
``` ```
This will create a `mash-lago-redis` instance on this host with its data in `/mash/lago-redis`. This will create a `mash-lago-keydb` instance on this host with its data in `/mash/lago-keydb`.
Then, adjust your main inventory host's variables file (`inventory/host_vars/lago.example.com/vars.yml`) like this: Then, adjust your main inventory host's variables file (`inventory/host_vars/lago.example.com/vars.yml`) like this:
@ -181,16 +181,16 @@ Then, adjust your main inventory host's variables file (`inventory/host_vars/lag
# Base configuration as shown above # Base configuration as shown above
# Point Lago to its dedicated Redis instance # Point Lago to its dedicated KeyDB instance
lago_redis_hostname: mash-lago-redis lago_redis_hostname: mash-lago-keydb
# Make sure the Lago service (mash-lago.service) starts after its dedicated Redis service (mash-lago-redis.service) # Make sure the Lago service (mash-lago.service) starts after its dedicated KeyDB service (mash-lago-keydb.service)
lago_api_systemd_required_services_list_custom: lago_api_systemd_required_services_list_custom:
- "mash-lago-redis.service" - "mash-lago-keydb.service"
# Make sure the Lago container is connected to the container network of its dedicated Redis service (mash-lago-redis) # Make sure the Lago container is connected to the container network of its dedicated KeyDB service (mash-lago-keydb)
lago_api_container_additional_networks_custom: lago_api_container_additional_networks_custom:
- "mash-lago-redis" - "mash-lago-keydb"
######################################################################## ########################################################################
# # # #

64
docs/services/netbox.md
View file

@ -8,7 +8,7 @@
This service requires the following other services: This service requires the following other services:
- a [Postgres](postgres.md) database - a [Postgres](postgres.md) database
- a [Redis](redis.md) data-store, installation details [below](#redis) - a [KeyDB](keydb.md) data-store, installation details [below](#keydb)
- a [Traefik](traefik.md) reverse-proxy server - a [Traefik](traefik.md) reverse-proxy server
@ -38,7 +38,7 @@ netbox_environment_variable_superuser_email: your.email@example.com
# Changing the password subsequently will not affect the user's password. # Changing the password subsequently will not affect the user's password.
netbox_environment_variable_superuser_password: '' netbox_environment_variable_superuser_password: ''
# Redis configuration, as described below # KeyDB configuration, as described below
######################################################################## ########################################################################
# # # #
@ -60,28 +60,28 @@ If `netbox_environment_variable_superuser_*` variables are specified, NetBox wil
[Single-Sign-On](#single-sign-on-sso-integration) is also supported. [Single-Sign-On](#single-sign-on-sso-integration) is also supported.
### Redis ### KeyDB
As described on the [Redis](redis.md) documentation page, if you're hosting additional services which require Redis on the same server, you'd better go for installing a separate Redis instance for each service. See [Creating a Redis instance dedicated to NetBox](#creating-a-redis-instance-dedicated-to-netbox). As described on the [KeyDB](keydb.md) documentation page, if you're hosting additional services which require KeyDB on the same server, you'd better go for installing a separate KeyDB instance for each service. See [Creating a KeyDB instance dedicated to NetBox](#creating-a-keydb-instance-dedicated-to-netbox).
If you're only running NetBox on this server and don't need to use Redis for anything else, you can [use a single Redis instance](#using-the-shared-redis-instance-for-netbox). If you're only running NetBox on this server and don't need to use KeyDB for anything else, you can [use a single KeyDB instance](#using-the-shared-keydb-instance-for-netbox).
#### Using the shared Redis instance for NetBox #### Using the shared KeyDB instance for NetBox
To install a single (non-dedicated) Redis instance (`mash-redis`) and hook NetBox to it, add the following **additional** configuration: To install a single (non-dedicated) KeyDB instance (`mash-keydb`) and hook NetBox to it, add the following **additional** configuration:
```yaml ```yaml
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
@ -94,17 +94,17 @@ redis_enabled: true
# Base configuration as shown above # Base configuration as shown above
# Point NetBox to the shared Redis instance # Point NetBox to the shared KeyDB instance
netbox_environment_variable_redis_host: "{{ redis_identifier }}" netbox_environment_variable_redis_host: "{{ keydb_identifier }}"
netbox_environment_variable_redis_cache_host: "{{ redis_identifier }}" netbox_environment_variable_redis_cache_host: "{{ keydb_identifier }}"
# Make sure the NetBox service (mash-netbox.service) starts after the shared Redis service (mash-redis.service) # Make sure the NetBox service (mash-netbox.service) starts after the shared KeyDB service (mash-keydb.service)
netbox_systemd_required_services_list_custom: netbox_systemd_required_services_list_custom:
- "{{ redis_identifier }}.service" - "{{ keydb_identifier }}.service"
# Make sure the NetBox container is connected to the container network of the shared Redis service (mash-redis) # Make sure the NetBox container is connected to the container network of the shared KeyDB service (mash-keydb)
netbox_container_additional_networks_custom: netbox_container_additional_networks_custom:
- "{{ redis_identifier }}" - "{{ keydb_identifier }}"
######################################################################## ########################################################################
# # # #
@ -113,12 +113,12 @@ netbox_container_additional_networks_custom:
######################################################################## ########################################################################
``` ```
This will create a `mash-redis` Redis instance on this host. This will create a `mash-keydb` KeyDB instance on this host.
This is only recommended if you won't be installing other services which require Redis. Alternatively, go for [Creating a Redis instance dedicated to NetBox](#creating-a-redis-instance-dedicated-to-netbox). This is only recommended if you won't be installing other services which require KeyDB. Alternatively, go for [Creating a KeyDB instance dedicated to NetBox](#creating-a-keydb-instance-dedicated-to-netbox).
#### Creating a Redis instance dedicated to NetBox #### Creating a KeyDB instance dedicated to NetBox
The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation. The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation.
@ -154,20 +154,20 @@ mash_playbook_service_base_directory_name_prefix: 'netbox-'
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
``` ```
This will create a `mash-netbox-redis` instance on this host with its data in `/mash/netbox-redis`. This will create a `mash-netbox-keydb` instance on this host with its data in `/mash/netbox-keydb`.
Then, adjust your main inventory host's variables file (`inventory/host_vars/netbox.example.com/vars.yml`) like this: Then, adjust your main inventory host's variables file (`inventory/host_vars/netbox.example.com/vars.yml`) like this:
@ -181,17 +181,17 @@ Then, adjust your main inventory host's variables file (`inventory/host_vars/net
# Base configuration as shown above # Base configuration as shown above
# Point NetBox to its dedicated Redis instance # Point NetBox to its dedicated KeyDB instance
netbox_environment_variable_redis_host: mash-netbox-redis netbox_environment_variable_redis_host: mash-netbox-keydb
netbox_environment_variable_redis_cache_host: mash-netbox-redis netbox_environment_variable_redis_cache_host: mash-netbox-keydb
# Make sure the NetBox service (mash-netbox.service) starts after its dedicated Redis service (mash-netbox-redis.service) # Make sure the NetBox service (mash-netbox.service) starts after its dedicated KeyDB service (mash-netbox-keydb.service)
netbox_systemd_required_services_list_custom: netbox_systemd_required_services_list_custom:
- "mash-netbox-redis.service" - "mash-netbox-keydb.service"
# Make sure the NetBox container is connected to the container network of its dedicated Redis service (mash-netbox-redis) # Make sure the NetBox container is connected to the container network of its dedicated KeyDB service (mash-netbox-keydb)
netbox_container_additional_networks_custom: netbox_container_additional_networks_custom:
- "mash-netbox-redis" - "mash-netbox-keydb"
######################################################################## ########################################################################
# # # #
@ -257,7 +257,7 @@ For additional environment variables controlling groups and permissions for new
## Installation ## Installation
If you've decided to install a dedicated Redis instance for NetBox, make sure to first do [installation](../installing.md) for the supplementary inventory host (e.g. `netbox.example.com-deps`), before running installation for the main one (e.g. `netbox.example.com`). If you've decided to install a dedicated KeyDB instance for NetBox, make sure to first do [installation](../installing.md) for the supplementary inventory host (e.g. `netbox.example.com-deps`), before running installation for the main one (e.g. `netbox.example.com`).
## Usage ## Usage

76
docs/services/nextcloud.md
View file

@ -9,7 +9,7 @@ This service requires the following other services:
- a [Postgres](postgres.md) database - a [Postgres](postgres.md) database
- a [Traefik](traefik.md) reverse-proxy server - a [Traefik](traefik.md) reverse-proxy server
- (optional) a [Redis](redis.md) data-store, installation details [below](#redis) - (optional) a [KeyDB](keydb.md) data-store, installation details [below](#keydb)
- (optional) the [exim-relay](exim-relay.md) mailer - (optional) the [exim-relay](exim-relay.md) mailer
@ -29,7 +29,7 @@ nextcloud_enabled: true
nextcloud_hostname: mash.example.com nextcloud_hostname: mash.example.com
nextcloud_path_prefix: /nextcloud nextcloud_path_prefix: /nextcloud
# Redis configuration, as described below # KeyDB configuration, as described below
######################################################################## ########################################################################
# # # #
@ -42,23 +42,23 @@ In the example configuration above, we configure the service to be hosted at `ht
You can remove the `nextcloud_path_prefix` variable definition, to make it default to `/`, so that the service is served at `https://mash.example.com/`. You can remove the `nextcloud_path_prefix` variable definition, to make it default to `/`, so that the service is served at `https://mash.example.com/`.
### Redis ### KeyDB
Redis can **optionally** be enabled to improve Nextcloud performance. KeyDB can **optionally** be enabled to improve Nextcloud performance.
It's dubious whether using using Redis helps much, so we recommend that you **start without** it, for a simpler deployment. It's dubious whether using using KeyDB helps much, so we recommend that you **start without** it, for a simpler deployment.
To learn more, read the [Memory caching](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/caching_configuration.html) section of the Nextcloud documentation. To learn more, read the [Memory caching](https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/caching_configuration.html) section of the Nextcloud documentation.
As described on the [Redis](redis.md) documentation page, if you're hosting additional services which require Redis on the same server, you'd better go for installing a separate Redis instance for each service. See [Creating a Redis instance dedicated to Nextcloud](#creating-a-redis-instance-dedicated-to-nextcloud). As described on the [KeyDB](keydb.md) documentation page, if you're hosting additional services which require KeyDB on the same server, you'd better go for installing a separate KeyDB instance for each service. See [Creating a KeyDB instance dedicated to Nextcloud](#creating-a-keydb-instance-dedicated-to-nextcloud).
If you're only running Nextcloud on this server and don't need to use Redis for anything else, you can [use a single Redis instance](#using-the-shared-redis-instance-for-nextcloud). If you're only running Nextcloud on this server and don't need to use KeyDB for anything else, you can [use a single KeyDB instance](#using-the-shared-keydb-instance-for-nextcloud).
**Regardless** of the method of installing Redis, you may need to adjust your Nextcloud configuration file (e.g. `/mash/nextcloud/data/config/config.php`) to **add** this: **Regardless** of the method of installing KeyDB, you may need to adjust your Nextcloud configuration file (e.g. `/mash/nextcloud/data/config/config.php`) to **add** this:
```php ```php
'memcache.distributed' => '\OC\Memcache\Redis', 'memcache.distributed' => '\OC\Memcache\KeyDB',
'memcache.locking' => '\OC\Memcache\Redis', 'memcache.locking' => '\OC\Memcache\KeyDB',
'redis' => [ 'keydb' => [
'host' => 'REDIS_HOSTNAME_HERE', 'host' => 'REDIS_HOSTNAME_HERE',
'port' => 6379, 'port' => 6379,
], ],
@ -66,26 +66,26 @@ If you're only running Nextcloud on this server and don't need to use Redis for
Where `REDIS_HOSTNAME_HERE` is to be replaced with: Where `REDIS_HOSTNAME_HERE` is to be replaced with:
- `mash-nextcloud-redis`, when [Creating a Redis instance dedicated to Nextcloud](#creating-a-redis-instance-dedicated-to-nextcloud) - `mash-nextcloud-keydb`, when [Creating a KeyDB instance dedicated to Nextcloud](#creating-a-keydb-instance-dedicated-to-nextcloud)
- `mash-redis`, when [using a single Redis instance](#using-the-shared-redis-instance-for-nextcloud). - `mash-keydb`, when [using a single KeyDB instance](#using-the-shared-keydb-instance-for-nextcloud).
#### Using the shared Redis instance for Nextcloud #### Using the shared KeyDB instance for Nextcloud
To install a single (non-dedicated) Redis instance (`mash-redis`) and hook Nextcloud to it, add the following **additional** configuration: To install a single (non-dedicated) KeyDB instance (`mash-keydb`) and hook Nextcloud to it, add the following **additional** configuration:
```yaml ```yaml
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
@ -98,16 +98,16 @@ redis_enabled: true
# Base configuration as shown above # Base configuration as shown above
# Point Nextcloud to the shared Redis instance # Point Nextcloud to the shared KeyDB instance
nextcloud_redis_hostname: "{{ redis_identifier }}" nextcloud_redis_hostname: "{{ keydb_identifier }}"
# Make sure the Nextcloud service (mash-nextcloud.service) starts after the shared Redis service (mash-redis.service) # Make sure the Nextcloud service (mash-nextcloud.service) starts after the shared KeyDB service (mash-keydb.service)
nextcloud_systemd_required_services_list_custom: nextcloud_systemd_required_services_list_custom:
- "{{ redis_identifier }}.service" - "{{ keydb_identifier }}.service"
# Make sure the Nextcloud container is connected to the container network of the shared Redis service (mash-redis) # Make sure the Nextcloud container is connected to the container network of the shared KeyDB service (mash-keydb)
nextcloud_container_additional_networks_custom: nextcloud_container_additional_networks_custom:
- "{{ redis_identifier }}" - "{{ keydb_identifier }}"
######################################################################## ########################################################################
# # # #
@ -115,11 +115,11 @@ nextcloud_container_additional_networks_custom:
# # # #
######################################################################## ########################################################################
``` ```
This will create a `mash-redis` Redis instance on this host. This will create a `mash-keydb` KeyDB instance on this host.
This is only recommended if you won't be installing other services which require Redis. Alternatively, go for [Creating a Redis instance dedicated to Nextcloud](#creating-a-redis-instance-dedicated-to-nextcloud). This is only recommended if you won't be installing other services which require KeyDB. Alternatively, go for [Creating a KeyDB instance dedicated to Nextcloud](#creating-a-keydb-instance-dedicated-to-nextcloud).
#### Creating a Redis instance dedicated to Nextcloud #### Creating a KeyDB instance dedicated to Nextcloud
The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation. The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation.
@ -155,20 +155,20 @@ mash_playbook_service_base_directory_name_prefix: 'nextcloud-'
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
``` ```
This will create a `mash-nextcloud-redis` instance on this host with its data in `/mash/nextcloud-redis`. This will create a `mash-nextcloud-keydb` instance on this host with its data in `/mash/nextcloud-keydb`.
Then, adjust your main inventory host's variables file (`inventory/host_vars/nextcloud.example.com/vars.yml`) like this: Then, adjust your main inventory host's variables file (`inventory/host_vars/nextcloud.example.com/vars.yml`) like this:
@ -181,16 +181,16 @@ Then, adjust your main inventory host's variables file (`inventory/host_vars/nex
# Base configuration as shown above # Base configuration as shown above
# Point Nextcloud to its dedicated Redis instance # Point Nextcloud to its dedicated KeyDB instance
nextcloud_redis_hostname: mash-nextcloud-redis nextcloud_redis_hostname: mash-nextcloud-keydb
# Make sure the Nextcloud service (mash-nextcloud.service) starts after its dedicated Redis service (mash-nextcloud-redis.service) # Make sure the Nextcloud service (mash-nextcloud.service) starts after its dedicated KeyDB service (mash-nextcloud-keydb.service)
nextcloud_systemd_required_services_list_custom: nextcloud_systemd_required_services_list_custom:
- "mash-nextcloud-redis.service" - "mash-nextcloud-keydb.service"
# Make sure the Nextcloud container is connected to the container network of its dedicated Redis service (mash-nextcloud-redis) # Make sure the Nextcloud container is connected to the container network of its dedicated KeyDB service (mash-nextcloud-keydb)
nextcloud_container_additional_networks_custom: nextcloud_container_additional_networks_custom:
- "mash-nextcloud-redis" - "mash-nextcloud-keydb"
######################################################################## ########################################################################
# # # #
@ -230,7 +230,7 @@ nextcloud_container_image_customizations_samba_enabled: true
## Installation ## Installation
If you've decided to install a dedicated Redis instance for Nextcloud, make sure to first do [installation](../installing.md) for the supplementary inventory host (e.g. `nextcloud.example.com-deps`), before running installation for the main one (e.g. `nextcloud.example.com`). If you've decided to install a dedicated KeyDB instance for Nextcloud, make sure to first do [installation](../installing.md) for the supplementary inventory host (e.g. `nextcloud.example.com-deps`), before running installation for the main one (e.g. `nextcloud.example.com`).
## Usage ## Usage

12
docs/services/outline.md
View file

@ -8,7 +8,7 @@
This service requires the following other services: This service requires the following other services:
- [Postgres](postgres.md) - [Postgres](postgres.md)
- [Redis](redis.md) - [KeyDB](keydb.md)
- a [Traefik](traefik.md) reverse-proxy server - a [Traefik](traefik.md) reverse-proxy server
@ -30,14 +30,14 @@ outline_hostname: outline.example.com
# This must be generated with: `openssl rand -hex 32` # This must be generated with: `openssl rand -hex 32`
outline_environment_variable_secret_key: '' outline_environment_variable_secret_key: ''
# The configuration below connects Outline to the Redis instance, for session storage purposes. # The configuration below connects Outline to the KeyDB instance, for session storage purposes.
# You may wish to run a separate Redis instance for Outline, because Redis is not multi-tenant. # You may wish to run a separate KeyDB instance for Outline, because KeyDB is not multi-tenant.
# Read more in docs/services/redis.md. # Read more in docs/services/keydb.md.
outline_redis_hostname: "{{ redis_identifier if redis_enabled else '' }}" outline_redis_hostname: "{{ keydb_identifier if keydb_enabled else '' }}"
outline_container_additional_networks_custom: | outline_container_additional_networks_custom: |
{{ {{
[redis_container_network] [keydb_container_network]
}} }}
# By default, files are stored locally. # By default, files are stored locally.

60
docs/services/peertube.md
View file

@ -8,7 +8,7 @@
This service requires the following other services: This service requires the following other services:
- a [Postgres](postgres.md) database - a [Postgres](postgres.md) database
- a [Redis](redis.md) data-store, installation details [below](#redis) - a [KeyDB](keydb.md) data-store, installation details [below](#keydb)
- a [Traefik](traefik.md) reverse-proxy server - a [Traefik](traefik.md) reverse-proxy server
@ -47,7 +47,7 @@ peertube_config_root_user_initial_password: ''
# Then, replace the example IP range below, and re-run the playbook. # Then, replace the example IP range below, and re-run the playbook.
# peertube_trusted_proxies_values_custom: ["172.21.0.0/16"] # peertube_trusted_proxies_values_custom: ["172.21.0.0/16"]
# Redis configuration, as described below # KeyDB configuration, as described below
######################################################################## ########################################################################
# # # #
@ -60,28 +60,28 @@ In the example configuration above, we configure the service to be hosted at `ht
Hosting PeerTube under a subpath (by configuring the `peertube_path_prefix` variable) does not seem to be possible right now, due to PeerTube limitations. Hosting PeerTube under a subpath (by configuring the `peertube_path_prefix` variable) does not seem to be possible right now, due to PeerTube limitations.
### Redis ### KeyDB
As described on the [Redis](redis.md) documentation page, if you're hosting additional services which require Redis on the same server, you'd better go for installing a separate Redis instance for each service. See [Creating a Redis instance dedicated to PeerTube](#creating-a-redis-instance-dedicated-to-peertube). As described on the [KeyDB](keydb.md) documentation page, if you're hosting additional services which require KeyDB on the same server, you'd better go for installing a separate KeyDB instance for each service. See [Creating a KeyDB instance dedicated to PeerTube](#creating-a-keydb-instance-dedicated-to-peertube).
If you're only running PeerTube on this server and don't need to use Redis for anything else, you can [use a single Redis instance](#using-the-shared-redis-instance-for-peertube). If you're only running PeerTube on this server and don't need to use KeyDB for anything else, you can [use a single KeyDB instance](#using-the-shared-keydb-instance-for-peertube).
#### Using the shared Redis instance for PeerTube #### Using the shared KeyDB instance for PeerTube
To install a single (non-dedicated) Redis instance (`mash-redis`) and hook PeerTube to it, add the following **additional** configuration: To install a single (non-dedicated) KeyDB instance (`mash-keydb`) and hook PeerTube to it, add the following **additional** configuration:
```yaml ```yaml
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
@ -94,16 +94,16 @@ redis_enabled: true
# Base configuration as shown above # Base configuration as shown above
# Point PeerTube to the shared Redis instance # Point PeerTube to the shared KeyDB instance
peertube_config_redis_hostname: "{{ redis_identifier }}" peertube_config_redis_hostname: "{{ keydb_identifier }}"
# Make sure the PeerTube service (mash-peertube.service) starts after the shared Redis service (mash-redis.service) # Make sure the PeerTube service (mash-peertube.service) starts after the shared KeyDB service (mash-keydb.service)
peertube_systemd_required_services_list_custom: peertube_systemd_required_services_list_custom:
- "{{ redis_identifier }}.service" - "{{ keydb_identifier }}.service"
# Make sure the PeerTube container is connected to the container network of the shared Redis service (mash-redis) # Make sure the PeerTube container is connected to the container network of the shared KeyDB service (mash-keydb)
peertube_container_additional_networks_custom: peertube_container_additional_networks_custom:
- "{{ redis_identifier }}" - "{{ keydb_identifier }}"
######################################################################## ########################################################################
# # # #
@ -112,12 +112,12 @@ peertube_container_additional_networks_custom:
######################################################################## ########################################################################
``` ```
This will create a `mash-redis` Redis instance on this host. This will create a `mash-keydb` KeyDB instance on this host.
This is only recommended if you won't be installing other services which require Redis. Alternatively, go for [Creating a Redis instance dedicated to PeerTube](#creating-a-redis-instance-dedicated-to-peertube). This is only recommended if you won't be installing other services which require KeyDB. Alternatively, go for [Creating a KeyDB instance dedicated to PeerTube](#creating-a-keydb-instance-dedicated-to-peertube).
#### Creating a Redis instance dedicated to PeerTube #### Creating a KeyDB instance dedicated to PeerTube
The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation. The following instructions are based on the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation.
@ -153,20 +153,20 @@ mash_playbook_service_base_directory_name_prefix: 'peertube-'
######################################################################## ########################################################################
# # # #
# redis # # keydb #
# # # #
######################################################################## ########################################################################
redis_enabled: true keydb_enabled: true
######################################################################## ########################################################################
# # # #
# /redis # # /keydb #
# # # #
######################################################################## ########################################################################
``` ```
This will create a `mash-peertube-redis` instance on this host with its data in `/mash/peertube-redis`. This will create a `mash-peertube-keydb` instance on this host with its data in `/mash/peertube-keydb`.
Then, adjust your main inventory host's variables file (`inventory/host_vars/peertube.example.com/vars.yml`) like this: Then, adjust your main inventory host's variables file (`inventory/host_vars/peertube.example.com/vars.yml`) like this:
@ -179,16 +179,16 @@ Then, adjust your main inventory host's variables file (`inventory/host_vars/pee
# Base configuration as shown above # Base configuration as shown above
# Point PeerTube to its dedicated Redis instance # Point PeerTube to its dedicated KeyDB instance
peertube_config_redis_hostname: mash-peertube-redis peertube_config_redis_hostname: mash-peertube-keydb
# Make sure the PeerTube service (mash-peertube.service) starts after its dedicated Redis service (mash-peertube-redis.service) # Make sure the PeerTube service (mash-peertube.service) starts after its dedicated KeyDB service (mash-peertube-keydb.service)
peertube_systemd_required_services_list_custom: peertube_systemd_required_services_list_custom:
- "mash-peertube-redis.service" - "mash-peertube-keydb.service"
# Make sure the PeerTube container is connected to the container network of its dedicated Redis service (mash-peertube-redis) # Make sure the PeerTube container is connected to the container network of its dedicated KeyDB service (mash-peertube-keydb)
peertube_container_additional_networks_custom: peertube_container_additional_networks_custom:
- "mash-peertube-redis" - "mash-peertube-keydb"
######################################################################## ########################################################################
# # # #
@ -200,7 +200,7 @@ peertube_container_additional_networks_custom:
## Installation ## Installation
If you've decided to install a dedicated Redis instance for PeerTube, make sure to first do [installation](../installing.md) for the supplementary inventory host (e.g. `peertube.example.com-deps`), before running installation for the main one (e.g. `peertube.example.com`). If you've decided to install a dedicated KeyDB instance for PeerTube, make sure to first do [installation](../installing.md) for the supplementary inventory host (e.g. `peertube.example.com-deps`), before running installation for the main one (e.g. `peertube.example.com`).
## Usage ## Usage

2
docs/services/redis.md
View file

@ -2,6 +2,8 @@
[Redis](https://redis.io/) is an open source, in-memory data store used by millions of developers as a database, cache, streaming engine, and message broker. [Redis](https://redis.io/) is an open source, in-memory data store used by millions of developers as a database, cache, streaming engine, and message broker.
We used to used to advocate for using Redis, but since [Redis is now "source available"](https://redis.com/blog/redis-adopts-dual-source-available-licensing/) we recommend that you use [KeyDB](keydb.md) instead. KeyDB is compatible with Redis, so switching should be straightforward. You can learn more about the switch from Redis to KeyDB in [this changelog entry](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/50813c600db1c47b1f3e76707b81fe05d6c46ef5/CHANGELOG.md#backward-compatibility-break-the-playbook-now-defaults-to-keydb-instead-of-redis) for [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy).
Some of the services installed by this playbook require a Redis data store. Some of the services installed by this playbook require a Redis data store.
**Warning**: Because Redis is not as flexible as [Postgres](postgres.md) when it comes to authentication and data separation, it's **recommended that you run separate Redis instances** (one for each service). Redis supports multiple database and a [SELECT](https://redis.io/commands/select/) command for switching between them. However, **reusing the same Redis instance is not good enough** because: **Warning**: Because Redis is not as flexible as [Postgres](postgres.md) when it comes to authentication and data separation, it's **recommended that you run separate Redis instances** (one for each service). Redis supports multiple database and a [SELECT](https://redis.io/commands/select/) command for switching between them. However, **reusing the same Redis instance is not good enough** because:

1
docs/supported-services.md
View file

@ -36,6 +36,7 @@
| [InfluxDB](https://www.influxdata.com/) | A self-hosted time-series database. | [Link](services/influxdb.md) | | [InfluxDB](https://www.influxdata.com/) | A self-hosted time-series database. | [Link](services/influxdb.md) |
| [Jitsi](https://jitsi.org/) | A fully encrypted, 100% Open Source video conferencing solution | [Link](services/jitsi.md) | | [Jitsi](https://jitsi.org/) | A fully encrypted, 100% Open Source video conferencing solution | [Link](services/jitsi.md) |
| [Keycloak](https://www.keycloak.org/) | An open source identity and access management solution. | [Link](services/keycloak.md) | | [Keycloak](https://www.keycloak.org/) | An open source identity and access management solution. | [Link](services/keycloak.md) |
| [KeyDB](https://docs.keydb.dev/) | An in-memory data store used by millions of developers as a database, cache, streaming engine, and message broker. | [Link](services/keydb.md) |
| [Lago](https://www.getlago.com/) | Open-source metering and usage-based billing | [Link](services/lago.md) | | [Lago](https://www.getlago.com/) | Open-source metering and usage-based billing | [Link](services/lago.md) |
| [languageTool](https://languagetool.org/) | An open source online grammar, style and spell checker | [Link](services/languagetool.md) | | [languageTool](https://languagetool.org/) | An open source online grammar, style and spell checker | [Link](services/languagetool.md) |
| [linkding](https://github.com/sissbruecker/linkding/) | Bookmark manager designed to be minimal and fast. | [Link](services/linkding.md) | | [linkding](https://github.com/sissbruecker/linkding/) | Bookmark manager designed to be minimal and fast. | [Link](services/linkding.md) |

32
templates/group_vars_mash_servers
View file

@ -4346,6 +4346,38 @@ redis_gid: "{{ mash_playbook_gid }}"
# /role-specific:redis # /role-specific:redis
# role-specific:keydb
########################################################################
# #
# keydb #
# #
########################################################################
keydb_enabled: false
redis_identifier: "{{ mash_playbook_service_identifier_prefix }}keydb"
keydb_uid: "{{ mash_playbook_uid }}"
keydb_gid: "{{ mash_playbook_gid }}"
keydb_base_path: "{{ mash_playbook_base_path }}/{{ mash_playbook_service_base_directory_name_prefix }}keydb"
keydb_arch: |-
{{
({
'amd64': 'x86_64',
'arm32': 'arm32',
'arm64': 'arm64',
})[mash_playbook_architecture]
}}
########################################################################
# #
# /keydb #
# #
########################################################################
# /role-specific:keydb
# role-specific:roundcube # role-specific:roundcube
######################################################################## ########################################################################

4
templates/requirements.yml
View file

@ -152,6 +152,10 @@
version: v24.0.2-0 version: v24.0.2-0
name: keycloak name: keycloak
activation_prefix: keycloak_ activation_prefix: keycloak_
- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-keydb.git
version: v6.3.4-1
name: keydb
activation_prefix: keydb_
- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-lago.git - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-lago.git
version: v0.50.0-0 version: v0.50.0-0
name: lago name: lago