From b23ddd0b9890df22b3e4b77d44049a94443673e2 Mon Sep 17 00:00:00 2001 From: Mauricio Siu Date: Tue, 14 Jul 2026 12:12:24 -0600 Subject: [PATCH] feat: add Synapse (Matrix homeserver) template Co-Authored-By: Claude Fable 5 --- blueprints/synapse/docker-compose.yml | 51 +++++++++++++++ blueprints/synapse/instructions.md | 39 +++++++++++ blueprints/synapse/meta.json | 16 +++++ blueprints/synapse/synapse.svg | 5 ++ blueprints/synapse/template.toml | 93 +++++++++++++++++++++++++++ 5 files changed, 204 insertions(+) create mode 100644 blueprints/synapse/docker-compose.yml create mode 100644 blueprints/synapse/instructions.md create mode 100644 blueprints/synapse/meta.json create mode 100644 blueprints/synapse/synapse.svg create mode 100644 blueprints/synapse/template.toml diff --git a/blueprints/synapse/docker-compose.yml b/blueprints/synapse/docker-compose.yml new file mode 100644 index 00000000..ee9c0bd8 --- /dev/null +++ b/blueprints/synapse/docker-compose.yml @@ -0,0 +1,51 @@ +services: + synapse: + image: matrixdotorg/synapse:v1.156.0 + restart: unless-stopped + # The stock entrypoint (/start.py) does not generate the signing key when a + # config file is provided, so generate any missing keys on first boot and + # make sure the data volume is owned by the synapse user (991) before + # handing over to the regular entrypoint. + entrypoint: + - /bin/sh + - -c + - | + python -m synapse.app.homeserver --config-path /config/homeserver.yaml --keys-directory /data --generate-keys + chown -R 991:991 /data + exec /start.py + environment: + SYNAPSE_CONFIG_PATH: /config/homeserver.yaml + volumes: + - synapse-data:/data + - ../files/homeserver.yaml:/config/homeserver.yaml:ro + - ../files/log.config:/config/log.config:ro + depends_on: + postgres: + condition: service_healthy + healthcheck: + test: ["CMD-SHELL", "curl -fSs http://localhost:8008/health || exit 1"] + interval: 15s + timeout: 5s + retries: 10 + start_period: 90s + + postgres: + image: postgres:16-alpine + restart: unless-stopped + environment: + POSTGRES_USER: synapse + POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} + POSTGRES_DB: synapse + # Synapse requires a database with C collation + POSTGRES_INITDB_ARGS: "--encoding=UTF-8 --lc-collate=C --lc-ctype=C" + volumes: + - postgres-data:/var/lib/postgresql/data + healthcheck: + test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"] + interval: 10s + timeout: 5s + retries: 5 + +volumes: + synapse-data: + postgres-data: diff --git a/blueprints/synapse/instructions.md b/blueprints/synapse/instructions.md new file mode 100644 index 00000000..91b308a2 --- /dev/null +++ b/blueprints/synapse/instructions.md @@ -0,0 +1,39 @@ +## Instructions + +Synapse is deployed with public registration disabled, so you need to create the +first user (your admin account) from the command line. + +### Create the first user + +Open a terminal on the server running Dokploy (or use the container terminal in +the Dokploy UI) and run the following inside the `synapse` service container: + +```bash +docker exec -it $(docker ps -qf "name=synapse" | head -n 1) \ + register_new_matrix_user http://localhost:8008 -c /config/homeserver.yaml +``` + +The tool prompts for a username and password, and asks whether the user should +be an admin. It authenticates against the server using the +`registration_shared_secret` that was generated for this deployment (stored in +the mounted `homeserver.yaml`), so no registration needs to be enabled. + +### Log in + +Point any Matrix client (for example Element Web at https://app.element.io) at +your homeserver URL `https://your-domain` and log in with the user you just +created. You can verify the server is up with: + +```bash +curl https://your-domain/_matrix/client/versions +``` + +### Notes + +- Data (signing keys, media uploads) is stored in the `synapse-data` volume and + the database in the `postgres-data` volume. +- Federation with other Matrix servers works through `.well-known` delegation + over HTTPS (port 443). The dedicated federation port 8448 is not exposed. +- To allow open registration instead, edit `enable_registration` in the mounted + `homeserver.yaml` (see Synapse docs for the required spam-check options such + as CAPTCHA or email verification). diff --git a/blueprints/synapse/meta.json b/blueprints/synapse/meta.json new file mode 100644 index 00000000..bd4dbd1f --- /dev/null +++ b/blueprints/synapse/meta.json @@ -0,0 +1,16 @@ +{ + "id": "synapse", + "name": "Synapse", + "version": "v1.156.0", + "description": "Synapse is the reference homeserver implementation for Matrix, an open standard for secure, decentralised, real-time communication.", + "logo": "synapse.svg", + "links": { + "github": "https://github.com/element-hq/synapse", + "website": "https://element-hq.github.io/synapse/latest/", + "docs": "https://element-hq.github.io/synapse/latest/setup/installation.html" + }, + "tags": [ + "matrix", + "communication" + ] +} diff --git a/blueprints/synapse/synapse.svg b/blueprints/synapse/synapse.svg new file mode 100644 index 00000000..d2ab11db --- /dev/null +++ b/blueprints/synapse/synapse.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/blueprints/synapse/template.toml b/blueprints/synapse/template.toml new file mode 100644 index 00000000..f87bcdbb --- /dev/null +++ b/blueprints/synapse/template.toml @@ -0,0 +1,93 @@ +[variables] +main_domain = "${domain}" +postgres_password = "${password:32}" +registration_shared_secret = "${password:32}" +macaroon_secret_key = "${password:32}" +form_secret = "${password:32}" + +[config] +env = [ + "POSTGRES_PASSWORD=${postgres_password}", +] + +[[config.domains]] +serviceName = "synapse" +port = 8008 +host = "${main_domain}" + +[[config.mounts]] +filePath = "homeserver.yaml" +content = """ +# Synapse homeserver configuration +# https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html + +server_name: "${main_domain}" +public_baseurl: "https://${main_domain}/" +pid_file: /data/homeserver.pid +signing_key_path: "/data/signing.key" +log_config: "/config/log.config" +media_store_path: /data/media_store +report_stats: false + +# Serve /.well-known/matrix/server so other homeservers can federate with +# this server over port 443 (the dedicated federation port 8448 is not exposed). +serve_server_wellknown: true + +listeners: + - port: 8008 + tls: false + type: http + x_forwarded: true + bind_addresses: ['0.0.0.0'] + resources: + - names: [client, federation] + compress: false + +database: + name: psycopg2 + args: + user: synapse + password: "${postgres_password}" + database: synapse + host: postgres + port: 5432 + cp_min: 5 + cp_max: 10 + +# Public registration is disabled. Create users with the +# register_new_matrix_user tool (see the template instructions). +enable_registration: false +registration_shared_secret: "${registration_shared_secret}" + +macaroon_secret_key: "${macaroon_secret_key}" +form_secret: "${form_secret}" + +trusted_key_servers: + - server_name: "matrix.org" +suppress_key_server_warning: true +""" + +[[config.mounts]] +filePath = "log.config" +content = """ +version: 1 + +formatters: + precise: + format: '%(asctime)s - %(name)s - %(lineno)d - %(levelname)s - %(request)s - %(message)s' + +handlers: + console: + class: logging.StreamHandler + formatter: precise + +loggers: + synapse.storage.SQL: + level: INFO + +root: + level: INFO + handlers: [console] + +disable_existing_loggers: false +"""