Unify Complement developer docs by MadLittleMods · Pull Request #19518 · element-hq/synapse

MadLittleMods · 2026-03-03T00:19:40Z

Unify Complement developer docs

Instead of having info spread across a few places, consolidate and link to one spot.

Pull Request Checklist

Pull request is based on the develop branch
Pull request includes a changelog file. The entry should:
- Be a short description of your change which makes sense to users. "Fixed a bug that prevented receiving messages from other servers." instead of "Moved X method from EventStore to EventWorkerStore.".
- Use markdown where necessary, mostly for code blocks.
- End with either a period (.) or an exclamation mark (!).
- Start with a capital letter.
- Feel free to credit yourself, by adding a sentence "Contributed by @github_username." or "Contributed by [Your Name]." to the end of the entry.
Code style is correct (run the linters)

MadLittleMods · 2026-03-03T00:20:55Z

complement/README.md

+The above will run a monolithic (single-process) Synapse with SQLite as the database.
+For other configurations, try:
+
+- Passing `POSTGRES=1` as an environment variable to use the Postgres database instead.
+- Passing `WORKERS=1` as an environment variable to use a workerised setup instead. This
+  option implies the use of Postgres.
+  - If setting `WORKERS=1`, optionally set `WORKER_TYPES=` to declare which worker types
+    you wish to test. A simple comma-delimited string containing the worker types
+    defined from the `WORKERS_CONFIG` template in
+    [here](https://github.com/element-hq/synapse/blob/develop/docker/configure_workers_and_start.py#L54).
+    A safe example would be `WORKER_TYPES="federation_inbound, federation_sender,
+    synchrotron"`. See the [worker documentation](../workers.md) for additional
+    information on workers.
+- Passing `ASYNCIO_REACTOR=1` as an environment variable to use the Twisted asyncio
+  reactor instead of the default one.
+- Passing `PODMAN=1` will use the [podman](https://podman.io/) container runtime,
+  instead of docker.
+- Passing `UNIX_SOCKETS=1` will utilise Unix socket functionality for Synapse, Redis,
+  and Postgres(when applicable).


Moved from docs/development/contributing_guide.md with wrapping

MadLittleMods · 2026-03-03T00:21:22Z

complement/README.md

+To increase the log level for the tests, set `SYNAPSE_TEST_LOG_LEVEL`, e.g:
+```sh
+SYNAPSE_TEST_LOG_LEVEL=DEBUG COMPLEMENT_DIR=../complement ./scripts-dev/complement.sh -run TestRoomCreate
+```


Moved from docs/development/contributing_guide.md (just with a different test to match the other examples here, TestRoomCreate)

MadLittleMods · 2026-03-03T00:21:45Z

docs/development/contributing_guide.md

+See [our Complement docs](https://github.com/element-hq/synapse/tree/develop/complement)
+for how to use our `./scripts-dev/complement.sh` test runner script.


Since this appears on https://element-hq.github.io/synapse/latest/development/contributing_guide.html, I've linked to our GitHub repo instead of a relative link within the repo.

MadLittleMods · 2026-03-03T00:31:51Z

complement/README.md

+### Access database for homeserver after Complement test runs.
+
+If you're curious what the database looks like after you run some tests, here are some
+steps to get you going in Synapse:
+
+1. In your Complement test comment out `defer deployment.Destroy(t)` and replace with
+   `defer time.Sleep(2 * time.Hour)` to keep the homeserver running after the tests
+   complete
+1. Start the Complement tests
+1. Find the name of the container, `docker ps -f name=complement_` (this will filter for
+   just the Compelement related Docker containers)
+1. Access the container replacing the name with what you found in the previous step:
+   `docker exec -it complement_1_hs_with_application_service.hs1_2 /bin/bash`
+1. Install sqlite (database driver), `apt-get update && apt-get install -y sqlite3`
+1. Then run `sqlite3` and open the database `.open /conf/homeserver.db` (this db path
+   comes from the Synapse homeserver.yaml)


Moved from docs/development/contributing_guide.md with wrapping

complement/README.md

See #19518 (comment)

MadLittleMods · 2026-03-03T19:19:06Z

Thanks for the review @reivilibre 🐂

This PR contains the following updates: | Package | Update | Change | |---|---|---| | [element-hq/synapse](https://github.com/element-hq/synapse) | minor | `v1.149.1` → `v1.150.0` | --- ### Release Notes <details> <summary>element-hq/synapse (element-hq/synapse)</summary> ### [`v1.150.0`](https://github.com/element-hq/synapse/releases/tag/v1.150.0) [Compare Source](element-hq/synapse@v1.149.1...v1.150.0) ### Synapse 1.150.0 (2026-03-24) No significant changes since 1.150.0rc1. ### Synapse 1.150.0rc1 (2026-03-17) #### Features - Add experimental support for the [MSC4370](matrix-org/matrix-spec-proposals#4370) Federation API `GET /extremities` endpoint. ([#19314](element-hq/synapse#19314)) - [MSC4140: Cancellable delayed events](matrix-org/matrix-spec-proposals#4140): When persisting a delayed event to the timeline, include its `delay_id` in the event's `unsigned` section in `/sync` responses to the event sender. ([#19479](element-hq/synapse#19479)) - Expose [MSC4354 Sticky Events](matrix-org/matrix-spec-proposals#4354) over the legacy (v3) /sync API. ([#19487](element-hq/synapse#19487)) - When Matrix Authentication Service (MAS) integration is enabled, allow MAS to set the user locked status in Synapse. ([#19554](element-hq/synapse#19554)) #### Bugfixes - Fix `Build and push complement image` CI job pointing to non-existent image. ([#19523](element-hq/synapse#19523)) - Fix a bug introduced in v1.26.0 that caused deactivated, erased users to not be removed from the user directory. ([#19542](element-hq/synapse#19542)) #### Improved Documentation - In the Admin API documentation, always express path parameters as `/<param>` instead of as `/$param`. ([#19307](element-hq/synapse#19307)) - Update docs to clarify `outbound_federation_restricted_to` can also be used with the [Secure Border Gateway (SBG)](https://element.io/en/server-suite/secure-border-gateways). ([#19517](element-hq/synapse#19517)) - Unify Complement developer docs. ([#19518](element-hq/synapse#19518)) #### Internal Changes - Put membership updates in a background resumable task when changing the avatar or the display name. ([#19311](element-hq/synapse#19311)) - Add in-repo Complement test to sanity check Synapse version matches git checkout (testing what we think we are). ([#19476](element-hq/synapse#19476)) - Migrate `dev` dependencies to [PEP 735](https://peps.python.org/pep-0735/) dependency groups. ([#19490](element-hq/synapse#19490)) - Remove the optional `systemd-python` dependency and the `systemd` extra on the `synapse` package. ([#19491](element-hq/synapse#19491)) - Avoid re-computing the event ID when cloning events. ([#19527](element-hq/synapse#19527)) - Allow caching of the `/versions` and `/auth_metadata` public endpoints. ([#19530](element-hq/synapse#19530)) - Add a few labels to the number groupings in the `Processed request` logs. ([#19548](element-hq/synapse#19548)) </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Reviewed-on: https://gitea.alexlebens.dev/alexlebens/infrastructure/pulls/5040 Co-authored-by: Renovate Bot <renovate-bot@alexlebens.net> Co-committed-by: Renovate Bot <renovate-bot@alexlebens.net>

Unify Complement docs

082dcc3

MadLittleMods added A-Docs A-Testing labels Mar 3, 2026

Add changelog

d151533

MadLittleMods commented Mar 3, 2026

View reviewed changes

MadLittleMods added 3 commits March 2, 2026 18:26

Less our

56401ec

Point to the new place

314fc96

Move database access docs

493dc98

MadLittleMods commented Mar 3, 2026

View reviewed changes

Fix typo

23bdfab

MadLittleMods marked this pull request as ready for review March 3, 2026 04:01

MadLittleMods requested a review from a team as a code owner March 3, 2026 04:01

reivilibre self-requested a review March 3, 2026 17:28

reivilibre approved these changes Mar 3, 2026

View reviewed changes

complement/README.md Outdated Show resolved Hide resolved

MadLittleMods added 2 commits March 3, 2026 12:04

Merge branch 'develop' into madlittlemods/unify-complement-docs

63672e4

"asyncio-backed reactor for Twisted"

a6f9db3

See #19518 (comment)

MadLittleMods merged commit 46c6e0a into develop Mar 3, 2026
44 checks passed

MadLittleMods deleted the madlittlemods/unify-complement-docs branch March 3, 2026 19:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Unify Complement developer docs#19518

Unify Complement developer docs#19518
MadLittleMods merged 8 commits intodevelopfrom
madlittlemods/unify-complement-docs

MadLittleMods commented Mar 3, 2026 •

edited

Loading

Uh oh!

MadLittleMods Mar 3, 2026

Uh oh!

MadLittleMods Mar 3, 2026

Uh oh!

MadLittleMods Mar 3, 2026

Uh oh!

MadLittleMods Mar 3, 2026

Uh oh!

Uh oh!

Uh oh!

MadLittleMods commented Mar 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		See [our Complement docs](https://github.com/element-hq/synapse/tree/develop/complement)
		for how to use our `./scripts-dev/complement.sh` test runner script.

Conversation

MadLittleMods commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Checklist

Uh oh!

MadLittleMods Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

MadLittleMods Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

MadLittleMods Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

MadLittleMods Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

MadLittleMods commented Mar 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MadLittleMods commented Mar 3, 2026 •

edited

Loading