mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2026-06-30 03:50:30 +03:00
Add Synology DSM support (#5315)
Adds optional support for running the playbook on Synology DSM 7+, detected automatically via /etc/synoinfo.conf so that non-Synology hosts are unaffected. Includes DSM-native user/group management (synouser/synogroup), a requests version constraint for Docker SDK compatibility, and a boot-fix service that re-shares the volume mount and starts matrix services skipped by DSM's boot ordering. The shared-mount volume path is configurable via matrix_base_synology_volume_path, and the make-shared step only runs when the volume is not already shared. Co-authored-by: CKSit <sitchiuki@gmail.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
cksit
GitHub
@@ -0,0 +1,179 @@
|
||||
<!--
|
||||
SPDX-FileCopyrightText: 2026 Chiu Ki Sit
|
||||
|
||||
SPDX-License-Identifier: AGPL-3.0-or-later
|
||||
-->
|
||||
|
||||
# Configuring Synology DSM
|
||||
|
||||
This document is a guide for preparing Synology DSM for the installation of the [Matrix Docker Ansible Deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy) project.
|
||||
|
||||
> **Note:** Synology DSM is a community-supported platform. It is not officially tested or maintained by the project maintainers. Use at your own discretion.
|
||||
|
||||
**Intended audience:** Users already familiar with DSM, SSH, and this Ansible project.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- DSM version 7 or higher
|
||||
- `Volume1` is used as the default Docker storage location
|
||||
- You are using DSM's built-in reverse proxy for handling HTTPS
|
||||
|
||||
## How Synology Support Works
|
||||
|
||||
The playbook automatically detects Synology DSM by checking for `/etc/synoinfo.conf`. When detected, it:
|
||||
|
||||
- Uses `synouser` and `synogroup` (DSM-native tools) instead of standard Linux user management
|
||||
- Constrains the Python `requests` package to a version compatible with the Docker SDK
|
||||
- Ensures `/volume1` has shared mount propagation so container bind mounts work correctly
|
||||
- Deploys a `matrix-synology-boot-fix` service that runs on every boot after Docker is ready
|
||||
|
||||
You can override auto-detection by setting `matrix_base_host_is_synology: true` or `false` in your `vars.yml`.
|
||||
|
||||
### Matrix Service Account
|
||||
|
||||
The playbook creates a `matrix` system account using Synology's `synouser` tool. The account is secured as follows:
|
||||
|
||||
- **Expired** (`expired=1`) — the account cannot be used to log in to DSM or any application
|
||||
|
||||
You must set a password for this account via `matrix_synology_user_password` in your `vars.yml` (see [vars.yml Configuration](#varsyml-configuration)). The password cannot be used to log in because the account is expired, but a non-empty password is required as an additional security layer.
|
||||
|
||||
> If you pre-create the `matrix` user manually before running the playbook, the playbook will not modify the existing account's settings — you are responsible for securing it.
|
||||
|
||||
### Boot-fix Service
|
||||
|
||||
Synology DSM has two boot-time quirks that the boot-fix service addresses automatically:
|
||||
|
||||
1. **`/volume1` shared mount propagation**
|
||||
|
||||
Docker requires `/volume1` to be mounted as shared (`mount --make-shared /volume1`) for container bind mounts with `bind-propagation=slave` to work correctly (used by matrix-synapse for its media store). On Synology, this cannot be inserted into the systemd chain before Container Manager starts — doing so causes Container Manager to detect a broken dependency and prompt for repair on every boot. The playbook applies this during setup, and the boot-fix service re-applies it on every subsequent reboot, safely outside Container Manager's dependency chain.
|
||||
|
||||
2. **Skipped services at boot**
|
||||
|
||||
Synology's systemd drops services with multi-level dependency chains from the boot activation queue (e.g. `matrix-traefik → matrix-container-socket-proxy → docker`). These services show as `inactive` or `failed` after reboot even though they are enabled. The boot-fix service scans for any enabled `matrix-*.service` in either state and starts them automatically.
|
||||
|
||||
> **If you previously configured a Task Scheduler entry** (`Control Panel > Task Scheduler`) to run `mount --make-shared /volume1` at boot-up, you can remove it — the boot-fix service now handles this.
|
||||
|
||||
## Synology GUI Preparation
|
||||
|
||||
1. **Enable SSH**
|
||||
- `Control Panel` > `Terminal & SNMP` > `Enable SSH service`
|
||||
|
||||
2. **Enable SFTP**
|
||||
- `Control Panel` > `File Service` > `FTP` > `Enable SFTP service` with default port
|
||||
|
||||
3. **Enable User Home Directory**
|
||||
- `Control Panel` > `User & Group` > `Advanced` > `Enable user home service`
|
||||
|
||||
4. **Install Container Manager**
|
||||
- Install from `Package Center`
|
||||
|
||||
5. **Configure Reverse Proxy**
|
||||
- `Control Panel` > `Login Portal` > `Advanced` > `Reverse Proxy`
|
||||
- Create entries for each service you enable (e.g. Matrix, Element, admin page)
|
||||
- Example entry:
|
||||
- Source: `HTTPS` / `matrix.example.com` / port `443`
|
||||
- Destination: `HTTP` / `localhost` / port `81`
|
||||
|
||||
## SSH Preparation
|
||||
|
||||
### (Optional but Recommended) Enable SSH Key Authentication
|
||||
|
||||
Configure key-based SSH login to avoid password prompts during Ansible runs.
|
||||
|
||||
### Set Up the Ansible Environment
|
||||
|
||||
Create a project folder and Python virtual environment on the DSM host:
|
||||
|
||||
```shell
|
||||
mkdir ~/path/to/your/project/folder
|
||||
cd ~/path/to/your/project/folder
|
||||
|
||||
python3 -m venv ./myenv
|
||||
# (optional) activate python virtual environment
|
||||
# source ./myenv/bin/activate
|
||||
```
|
||||
|
||||
## Inventory Configuration
|
||||
|
||||
In your `inventory/hosts` file, set the Python interpreter to your virtual environment:
|
||||
|
||||
```ini
|
||||
# SSH key authentication with empty passphrase example
|
||||
matrix.example.com ansible_host=<your-dsm-ip> ansible_ssh_user=<dsm-ssh-user> become=true become_user=root ansible_python_interpreter=/volume1/homes/path/to/your/project/folder/myenv/bin/python ansible_sudo_pass='your-password'
|
||||
```
|
||||
|
||||
## vars.yml Configuration
|
||||
|
||||
Add the following Synology-specific variables to your `vars.yml`:
|
||||
|
||||
```yaml
|
||||
# Synology-specific settings
|
||||
|
||||
# Controls Synology DSM-specific handling. `null` means autodetect (via /etc/synoinfo.conf).
|
||||
# Set to `true`/`false` to force.
|
||||
# matrix_base_host_is_synology: true
|
||||
|
||||
# Password for the Matrix service account created by the playbook.
|
||||
# The account is created as expired so this password cannot be used to log in.
|
||||
matrix_synology_user_password: "your-strong-password"
|
||||
|
||||
# User and group that will be created automatically by the playbook
|
||||
matrix_user_name: "matrix"
|
||||
matrix_group_name: "matrix"
|
||||
|
||||
# Data path on your Synology volume
|
||||
matrix_base_data_path: "/volume1/docker/matrix"
|
||||
|
||||
# Use Synology Container Manager's Docker daemon instead of installing Docker
|
||||
matrix_playbook_docker_installation_enabled: false
|
||||
devture_systemd_docker_base_host_command_docker: "/var/packages/ContainerManager/target/usr/bin/docker"
|
||||
devture_systemd_docker_base_docker_service_name: "pkg-ContainerManager-dockerd.service"
|
||||
|
||||
# Use Synology's NTP service
|
||||
devture_timesync_ntpd_service: "chronyd"
|
||||
|
||||
# Reverse proxy settings — use HTTPS at the DSM reverse proxy level
|
||||
matrix_playbook_ssl_enabled: true
|
||||
traefik_config_entrypoint_web_secure_enabled: false
|
||||
|
||||
# Bind to localhost only — DSM reverse proxy handles public traffic
|
||||
traefik_container_web_host_bind_port: '127.0.0.1:81'
|
||||
matrix_playbook_public_matrix_federation_api_traefik_entrypoint_host_bind_port: '127.0.0.1:8449'
|
||||
|
||||
# Trust X-Forwarded-* headers from the local reverse proxy
|
||||
traefik_config_entrypoint_web_forwardedHeaders_insecure: true
|
||||
|
||||
matrix_playbook_public_matrix_federation_api_traefik_entrypoint_config_custom:
|
||||
forwardedHeaders:
|
||||
insecure: true
|
||||
```
|
||||
|
||||
## Running the Playbook
|
||||
|
||||
```shell
|
||||
# Full setup
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all
|
||||
|
||||
# start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start
|
||||
|
||||
# Stop all services
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=stop
|
||||
|
||||
# Apply config changes (always include start to restart running containers)
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=stop,setup-all,start
|
||||
```
|
||||
|
||||
> **Important:** Always include `stop` before `setup-all,start` when changing configuration. Running `setup-all` alone does not restart already-running containers.
|
||||
|
||||
## Creating Matrix Users
|
||||
|
||||
After the services are running, create your first Matrix user:
|
||||
|
||||
```shell
|
||||
# option 1:
|
||||
sudo docker exec -it matrix-synapse register_new_matrix_user http://localhost:8008 -c /data/homeserver.yaml -u your_username -p your_password
|
||||
|
||||
# option 2:
|
||||
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=your_username password=your_password admin=yes|no' --tags=register-user
|
||||
```
|
||||
Reference in New Issue
Block a user