Merge branch 'main' of https://github.com/mother-of-all-self-hosting/mash-playbook into gotosocial

.editorconfig

@@ -23,6 +23,10 @@ indent_size = 2
 indent_style = space
 indent_size = 2
 
+[justfile]
+indent_style = space
+indent_size = 4
+
 # Markdown Files
 #
 # Two spaces at the end of a line in Markdown mean "new line",

CHANGELOG.md

@@ -1,3 +1,14 @@
+# 2023-03-26
+
+## (Backward Compatibility Break) PeerTube is no longer wired to Redis automatically
+
+As described in our [Redis](docs/services/redis.md) services docs, running a single instance of Redis to be used by multiple services is not a good practice.
+
+For this reason, we're no longer auto-wiring PeerTube to Redis. If you're running other services (which may require Redis in the future) on the same host, it's recommended that you follow the [Creating a Redis instance dedicated to PeerTube](docs/services/peertube.md#creating-a-redis-instance-dedicated-to-peertube) documentation.
+
+If you're only running PeerTube on a dedicated server (no other services that may need Redis) or you'd like to stick to what you've used until now (a single shared Redis instance), follow the [Using the shared Redis instance for PeerTube](docs/services/peertube.md#using-the-shared-redis-instance-for-peertube) documentation.
+
+
 # 2023-03-25
 
 ## (Backward Compatibility Break) Docker no longer installed by default

docs/running-multiple-instances.md

@@ -0,0 +1,210 @@
+## Running multiple instances of the same service on the same host
+
+The way this playbook is structured, each Ansible role can only be invoked once and made to install one instance of the service it's responsible for.
+
+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.
+
+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.
+
+We propose that you **don't** add `redis_enabled: true` to your main `mash.example.com` file, but do the following:
+
+## Re-do your inventory to add supplementary hosts
+
+Create multiple hosts in your inventory (`inventory/hosts`) which target the same server, like this:
+
+```ini
+[mash_servers]
+[mash_servers:children]
+mash_example_com
+
+[mash_example_com]
+mash.example.com-netbox-deps ansible_host=1.2.3.4
+mash.example.com-peertube-deps ansible_host=1.2.3.4
+mash.example.com ansible_host=1.2.3.4
+```
+
+This creates a new group (called `mash_example_com`) which groups all 3 hosts:
+
+- (**new**) `mash.example.com-netbox-deps` - a new host, for your [NetBox](services/netbox.md) dependencies
+- (**new**) `mash.example.com-peertube-deps` - a new host, for your [PeerTube](services/peertube.md) dependencies
+- (old) `mash.example.com` - your regular inventory host
+
+When running Ansible commands later on, you can use the `-l` flag to limit which host to run them against. Here are a few examples:
+
+- `just install-all` - runs the [installation](installing.md) process on all hosts (3 hosts in this case)
+- `just install-all -l mash_example_com` - runs the installation process on all hosts in the `mash_example_com` group (same 3 hosts as `just install-all` in this case)
+- `just install-all -l mash.example.com-netbox-deps` - runs the installation process on the `mash.example.com-netbox-deps` host
+
+
+## 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.
+
+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:
+
+`inventory/host_vars/mash.example.com-netbox-deps/vars.yml`:
+
+```yaml
+---
+
+########################################################################
+#                                                                      #
+# Playbook                                                             #
+#                                                                      #
+########################################################################
+
+# Put a strong secret below, generated with `pwgen -s 64 1` or in another way
+# Various other secrets will be derived from this secret automatically.
+mash_playbook_generic_secret_key: ''
+
+# Override service names and directory path prefixes
+mash_playbook_service_identifier_prefix: 'mash-netbox-'
+mash_playbook_service_base_directory_name_prefix: 'netbox-'
+
+########################################################################
+#                                                                      #
+# /Playbook                                                            #
+#                                                                      #
+########################################################################
+
+
+########################################################################
+#                                                                      #
+# redis                                                                #
+#                                                                      #
+########################################################################
+
+redis_enabled: true
+
+########################################################################
+#                                                                      #
+# /redis                                                               #
+#                                                                      #
+########################################################################
+```
+
+`inventory/host_vars/mash.example.com-peertube-deps/vars.yml`:
+
+```yaml
+---
+
+########################################################################
+#                                                                      #
+# Playbook                                                             #
+#                                                                      #
+########################################################################
+
+# Put a strong secret below, generated with `pwgen -s 64 1` or in another way
+# Various other secrets will be derived from this secret automatically.
+mash_playbook_generic_secret_key: ''
+
+# Override service names and directory path prefixes
+mash_playbook_service_identifier_prefix: 'mash-peertube-'
+mash_playbook_service_base_directory_name_prefix: 'peertube-'
+
+########################################################################
+#                                                                      #
+# /Playbook                                                            #
+#                                                                      #
+########################################################################
+
+
+########################################################################
+#                                                                      #
+# redis                                                                #
+#                                                                      #
+########################################################################
+
+redis_enabled: true
+
+########################################################################
+#                                                                      #
+# /redis                                                               #
+#                                                                      #
+########################################################################
+```
+
+The above configuration will create **2** Redis instances:
+
+- `mash-netbox-redis` with its base data path in `/mash/netbox-redis`
+- `mash-peertube-redis` with its base data path in `/mash/peertube-redis`
+
+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
+
+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.
+
+You'll need configuration (`inventory/host_vars/mash.example.com/vars.yml`) like this:
+
+```yaml
+########################################################################
+#                                                                      #
+# netbox                                                               #
+#                                                                      #
+########################################################################
+
+netbox_enabled: true
+
+# Other NetBox configuration here
+
+# Point NetBox to its dedicated Redis instance
+netbox_environment_variable_redis_host: mash-netbox-redis
+netbox_environment_variable_redis_cache_host: mash-netbox-redis
+
+# Make sure the NetBox service (mash-netbox.service) starts after its dedicated Redis service (mash-netbox-redis.service)
+netbox_systemd_required_services_list_custom:
+  - mash-netbox-redis.service
+
+# Make sure the NetBox container is connected to the container network of its dedicated Redis service (mash-netbox-redis)
+netbox_container_additional_networks_custom:
+  - mash-netbox-redis
+
+########################################################################
+#                                                                      #
+# /netbox                                                              #
+#                                                                      #
+########################################################################
+
+
+
+########################################################################
+#                                                                      #
+# peertube                                                             #
+#                                                                      #
+########################################################################
+
+# Other PeerTube configuration here
+
+# Point PeerTube to its dedicated Redis instance
+peertube_config_redis_hostname: mash-peertube-redis
+
+# Make sure the PeerTube service (mash-peertube.service) starts after its dedicated Redis service (mash-peertube-redis.service)
+peertube_systemd_required_services_list_custom:
+  - "mash-peertube-redis.service"
+
+# Make sure the PeerTube container is connected to the container network of its dedicated Redis service (mash-peertube-redis)
+peertube_container_additional_networks_custom:
+  - "mash-peertube-redis"
+
+########################################################################
+#                                                                      #
+# /peertube                                                            #
+#                                                                      #
+########################################################################
+```
+
+
+## Questions & Answers
+
+**Can't I just use the same Redis instance for multiple services?**
+
+> You may or you may not. See the [Redis](services/redis.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)?
+
+> That's a possibility which is somewhat clean. The downside is that each "full stack" comes with its own Postgres database which needs to be maintained and upgraded separately.

docs/services/keycloak.md

@@ -0,0 +1,61 @@
+# Keycloak
+
+[Keycloak](https://www.keycloak.org/) is an open source identity and access management solution.
+
+**Warning**: this service is a new addition to the playbook. It may not fully work or be configured in a suboptimal manner.
+
+
+## Dependencies
+
+This service requires the following other services:
+
+- a [Postgres](postgres.md) database
+- a [Traefik](traefik.md) reverse-proxy server
+
+
+## Configuration
+
+To enable this service, add the following configuration to your `vars.yml` file and re-run the [installation](../installing.md) process:
+
+```yaml
+########################################################################
+#                                                                      #
+# keycloak                                                             #
+#                                                                      #
+########################################################################
+
+keycloak_enabled: true
+
+keycloak_hostname: mash.example.com
+keycloak_path_prefix: /keycloak
+
+keycloak_environment_variable_keycloak_admin: your_username_here
+# Generating a strong password (e.g. `pwgen -s 64 1`) is recommended
+keycloak_environment_variable_keycloak_admin_password: ''
+
+########################################################################
+#                                                                      #
+# /keycloak                                                            #
+#                                                                      #
+########################################################################
+```
+
+### URL
+
+In the example configuration above, we configure the service to be hosted at `https://mash.example.com/keycloak`.
+
+You can remove the `keycloak_path_prefix` variable definition, to make it default to `/`, so that the service is served at `https://mash.example.com/`.
+
+### Authentication
+
+On first start, the admin user account will be created as defined with the `keycloak_environment_variable_keycloak_admin` and `keycloak_environment_variable_keycloak_admin_password` variables.
+
+On each start after that, Keycloak will attempt to create the user again and report a non-fatal error (Keycloak will continue running).
+
+Subsequent changes to the password will not affect an existing user's password.
+
+## Usage
+
+After installation, you can go to the Keycloak URL, as defined in `keycloak_hostname` and `keycloak_path_prefix` and log in as described in [Authentication](#authentication).
+
+Follow the [Keycloak documentation](https://www.keycloak.org/documentation) or other guides for learning how to use Keycloak.

docs/services/netbox.md

@@ -0,0 +1,211 @@
+# NetBox
+
+[NetBox](https://docs.netbox.dev/en/stable/) is an open-source web application that provides [IP address management (IPAM)](https://en.wikipedia.org/wiki/IP_address_management) and [data center infrastructure management (DCIM)](https://en.wikipedia.org/wiki/Data_center_management#Data_center_infrastructure_management) functionality.
+
+
+## Dependencies
+
+This service requires the following other services:
+
+- a [Postgres](postgres.md) database
+- a [Redis](redis.md) data-store, installation details [below](#redis)
+- a [Traefik](traefik.md) reverse-proxy server
+
+
+## Configuration
+
+To enable this service, add the following configuration to your `vars.yml` file and re-run the [installation](../installing.md) process:
+
+```yaml
+########################################################################
+#                                                                      #
+# netbox                                                               #
+#                                                                      #
+########################################################################
+
+netbox_enabled: true
+
+netbox_hostname: mash.example.com
+netbox_path_prefix: /netbox
+
+# Put a strong secret below, generated with `pwgen -s 64 1` or in another way
+netbox_environment_variable_secret_key: ''
+
+# The following superuser will be created upon launch.
+netbox_environment_variable_superuser_name: your_username_here
+netbox_environment_variable_superuser_email: your.email@example.com
+# Put a strong secret below, generated with `pwgen -s 64 1` or in another way.
+# Changing the password subsequently will not affect the user's password.
+netbox_environment_variable_superuser_password: ''
+
+# Redis configuration, as described below
+
+########################################################################
+#                                                                      #
+# /netbox                                                              #
+#                                                                      #
+########################################################################
+```
+
+### URL
+
+In the example configuration above, we configure the service to be hosted at `https://mash.example.com/netbox`.
+
+You can remove the `netbox_path_prefix` variable definition, to make it default to `/`, so that the service is served at `https://mash.example.com/`.
+
+
+### Authentication
+
+If `netbox_environment_variable_superuser_*` variables are specified, NetBox will try to create the user (if missing).
+
+
+### Redis
+
+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).
+
+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).
+
+#### Using the shared Redis instance for NetBox
+
+To install a single (non-dedicated) Redis instance (`mash-redis`) and hook NetBox to it, add the following **additional** configuration:
+
+```yaml
+########################################################################
+#                                                                      #
+# redis                                                                #
+#                                                                      #
+########################################################################
+
+redis_enabled: true
+
+########################################################################
+#                                                                      #
+# /redis                                                               #
+#                                                                      #
+########################################################################
+
+
+########################################################################
+#                                                                      #
+# netbox                                                               #
+#                                                                      #
+########################################################################
+
+# Base configuration as shown above
+
+# Point NetBox to the shared Redis instance
+netbox_config_redis_hostname: "{{ redis_identifier }}"
+
+# Make sure the NetBox service (mash-netbox.service) starts after the shared Redis service (mash-redis.service)
+netbox_systemd_required_services_list_custom:
+  - "{{ redis_identifier }}.service"
+
+# Make sure the NetBox container is connected to the container network of the shared Redis service (mash-redis)
+netbox_container_additional_networks_custom:
+  - "{{ redis_identifier }}"
+
+########################################################################
+#                                                                      #
+# /netbox                                                              #
+#                                                                      #
+########################################################################
+```
+
+This will create a `mash-redis` Redis 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).
+
+
+#### Creating a Redis 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.
+
+Adjust your `inventory/hosts` file as described in [Re-do your inventory to add supplementary hosts](../running-multiple-instances.md#re-do-your-inventory-to-add-supplementary-hosts), adding a new supplementary host (e.g. if `netbox.example.com` is your main one, create `netbox.example.com-deps`).
+
+Then, create a new `vars.yml` file for the
+
+`inventory/host_vars/netbox.example.com-deps/vars.yml`:
+
+```yaml
+---
+
+########################################################################
+#                                                                      #
+# Playbook                                                             #
+#                                                                      #
+########################################################################
+
+# Put a strong secret below, generated with `pwgen -s 64 1` or in another way
+# Various other secrets will be derived from this secret automatically.
+mash_playbook_generic_secret_key: ''
+
+# Override service names and directory path prefixes
+mash_playbook_service_identifier_prefix: 'mash-netbox-'
+mash_playbook_service_base_directory_name_prefix: 'netbox-'
+
+########################################################################
+#                                                                      #
+# /Playbook                                                            #
+#                                                                      #
+########################################################################
+
+
+########################################################################
+#                                                                      #
+# redis                                                                #
+#                                                                      #
+########################################################################
+
+redis_enabled: true
+
+########################################################################
+#                                                                      #
+# /redis                                                               #
+#                                                                      #
+########################################################################
+```
+
+This will create a `mash-netbox-redis` instance on this host with its data in `/mash/netbox-redis`.
+
+Then, adjust your main inventory host's variables file (`inventory/host_vars/netbox.example.com/vars.yml`) like this:
+
+```yaml
+########################################################################
+#                                                                      #
+# netbox                                                               #
+#                                                                      #
+########################################################################
+
+# Base configuration as shown above
+
+
+# Point NetBox to its dedicated Redis instance
+netbox_environment_variable_redis_host: mash-netbox-redis
+netbox_environment_variable_redis_cache_host: mash-netbox-redis
+
+# Make sure the NetBox service (mash-netbox.service) starts after its dedicated Redis service (mash-netbox-redis.service)
+netbox_systemd_required_services_list_custom:
+  - "mash-netbox-redis.service"
+
+# Make sure the NetBox container is connected to the container network of its dedicated Redis service (mash-netbox-redis)
+netbox_container_additional_networks_custom:
+  - "mash-netbox-redis"
+
+########################################################################
+#                                                                      #
+# /netbox                                                              #
+#                                                                      #
+########################################################################
+```
+
+
+## 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`).
+
+
+## Usage
+
+After installation, you can go to the NetBox URL, as defined in `netbox_hostname` and `netbox_path_prefix`.
+
+You can log in with the **username** (**not** email) and password specified in the `netbox_environment_variable_superuser*` variables.

docs/services/peertube.md

@@ -8,7 +8,7 @@
 This service requires the following other services:
 
 - a [Postgres](postgres.md) database
-- a [Redis](redis.md) data-store
+- a [Redis](redis.md) data-store, installation details [below](#redis)
 - a [Traefik](traefik.md) reverse-proxy server
 
 
@@ -47,6 +47,8 @@ peertube_config_root_user_initial_password: ''
 # Then, replace the example IP range below, and re-run the playbook.
 # peertube_trusted_proxies_values_custom: ["172.21.0.0/16"]
 
+# Redis configuration, as described below
+
 ########################################################################
 #                                                                      #
 # /peertube                                                            #
@@ -58,6 +60,148 @@ 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.
 
+### Redis
+
+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).
+
+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).
+
+#### Using the shared Redis instance for PeerTube
+
+To install a single (non-dedicated) Redis instance (`mash-redis`) and hook PeerTube to it, add the following **additional** configuration:
+
+```yaml
+########################################################################
+#                                                                      #
+# redis                                                                #
+#                                                                      #
+########################################################################
+
+redis_enabled: true
+
+########################################################################
+#                                                                      #
+# /redis                                                               #
+#                                                                      #
+########################################################################
+
+
+########################################################################
+#                                                                      #
+# peertube                                                             #
+#                                                                      #
+########################################################################
+
+# Base configuration as shown above
+
+# Point PeerTube to the shared Redis instance
+peertube_config_redis_hostname: "{{ redis_identifier }}"
+
+# Make sure the PeerTube service (mash-peertube.service) starts after the shared Redis service (mash-redis.service)
+peertube_systemd_required_services_list_custom:
+  - "{{ redis_identifier }}.service"
+
+# Make sure the PeerTube container is connected to the container network of the shared Redis service (mash-redis)
+peertube_container_additional_networks_custom:
+  - "{{ redis_identifier }}"
+
+########################################################################
+#                                                                      #
+# /peertube                                                            #
+#                                                                      #
+########################################################################
+```
+
+This will create a `mash-redis` Redis 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).
+
+
+#### Creating a Redis 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.
+
+Adjust your `inventory/hosts` file as described in [Re-do your inventory to add supplementary hosts](../running-multiple-instances.md#re-do-your-inventory-to-add-supplementary-hosts), adding a new supplementary host (e.g. if `peertube.example.com` is your main one, create `peertube.example.com-deps`).
+
+Then, create a new `vars.yml` file for the
+
+`inventory/host_vars/peertube.example.com-deps/vars.yml`:
+
+```yaml
+---
+
+########################################################################
+#                                                                      #
+# Playbook                                                             #
+#                                                                      #
+########################################################################
+
+# Put a strong secret below, generated with `pwgen -s 64 1` or in another way
+# Various other secrets will be derived from this secret automatically.
+mash_playbook_generic_secret_key: ''
+
+# Override service names and directory path prefixes
+mash_playbook_service_identifier_prefix: 'mash-peertube-'
+mash_playbook_service_base_directory_name_prefix: 'peertube-'
+
+########################################################################
+#                                                                      #
+# /Playbook                                                            #
+#                                                                      #
+########################################################################
+
+
+########################################################################
+#                                                                      #
+# redis                                                                #
+#                                                                      #
+########################################################################
+
+redis_enabled: true
+
+########################################################################
+#                                                                      #
+# /redis                                                               #
+#                                                                      #
+########################################################################
+```
+
+This will create a `mash-peertube-redis` instance on this host with its data in `/mash/peertube-redis`.
+
+Then, adjust your main inventory host's variables file (`inventory/host_vars/peertube.example.com/vars.yml`) like this:
+
+```yaml
+########################################################################
+#                                                                      #
+# peertube                                                             #
+#                                                                      #
+########################################################################
+
+# Base configuration as shown above
+
+# Point PeerTube to its dedicated Redis instance
+peertube_config_redis_hostname: mash-peertube-redis
+
+# Make sure the PeerTube service (mash-peertube.service) starts after its dedicated Redis service (mash-peertube-redis.service)
+peertube_systemd_required_services_list_custom:
+  - "mash-peertube-redis.service"
+
+# Make sure the PeerTube container is connected to the container network of its dedicated Redis service (mash-peertube-redis)
+peertube_container_additional_networks_custom:
+  - "mash-peertube-redis"
+
+########################################################################
+#                                                                      #
+# /peertube                                                            #
+#                                                                      #
+########################################################################
+```
+
+
+## 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`).
+
 
 ## Usage
 
@@ -68,6 +212,7 @@ You should then be able to log in with:
 - username: `root`
 - password: the password you've set in `peertube_config_root_user_initial_password` in `vars.yml`
 
+
 ## Adjusting the trusted reverse-proxy networks
 
 If you go to **Administration** -> **System** -> **Debug** (`/admin/system/debug`), you'll notice that PeerTube reports some local IP instead of your own IP address.

docs/services/redis.md

@@ -4,12 +4,19 @@
 
 Some of the services installed by this playbook require a Redis data store.
 
-Enabling the Redis database service will automatically wire all other services to use it.
+**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:
+
+- if all services use the same Redis instance and database (id = 0), services may conflict with one another
+- the number of databases is limited to [16 by default](https://github.com/redis/redis/blob/aa2403ca98f6a39b6acd8373f8de1a7ba75162d5/redis.conf#L376-L379), which may or may not be enough. With configuration changes, this is solveable.
+- some services do not support switching the Redis database and always insist on using the default one (id = 0)
+- Redis [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 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 Redis service**:
 
 ```yaml
 ########################################################################
@@ -26,3 +33,5 @@ redis_enabled: true
 #                                                                      #
 ########################################################################
 ```
+
+To **host multiple instances of the Redis service**, follow the [Running multiple instances of the same service on the same host](../running-multiple-instances.md) documentation or the **Redis** section (if available) of the service you're installing.

docs/services/soft-serve.md

@@ -0,0 +1,39 @@
+# Soft Serve
+
+[Soft Serve](https://github.com/charmbracelet/soft-serve) is a tasty, self-hostable [Git](https://git-scm.com/) server for the command line.
+
+## Configuration
+
+To enable this service, add the following configuration to your `vars.yml` file and re-run the [installation](../installing.md) process:
+
+```yaml
+########################################################################
+#                                                                      #
+# soft-serve                                                           #
+#                                                                      #
+########################################################################
+
+soft_serve_enabled: true
+
+# The hostname of this system.
+# It will be used for generating git clone URLs (e.g. ssh://mash.example.com/repository.git)
+soft_serve_hostname: mash.example.com
+
+# Expose Soft Serve's port. For git servers the usual git-over-ssh port is 22
+soft_serve_container_bind_port: 2222
+
+# This key will be able to authenticate with ANY user until you configure Soft Serve
+soft_serve_initial_admin_key: YOUR PUBLIC SSH KEY HERE
+
+########################################################################
+#                                                                      #
+# /soft-serve                                                          #
+#                                                                      #
+########################################################################
+```
+
+## Usage
+
+After you've installed Soft Serve, you can `ssh your-user@mash.example.com -p 2222` with the SSH key defined in `soft_serve_initial_admin_key` to see its [TUI](https://en.wikipedia.org/wiki/Text-based_user_interface) and follow the instructions to configure Soft Serve further.
+
+Note that you have to [finish the configuration yourself](https://github.com/charmbracelet/soft-serve#configuration), otherwise any user with `soft_serve_initial_admin_key` will work as an admin.

docs/supported-services.md

@@ -11,11 +11,13 @@
 | [Docker Registry Purger](https://github.com/devture/docker-registry-purger) | A small tool used for purging a private Docker Registry's old tags | [Link](services/docker-registry-purger.md) |
 | [Focalboard](https://www.focalboard.com/) | An open source, self-hosted alternative to [Trello](https://trello.com/), [Notion](https://www.notion.so/), and [Asana](https://asana.com/). | [Link](services/focalboard.md) |
 | [Firezone](https://www.firezone.dev/) | A self-hosted VPN server (based on [WireGuard](https://en.wikipedia.org/wiki/WireGuard)) with a Web UI | [Link](services/firezone.md) |
-| [Gitea](https://gitea.io/) | A painless self-hosted Git service. | [Link](services/gitea.md) |
+| [Gitea](https://gitea.io/) | A painless self-hosted [Git](https://git-scm.com/) service. | [Link](services/gitea.md) |
 | [GotoSocial](https://gotosocial.org/) | [GoToSocial](https://gotosocial.org/) is a self-hosted [ActivityPub](https://activitypub.rocks/) social network server | [Link](services/gotosocial.md) |
 | [Grafana](https://grafana.com/) | An open and composable observability and data visualization platform, often used with [Prometheus](services/prometheus.md) | [Link](services/grafana.md) |
 | [Hubsite](https://github.com/moan0s/hubsite) | A simple, static site that shows an overview of the available services | [Link](services/hubsite.md) |
+| [Keycloak](https://www.keycloak.org/) | An open source identity and access management solution. | [Link](services/keycloak.md) |
 | [Miniflux](https://miniflux.app/) | Minimalist and opinionated feed reader. | [Link](services/miniflux.md) |
+| [NetBox](https://docs.netbox.dev/en/stable/) | Web application that provides [IP address management (IPAM)](https://en.wikipedia.org/wiki/IP_address_management) and [data center infrastructure management (DCIM)](https://en.wikipedia.org/wiki/Data_center_management#Data_center_infrastructure_management) functionality | [Link](services/netbox.md) |
 | [Nextcloud](https://nextcloud.com/) | The most popular self-hosted collaboration solution for tens of millions of users at thousands of organizations across the globe. | [Link](services/nextcloud.md) |
 | [PeerTube](https://joinpeertube.org/) | A tool for sharing online videos | [Link](services/peertube.md) |
 | [Postgres](https://www.postgresql.org) | A powerful, open source object-relational database system | [Link](services/postgres.md) |
@@ -26,6 +28,7 @@
 | [Radicale](https://radicale.org/) | A Free and Open-Source CalDAV and CardDAV Server (solution for hosting contacts and calendars) | [Link](services/radicale.md) |
 | [Redmine](https://redmine.org/) | A flexible project management web application. | [Link](services/redmine.md) |
 | [Redis](https://redis.io/) | An in-memory data store used by millions of developers as a database, cache, streaming engine, and message broker. | [Link](services/redis.md) |
+| [Soft Serve](https://github.com/charmbracelet/soft-serve) | A tasty, self-hostable [Git](https://git-scm.com/) server for the command line | [Link](services/soft-serve.md) |
 | [Syncthing](https://syncthing.net/) | A continuous file synchronization program which synchronizes files between two or more computers in real time | [Link](services/syncthing.md) |
 | [Traefik](https://doc.traefik.io/traefik/) | A container-aware reverse-proxy server | [Link](services/traefik.md) |
 | [Vaultwarden](https://github.com/dani-garcia/vaultwarden) | A lightweight unofficial and compatible implementation of the [Bitwarden](https://bitwarden.com/) password manager | [Link](services/vaultwarden.md) |

group_vars/mash_servers

@@ -93,14 +93,24 @@ devture_systemd_service_manager_services_list_auto: |
     +
     ([{'name': (gitea_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'gitea', 'gitea-server']}] if gitea_enabled else [])
     +
+    ([{'name': (gotosocial_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'gotosocial']}] if gotosocial_enabled else [])
+    +
     ([{'name': (grafana_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'grafana']}] if grafana_enabled else [])
     +
+    ([{'name': (keycloak_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'keycloak']}] if keycloak_enabled else [])
+    +
+    ([{'name': (miniflux_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'miniflux']}] if miniflux_enabled else [])
+    +
+    ([{'name': (netbox_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'netbox', 'netbox-server']}] if netbox_enabled else [])
+    +
+    ([{'name': (netbox_identifier + '-worker.service'), 'priority': 2500, 'groups': ['mash', 'netbox', 'netbox-worker']}] if netbox_enabled else [])
+    +
+    ([{'name': (netbox_identifier + '-housekeeping.service'), 'priority': 2500, 'groups': ['mash', 'netbox', 'netbox-housekeeping']}] if netbox_enabled else [])
+    +
     ([{'name': (nextcloud_identifier + '-server.service'), 'priority': 2000, 'groups': ['mash', 'nextcloud', 'nextcloud-server']}] if nextcloud_enabled else [])
     +
     ([{'name': (nextcloud_identifier + '-cron.timer'), 'priority': 2500, 'groups': ['mash', 'nextcloud', 'nextcloud-cron']}] if nextcloud_enabled else [])
     +
-    ([{'name': (miniflux_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'miniflux']}] if miniflux_enabled else [])
-    +
     ([{'name': (peertube_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'peertube']}] if peertube_enabled else [])
     +
     ([{'name': (prometheus_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'metrics', 'prometheus']}] if prometheus_enabled else [])
@@ -115,6 +125,8 @@ devture_systemd_service_manager_services_list_auto: |
     +
     ([{'name': (redis_identifier + '.service'), 'priority': 750, 'groups': ['mash', 'redis']}] if redis_enabled else [])
     +
+    ([{'name': (soft_serve_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'soft-serve']}] if soft_serve_enabled else [])
+    +
     ([{'name': (syncthing_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'syncthing']}] if syncthing_enabled else [])
     +
     ([{'name': (vaultwarden_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'vaultwarden', 'vaultwarden-server']}] if vaultwarden_enabled else [])
@@ -122,8 +134,6 @@ devture_systemd_service_manager_services_list_auto: |
     ([{'name': (uptime_kuma_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'uptime-kuma']}] if uptime_kuma_enabled else [])
     +
     ([{'name': (hubsite_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'hubsite']}] if hubsite_enabled else [])
-    +
-    ([{'name': (gotosocial_identifier + '.service'), 'priority': 2000, 'groups': ['mash', 'gotosocial']}] if gotosocial_enabled else [])
   }}
 
 ########################################################################
@@ -184,6 +194,12 @@ devture_postgres_managed_databases_auto: |
       'password': gotosocial_database_password,
     }] if gotosocial_enabled else [])
     +
+    ([{
+      'name': keycloak_database_name,
+      'username': keycloak_database_username,
+      'password': keycloak_database_password,
+    }] if keycloak_enabled and keycloak_database_type == 'postgres' and keycloak_database_hostname == devture_postgres_identifier else [])
+    +
     ([{
       'name': miniflux_database_name,
       'username': miniflux_database_username,
@@ -196,6 +212,12 @@ devture_postgres_managed_databases_auto: |
       'password': redmine_database_password,
     }] if redmine_enabled else [])
     +
+    ([{
+      'name': netbox_database_name,
+      'username': netbox_database_username,
+      'password': netbox_database_password,
+    }] if netbox_enabled else [])
+    +
     ([{
       'name': nextcloud_database_name,
       'username': nextcloud_database_username,
@@ -678,6 +700,50 @@ grafana_container_labels_traefik_tls_certResolver: "{{ devture_traefik_certResol
 
 
 
+########################################################################
+#                                                                      #
+# keycloak                                                             #
+#                                                                      #
+########################################################################
+
+keycloak_enabled: false
+
+keycloak_identifier: "{{ mash_playbook_service_identifier_prefix }}keycloak"
+
+keycloak_uid: "{{ mash_playbook_uid }}"
+keycloak_gid: "{{ mash_playbook_gid }}"
+
+keycloak_base_path: "{{ mash_playbook_base_path }}/{{ mash_playbook_service_base_directory_name_prefix }}keycloak"
+
+keycloak_systemd_required_systemd_services_list_auto: |
+  {{
+    ([devture_postgres_identifier ~ '.service'] if devture_postgres_enabled and keycloak_database_hostname == devture_postgres_identifier else [])
+  }}
+
+keycloak_container_additional_networks_auto: |
+  {{
+    ([mash_playbook_reverse_proxyable_services_additional_network] if mash_playbook_reverse_proxyable_services_additional_network else [])
+    +
+    ([devture_postgres_container_network] if devture_postgres_enabled and keycloak_database_hostname == devture_postgres_identifier and keycloak_container_network != devture_postgres_container_network else [])
+  }}
+
+keycloak_container_labels_traefik_enabled: "{{ mash_playbook_traefik_labels_enabled }}"
+keycloak_container_labels_traefik_docker_network: "{{ mash_playbook_reverse_proxyable_services_additional_network }}"
+keycloak_container_labels_traefik_entrypoints: "{{ devture_traefik_entrypoint_primary }}"
+keycloak_container_labels_traefik_tls_certResolver: "{{ devture_traefik_certResolver_primary }}"
+
+keycloak_database_hostname: "{{ devture_postgres_identifier if devture_postgres_enabled else '' }}"
+keycloak_database_port: "{{ '5432' if devture_postgres_enabled else '' }}"
+keycloak_database_password: "{{ '%s' | format(mash_playbook_generic_secret_key) | password_hash('sha512', 'db.keycloak', rounds=655555) | to_uuid }}"
+
+########################################################################
+#                                                                      #
+# /keycloak                                                            #
+#                                                                      #
+########################################################################
+
+
+
 ########################################################################
 #                                                                      #
 # miniflux                                                             #
@@ -770,6 +836,52 @@ nextcloud_database_password: "{{ '%s' | format(mash_playbook_generic_secret_key)
 
 
 
+########################################################################
+#                                                                      #
+# netbox                                                              #
+#                                                                      #
+########################################################################
+
+netbox_enabled: false
+
+netbox_identifier: "{{ mash_playbook_service_identifier_prefix }}netbox"
+
+netbox_uid: "{{ mash_playbook_uid }}"
+netbox_gid: "{{ mash_playbook_gid }}"
+
+netbox_base_path: "{{ mash_playbook_base_path }}/{{ mash_playbook_service_base_directory_name_prefix }}netbox"
+
+netbox_systemd_required_services_list_auto: |
+  {{
+    ([devture_postgres_identifier ~ '.service'] if devture_postgres_enabled and nextcloud_database_hostname == devture_postgres_identifier else [])
+  }}
+
+netbox_container_additional_networks_auto: |
+  {{
+    (
+      ([mash_playbook_reverse_proxyable_services_additional_network] if mash_playbook_reverse_proxyable_services_additional_network else [])
+      +
+      ([devture_postgres_container_network] if devture_postgres_enabled and netbox_database_hostname == devture_postgres_identifier and netbox_container_network != devture_postgres_container_network else [])
+    ) | unique
+  }}
+
+netbox_container_labels_traefik_enabled: "{{ mash_playbook_traefik_labels_enabled }}"
+netbox_container_labels_traefik_docker_network: "{{ mash_playbook_reverse_proxyable_services_additional_network }}"
+netbox_container_labels_traefik_entrypoints: "{{ devture_traefik_entrypoint_primary }}"
+netbox_container_labels_traefik_tls_certResolver: "{{ devture_traefik_certResolver_primary }}"
+
+netbox_database_hostname: "{{ devture_postgres_identifier if devture_postgres_enabled else '' }}"
+netbox_database_port: "{{ '5432' if devture_postgres_enabled else '' }}"
+netbox_database_password: "{{ '%s' | format(mash_playbook_generic_secret_key) | password_hash('sha512', 'db.netbox', rounds=655555) | to_uuid }}"
+
+########################################################################
+#                                                                      #
+# /netbox                                                             #
+#                                                                      #
+########################################################################
+
+
+
 ########################################################################
 #                                                                      #
 # peertube                                                             #
@@ -785,14 +897,12 @@ peertube_base_path: "{{ mash_playbook_base_path }}/{{ mash_playbook_service_base
 peertube_uid: "{{ mash_playbook_uid }}"
 peertube_gid: "{{ mash_playbook_gid }}"
 
-peertube_container_additional_networks: |
+peertube_container_additional_networks_auto: |
   {{
     (
       ([mash_playbook_reverse_proxyable_services_additional_network] if mash_playbook_reverse_proxyable_services_additional_network else [])
       +
       ([devture_postgres_container_network] if devture_postgres_enabled and peertube_config_database_hostname == devture_postgres_identifier and peertube_container_network != devture_postgres_container_network else [])
-      +
-      ([redis_container_network] if peertube_config_redis_hostname == redis_identifier else [])
     ) | unique
   }}
 
@@ -806,15 +916,9 @@ peertube_config_database_port: "{{ '5432' if devture_postgres_enabled else '' }}
 peertube_config_database_username: peertube
 peertube_config_database_password: "{{ '%s' | format(mash_playbook_generic_secret_key) | password_hash('sha512', 'db.peertube', rounds=655555) | to_uuid }}"
 
-peertube_config_redis_hostname: "{{ redis_identifier if redis_enabled else '' }}"
+peertube_systemd_required_services_list_auto: |
-
-peertube_systemd_required_services_list: |
   {{
-    (['docker.service'])
-    +
     ([devture_postgres_identifier ~ '.service'] if devture_postgres_enabled and peertube_config_database_hostname == devture_postgres_identifier else [])
-    +
-    ([redis_identifier ~ '.service'] if redis_enabled and peertube_config_redis_hostname == redis_identifier else [])
   }}
 
 ########################################################################
@@ -1039,6 +1143,30 @@ redis_gid: "{{ mash_playbook_gid }}"
 
 
 
+
+########################################################################
+#                                                                      #
+# soft-serve                                                           #
+#                                                                      #
+########################################################################
+
+soft_serve_enabled: false
+
+soft_serve_identifier: "{{ mash_playbook_service_identifier_prefix }}soft-serve"
+
+soft_serve_uid: "{{ mash_playbook_uid }}"
+soft_serve_gid: "{{ mash_playbook_gid }}"
+
+soft_serve_base_path: "{{ mash_playbook_base_path }}/{{ mash_playbook_service_base_directory_name_prefix }}soft-serve"
+
+########################################################################
+#                                                                      #
+# /soft-serve                                                          #
+#                                                                      #
+########################################################################
+
+
+
 ########################################################################
 #                                                                      #
 # syncthing                                                            #

justfile

@@ -5,7 +5,6 @@ default:
 # Pulls external Ansible roles
 roles:
     #!/usr/bin/env sh
-    set -euo pipefail
     if [ -x "$(command -v agru)" ]; then
     	agru
     else
@@ -26,7 +25,10 @@ install-all *extra_args: (run-tags "install-all,start" extra_args)
 
 # Runs installation tasks for a single service
 install-service service *extra_args:
-    just --justfile {{ justfile() }} run --tags=install-{{ service }},start-group --extra-vars=group={{ service }} {{ extra_args }}
+    just --justfile {{ justfile() }} run \
+    --tags=install-{{ service }},start-group \
+    --extra-vars=group={{ service }} \
+    --extra-vars=devture_systemd_service_manager_service_restart_mode=one-by-one {{ extra_args }}
 
 # Runs the playbook with --tags=setup-all,start and optional arguments
 setup-all *extra_args: (run-tags "setup-all,start" extra_args)

requirements.yml

@@ -26,7 +26,7 @@
 - src: git+https://github.com/devture/com.devture.ansible.role.traefik.git
   version: v2.9.9-0
 - src: git+https://github.com/devture/com.devture.ansible.role.systemd_service_manager.git
-  version: 6ccb88ac5fc27e1e70afcd48278ade4b564a9096
+  version: v1.0.0-0
 - src: git+https://github.com/devture/com.devture.ansible.role.playbook_runtime_messages.git
   version: 9b4b088c62b528b73a9a7c93d3109b091dd42ec6
 - src: git+https://github.com/devture/com.devture.ansible.role.woodpecker_ci_server.git
@@ -36,11 +36,11 @@
 - src: git+https://gitlab.com/etke.cc/roles/miniflux.git
   version: v2.0.43-2
 - src: git+https://gitlab.com/etke.cc/roles/grafana.git
-  version: v9.4.7-0
+  version: v9.4.7-1
 - src: git+https://gitlab.com/etke.cc/roles/radicale.git
   version: v3.1.8.1-2
 - src: git+https://gitlab.com/etke.cc/roles/uptime_kuma.git
-  version: v1.21.0-0
+  version: v1.21.1-0
 - src: git+https://gitlab.com/etke.cc/roles/redis.git
   version: v7.0.10-0
 - src: git+https://gitlab.com/etke.cc/roles/prometheus_node_exporter.git
@@ -49,6 +49,8 @@
   version: v0.23.0-3
 - src: git+https://gitlab.com/etke.cc/roles/redmine.git
   version: v5.0.5-1
+- src: git+https://gitlab.com/etke.cc/roles/soft_serve.git
+  version: v0.4.7-0
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-adguard-home.git
   version: v0.107.26-0
   name: adguard_home
@@ -73,20 +75,26 @@
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-gitea.git
   version: v1.19.0-0
   name: gitea
+- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-keycloak.git
+  version: v21.0.1-1
+  name: keycloak
+- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-netbox.git
+  version: v3.4.6-2.5.1-0
+  name: netbox
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-nextcloud.git
   version: v26.0.0-0
   name: nextcloud
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-peertube.git
-  version: v5.1.0-0
+  version: v5.1.0-2
   name: peertube
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-prometheus.git
   version: v2.43.0-0
   name: prometheus
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-syncthing.git
-  version: v1.23.2-0
+  version: v1.23.2-1
   name: syncthing
 - src: git+https://github.com/mother-of-all-self-hosting/ansible-role-vaultwarden.git
-  version: v1.27.0-2
+  version: v1.28.0-0
   name: vaultwarden
 - src: git+https://github.com/moan0s/hubsite.git
   version: 6b20c472d36ce5765dc44675d42cce74cbcbd0fe

setup.yml

@@ -72,10 +72,14 @@
 
     - role: galaxy/grafana
 
+    - role: galaxy/keycloak
+
     - role: galaxy/miniflux
 
     - role: galaxy/hubsite
 
+    - role: galaxy/netbox
+
     - role: galaxy/nextcloud
 
     - role: galaxy/peertube
@@ -90,6 +94,8 @@
 
     - role: galaxy/redis
 
+    - role: galaxy/soft_serve
+
     - role: galaxy/syncthing
 
     - role: galaxy/vaultwarden