# mother-of-all-self-hosting/mash-playbook architecture

> Architecture diagram of the GitHub repository mother-of-all-self-hosting/mash-playbook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mother-of-all-self-hosting/mash-playbook
- Repository: https://github.com/mother-of-all-self-hosting/mash-playbook

## Overview

MASH is an Ansible playbook for configuring and installing self-hosted services as Docker containers on user-managed servers. The main workflow is to prepare service configuration and run the playbook; Ansible applies the deployment to the server. The README documents a broad service catalog and automated installation and upgrades. The visible role tree contains base setup and migration tasks, while service-specific role implementations are not present in the supplied tree, so those are represented only at the documented level. The sampled Python utility optimizes playbook inputs from configured variables; its relationship to the deployment workflow is not established here.

Main entry points: [`bin/optimize.py`](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/bin/optimize.py) (Playbook optimizer), [`roles/mash/playbook_base/tasks/main.yml`](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/roles/mash/playbook_base/tasks/main.yml) (Base setup), [`templates/setup.yml`](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/templates/setup.yml) (MASH playbook), [`roles`](https://github.com/mother-of-all-self-hosting/mash-playbook/tree/main/roles) (Service roles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_config["Service configuration<br/>[vars.yml]"]
  node_playbook["MASH playbook<br/>[setup.yml]"]
  node_ansible["Ansible"]
  node_server["Managed server"]
  node_containers["Docker services"]
end

subgraph group_roles["Playbook roles"]
  node_service_roles["Service roles"]
  node_base_setup["Base setup<br/>[main.yml]"]
  node_base_validation["Base validation"]
  node_base_directory["Base directory<br/>[setup_base_dir.yml]"]
  node_base_user["Base user<br/>[setup_user.yml]"]
  node_migration["Migrations<br/>[main.yml]"]
  node_service_catalog["Supported services"]
end

subgraph group_optimization["Configuration optimization"]
  node_optimizer["Playbook optimizer<br/>[optimize.py]"]
  node_vars_input["Variable files"]
  node_role_requirements["Role requirements<br/>[requirements.yml]"]
  node_setup_output["Filtered setup<br/>[setup.yml]"]
  node_group_vars["Filtered group vars"]
end

node_operator(("Server operator"))

node_operator -->|"configures"| node_config
node_operator -->|"runs"| node_playbook
node_playbook -->|"runs with"| node_ansible
node_ansible -->|"configures"| node_server
node_ansible -->|"installs"| node_containers
node_service_roles -.->|"documents"| node_service_catalog
node_optimizer -->|"reads"| node_vars_input
node_optimizer -->|"filters"| node_role_requirements
node_optimizer -->|"writes"| node_setup_output
node_optimizer -->|"writes"| node_group_vars
node_base_setup -.->|"runs"| node_base_validation
node_base_setup -.->|"runs"| node_base_directory
node_base_setup -.->|"runs"| node_base_user

click node_config "https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/examples/vars.yml"
click node_playbook "https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/templates/setup.yml"
click node_service_roles "https://github.com/mother-of-all-self-hosting/mash-playbook/tree/main/roles"
click node_base_setup "https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/roles/mash/playbook_base/tasks/main.yml"
click node_base_validation "https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/roles/mash/playbook_base/tasks/validate_config.yml"
click node_base_directory "https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/roles/mash/playbook_base/tasks/setup_base_dir.yml"
click node_base_user "https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/roles/mash/playbook_base/tasks/setup_user.yml"
click node_migration "https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/roles/mash/playbook_migration/tasks/main.yml"
click node_service_catalog "https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md"
click node_optimizer "https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/bin/optimize.py"
click node_role_requirements "https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/templates/requirements.yml"
click node_setup_output "https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/templates/setup.yml"
click node_group_vars "https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/templates/group_vars_mash_servers"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_playbook,node_ansible,node_server,node_containers toneBlue
class node_service_roles,node_base_setup,node_base_validation,node_base_directory,node_base_user,node_migration,node_service_catalog toneAmber
class node_optimizer,node_vars_input,node_role_requirements,node_setup_output,node_group_vars,node_operator toneMint
```

## Components

### Deployment

- [Service configuration](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/examples/vars.yml): `examples/vars.yml`
- [MASH playbook](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/templates/setup.yml): `templates/setup.yml`
- **Ansible**
- **Managed server**
- **Docker services**

### Playbook roles

- [Service roles](https://github.com/mother-of-all-self-hosting/mash-playbook/tree/main/roles): `roles`
- [Base setup](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/roles/mash/playbook_base/tasks/main.yml): `roles/mash/playbook_base/tasks/main.yml`
- [Base validation](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/roles/mash/playbook_base/tasks/validate_config.yml): `roles/mash/playbook_base/tasks/validate_config.yml`
- [Base directory](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/roles/mash/playbook_base/tasks/setup_base_dir.yml): `roles/mash/playbook_base/tasks/setup_base_dir.yml`
- [Base user](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/roles/mash/playbook_base/tasks/setup_user.yml): `roles/mash/playbook_base/tasks/setup_user.yml`
- [Migrations](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/roles/mash/playbook_migration/tasks/main.yml): `roles/mash/playbook_migration/tasks/main.yml`
- [Supported services](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/supported-services.md): `docs/supported-services.md`

### Configuration optimization

- [Playbook optimizer](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/bin/optimize.py): `bin/optimize.py`
- **Variable files**
- [Role requirements](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/templates/requirements.yml): `templates/requirements.yml`
- [Filtered setup](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/templates/setup.yml): `templates/setup.yml`
- [Filtered group vars](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/templates/group_vars_mash_servers): `templates/group_vars_mash_servers`

### Other components

- **Server operator**

## Connections

- Server operator → Service configuration: configures (evidence: `README.md`)
- Server operator → MASH playbook: runs (evidence: `README.md`)
- MASH playbook → Ansible: runs with (evidence: `README.md`)
- Ansible → Managed server: configures (evidence: `README.md`)
- Ansible → Docker services: installs (evidence: `README.md`)
- Service roles → Supported services: documents
- Playbook optimizer → Variable files: reads (evidence: `bin/optimize.py`)
- Playbook optimizer → Role requirements: filters (evidence: `bin/optimize.py`)
- Playbook optimizer → Filtered setup: writes (evidence: `bin/optimize.py`)
- Playbook optimizer → Filtered group vars: writes (evidence: `bin/optimize.py`)
- Base setup → Base validation: runs
- Base setup → Base directory: runs
- Base setup → Base user: runs
