feat: add Synapse (Matrix homeserver) template

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-16 03:15:23 +02:00 · 2026-07-14 12:12:24 -06:00
parent 17efd705a4
commit b23ddd0b98
5 changed files with 204 additions and 0 deletions
--- a/blueprints/synapse/docker-compose.yml
+++ 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:
--- a/blueprints/synapse/instructions.md
+++ 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).
--- a/blueprints/synapse/meta.json
+++ 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"
+  ]
+}
--- a/blueprints/synapse/synapse.svg
+++ b/blueprints/synapse/synapse.svg
@@ -0,0 +1,5 @@
+<svg width="75" height="32" xmlns="http://www.w3.org/2000/svg">
+  <g fill="#000000" fill-rule="nonzero">
+    <path d="M.936.732V31.25H3.13v.732H.095V0h3.034v.732zM9.386 10.407v1.544h.044a4.461 4.461 0 0 1 1.487-1.368c.58-.323 1.245-.485 1.993-.485.72 0 1.377.14 1.972.42.595.279 1.047.771 1.355 1.477.338-.5.796-.941 1.377-1.323.58-.383 1.266-.574 2.06-.574.602 0 1.16.074 1.674.22.514.148.954.383 1.322.707.366.323.653.746.859 1.268.205.522.308 1.15.308 1.887v7.633H20.71v-6.464c0-.383-.015-.743-.044-1.082a2.305 2.305 0 0 0-.242-.882 1.473 1.473 0 0 0-.584-.596c-.257-.146-.606-.22-1.047-.22-.44 0-.796.085-1.068.253-.272.17-.485.39-.639.662a2.654 2.654 0 0 0-.308.927 7.074 7.074 0 0 0-.078 1.048v6.354h-3.128v-6.398c0-.338-.007-.673-.021-1.004a2.825 2.825 0 0 0-.188-.916 1.411 1.411 0 0 0-.55-.673c-.258-.168-.636-.253-1.135-.253a2.33 2.33 0 0 0-.584.1 1.94 1.94 0 0 0-.705.374c-.228.184-.422.449-.584.794-.161.346-.242.798-.242 1.357v6.619H6.434V10.407h2.952zM25.842 12.084a3.751 3.751 0 0 1 1.233-1.17 5.37 5.37 0 0 1 1.685-.629 9.579 9.579 0 0 1 1.884-.187c.573 0 1.153.04 1.74.121.588.081 1.124.24 1.609.475.484.235.88.562 1.19.981.308.42.462.975.462 1.666v5.934c0 .516.03 1.008.088 1.478.058.471.161.824.308 1.06H32.87a4.435 4.435 0 0 1-.22-1.104c-.5.515-1.087.876-1.762 1.081a7.084 7.084 0 0 1-2.071.31c-.544 0-1.05-.067-1.52-.2a3.472 3.472 0 0 1-1.234-.617 2.87 2.87 0 0 1-.826-1.059c-.199-.426-.298-.934-.298-1.522 0-.647.114-1.18.342-1.6.227-.419.52-.753.881-1.004.36-.25.771-.437 1.234-.562.462-.125.929-.224 1.399-.298.47-.073.932-.132 1.387-.176.456-.044.86-.11 1.212-.199.353-.088.631-.217.837-.386.206-.169.301-.415.287-.74 0-.337-.055-.606-.166-.804a1.217 1.217 0 0 0-.44-.464 1.737 1.737 0 0 0-.639-.22 5.292 5.292 0 0 0-.782-.055c-.617 0-1.101.132-1.454.397-.352.264-.558.706-.617 1.323h-3.128c.044-.735.227-1.345.55-1.83zm6.179 4.423a5.095 5.095 0 0 1-.639.165 9.68 9.68 0 0 1-.716.11c-.25.03-.5.067-.749.11a5.616 5.616 0 0 0-.694.177 2.057 2.057 0 0 0-.594.298c-.17.125-.305.284-.408.474-.103.192-.154.434-.154.728 0 .28.051.515.154.706.103.192.242.342.419.453.176.11.381.187.617.231.234.044.477.066.726.066.617 0 1.094-.102 1.432-.309.338-.205.587-.452.75-.739.16-.286.26-.576.297-.87.036-.295.055-.53.055-.707v-1.17a1.4 1.4 0 0 1-.496.277zM43.884 10.407v2.096h-2.291v5.647c0 .53.088.883.264 1.059.176.177.529.265 1.057.265.177 0 .345-.007.507-.022.161-.015.316-.037.463-.066v2.426a7.49 7.49 0 0 1-.882.089 21.67 21.67 0 0 1-.947.022c-.484 0-.944-.034-1.377-.1a3.233 3.233 0 0 1-1.145-.386 2.04 2.04 0 0 1-.782-.816c-.191-.353-.287-.816-.287-1.39v-6.728H36.57v-2.096h1.894v-3.42h3.129v3.42h2.29zM48.355 10.407v2.118h.044a3.907 3.907 0 0 1 1.454-1.754 4.213 4.213 0 0 1 1.036-.497 3.734 3.734 0 0 1 1.145-.176c.206 0 .433.037.683.11v2.912a5.862 5.862 0 0 0-.528-.077 5.566 5.566 0 0 0-.595-.033c-.573 0-1.058.096-1.454.287a2.52 2.52 0 0 0-.958.783 3.143 3.143 0 0 0-.518 1.158 6.32 6.32 0 0 0-.154 1.434v5.14h-3.128V10.407h2.973zM54.039 8.642V6.06h3.128v2.582H54.04zm3.128 1.765v11.405H54.04V10.407h3.128zM58.797 10.407h3.569l2.005 2.978 1.982-2.978h3.459l-3.745 5.339 4.208 6.067h-3.57l-2.378-3.596-2.38 3.596h-3.502l4.097-6.001zM74.094 31.25V.732H71.9V0h3.035v31.982H71.9v-.732z"/>
+  </g>
+</svg>
--- a/blueprints/synapse/template.toml
+++ 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
+"""