[PR #1017] [MERGED] feat: add Synapse (Matrix homeserver) template #16325

New Issue

GiteaMirror · 2026-07-14T23:19:20-05:00

GiteaMirror commented

2026-07-14 23:19:20 -05:00

📋 Pull Request Information

Original PR: https://github.com/Dokploy/templates/pull/1017
Author: @Siumauricio
Created: 7/14/2026
Status: ✅ Merged
Merged: 7/14/2026
Merged by: @Siumauricio

Base: canary ← Head: feat/synapse

📝 Commits (1)

b23ddd0 feat: add Synapse (Matrix homeserver) template

📊 Changes

5 files changed (+204 additions, -0 deletions)

View changed files

➕ blueprints/synapse/docker-compose.yml (+51 -0)
➕ blueprints/synapse/instructions.md (+39 -0)
➕ blueprints/synapse/meta.json (+16 -0)
➕ blueprints/synapse/synapse.svg (+5 -0)
➕ blueprints/synapse/template.toml (+93 -0)

📄 Description

Adds a template for Synapse, the reference Matrix homeserver (matrixdotorg/synapse:v1.156.0, latest stable, released 2026-07-07), backed by PostgreSQL 16.

The repo already ships lighter Matrix homeservers (conduit, conduwuit, tuwunel), but Synapse remains the reference implementation and the most feature-complete one, and it was explicitly requested in #126.

Design decisions

Static config via mounts, not env vars. The Synapse image no longer supports generating homeserver.yaml from environment variables at runtime (start.py errors out with "no longer supports generating a config file on-the-fly"), so the template mounts a rendered homeserver.yaml + log.config through [[config.mounts]] and points SYNAPSE_CONFIG_PATH at it. All secrets (registration_shared_secret, macaroon_secret_key, form_secret, postgres password) are generated per-deployment by the template engine.
First-boot key generation. In run mode the stock entrypoint neither generates the signing key nor chowns /data, so the compose entrypoint runs --generate-keys and chown -R 991:991 /data before exec'ing the regular /start.py. Config files are mounted read-only under /config (outside /data) so the chown never touches them.
Registration: shared secret, closed by default. enable_registration: false; users are created with register_new_matrix_user against the generated registration_shared_secret — documented in instructions.md. This avoids shipping an open-registration server by default.
Postgres with C collation (POSTGRES_INITDB_ARGS=--lc-collate=C --lc-ctype=C), which Synapse requires, plus a healthcheck-gated depends_on.
Federation works through .well-known delegation over HTTPS/443 (serve_server_wellknown: true; the federation resource is on the same 8008 listener). The dedicated federation port 8448 is not exposed, which is noted in the instructions.

Test evidence (deployed on a Dokploy instance)

Deploy: done, both containers running/healthy.
GET / → 200 "Synapse is running"; GET /health → 200 OK
GET /_matrix/client/versions → 200 JSON (spec versions up to v1.12)
GET /.well-known/matrix/server → 200 {"m.server":"<domain>:443"}
GET /_synapse/admin/v1/register → 200 nonce (shared-secret registration path used by register_new_matrix_user is active)
POST /_matrix/client/v3/register → 403 M_FORBIDDEN "Registration has been disabled" (as designed)

node build-scripts/generate-meta.js --check passes (477 templates validated).

Closes #126

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/Dokploy/templates/pull/1017 **Author:** [@Siumauricio](https://github.com/Siumauricio) **Created:** 7/14/2026 **Status:** ✅ Merged **Merged:** 7/14/2026 **Merged by:** [@Siumauricio](https://github.com/Siumauricio) **Base:** `canary` ← **Head:** `feat/synapse` --- ### 📝 Commits (1) - [`b23ddd0`](https://github.com/Dokploy/templates/commit/b23ddd0b9890df22b3e4b77d44049a94443673e2) feat: add Synapse (Matrix homeserver) template ### 📊 Changes **5 files changed** (+204 additions, -0 deletions) <details> <summary>View changed files</summary> ➕ `blueprints/synapse/docker-compose.yml` (+51 -0) ➕ `blueprints/synapse/instructions.md` (+39 -0) ➕ `blueprints/synapse/meta.json` (+16 -0) ➕ `blueprints/synapse/synapse.svg` (+5 -0) ➕ `blueprints/synapse/template.toml` (+93 -0) </details> ### 📄 Description Adds a template for [Synapse](https://github.com/element-hq/synapse), the reference Matrix homeserver (`matrixdotorg/synapse:v1.156.0`, latest stable, released 2026-07-07), backed by PostgreSQL 16. The repo already ships lighter Matrix homeservers (conduit, conduwuit, tuwunel), but Synapse remains the reference implementation and the most feature-complete one, and it was explicitly requested in #126. ## Design decisions - **Static config via mounts, not env vars.** The Synapse image no longer supports generating `homeserver.yaml` from environment variables at runtime (`start.py` errors out with "no longer supports generating a config file on-the-fly"), so the template mounts a rendered `homeserver.yaml` + `log.config` through `[[config.mounts]]` and points `SYNAPSE_CONFIG_PATH` at it. All secrets (`registration_shared_secret`, `macaroon_secret_key`, `form_secret`, postgres password) are generated per-deployment by the template engine. - **First-boot key generation.** In `run` mode the stock entrypoint neither generates the signing key nor chowns `/data`, so the compose entrypoint runs `--generate-keys` and `chown -R 991:991 /data` before exec'ing the regular `/start.py`. Config files are mounted read-only under `/config` (outside `/data`) so the chown never touches them. - **Registration: shared secret, closed by default.** `enable_registration: false`; users are created with `register_new_matrix_user` against the generated `registration_shared_secret` — documented in `instructions.md`. This avoids shipping an open-registration server by default. - **Postgres with C collation** (`POSTGRES_INITDB_ARGS=--lc-collate=C --lc-ctype=C`), which Synapse requires, plus a healthcheck-gated `depends_on`. - **Federation** works through `.well-known` delegation over HTTPS/443 (`serve_server_wellknown: true`; the federation resource is on the same 8008 listener). The dedicated federation port 8448 is not exposed, which is noted in the instructions. ## Test evidence (deployed on a Dokploy instance) - Deploy: `done`, both containers running/healthy. - `GET /` → 200 "Synapse is running"; `GET /health` → 200 `OK` - `GET /_matrix/client/versions` → 200 JSON (spec versions up to v1.12) - `GET /.well-known/matrix/server` → 200 `{"m.server":"<domain>:443"}` - `GET /_synapse/admin/v1/register` → 200 nonce (shared-secret registration path used by `register_new_matrix_user` is active) - `POST /_matrix/client/v3/register` → 403 `M_FORBIDDEN` "Registration has been disabled" (as designed) `node build-scripts/generate-meta.js --check` passes (477 templates validated). Closes #126 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

GiteaMirror added the pull-request label 2026-07-14 23:19:20 -05:00

GiteaMirror closed this issue

2026-07-14 23:19:21 -05:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/templates#16325