hlhd/synapse
Synapse with S3 media offload and the antispam hook, hardened and rootless.
156
hlhd/synapse repository overview
synapse
A rootless, hardened container image for Synapse — the reference Matrix homeserver — carrying media offload to S3-compatible object storage and the antispam hook moderation tooling needs. A thin, digest-pinned layer over Element's published image: it adds what a self-hosted deployment actually needs, drops the package installer and every setuid binary, and runs as a non-root user with no root code path at all.
Documentation
| Topic | |
|---|---|
| Configuration | Database requirements, delegation, media storage, the bundled modules and what they need |
What Matrix is
| Federated, not hosted | Servers exchange messages directly, so a conversation spans hubs the way email spans providers — no single operator sits in the middle of it |
| Your name, your server | Identities are @you:example.com. The domain is the identity, which is why it is delegated from the apex and never changes afterwards |
| Encrypted by default | End-to-end encryption with cross-signed device verification, so a compromised server still cannot read rooms |
| Bridges to everything else | Application services relay WhatsApp, Signal, Discord, IRC and Slack into ordinary rooms — the one path that replaces a proprietary chat network without asking anyone to switch apps |
| Rooms, spaces, threads | Spaces group rooms, threads keep replies out of the main timeline, and both federate |
| Calls | Voice and video via MatrixRTC, which runs beside the homeserver rather than through it |
What this image adds
| S3 media offload | synapse-s3-storage-provider — keep the media repository in object storage instead of growing a volume without bound. Brings the s3_media_upload CLI for migrating media already on disk |
| Moderation hook | synapse-http-antispam — inert until configured, it is what Draupnir uses to reject events before the server accepts them, rather than cleaning up afterwards |
| No root code path | Upstream's image has no USER and its entrypoint runs as root to write config and drop privileges. Config comes from the deployment here, so that entrypoint is replaced outright rather than bypassed |
| No installer | pip, setuptools and wheel are removed after the modules are in. Nothing installs packages at runtime, so the installer is only attack surface |
| No setuid binaries | Every setuid and setgid bit in the image is stripped. A homeserver needs no path to root |
| Read-only-rootfs ready | Bytecode writing is off and everything Synapse writes is a mount, so readOnlyRootFilesystem: true holds |
| Pinned by digest | The base is addressed by digest, not tag — a tag can be re-pushed, a digest cannot |
Image contents
Base image & modules (click to expand)
Base Image:
Pinned components — see components.json:
| Component | Source | Version |
|---|---|---|
| base | element-hq/synapse (digest-pinned) | v1.160.0 |
| media provider | synapse-s3-storage-provider | 1.7.0 |
| antispam hook | synapse-http-antispam | 0.5.1 |
Installation
docker pull ghcr.io/homelabhd/synapse:latest
# or
docker pull docker.io/hlhd/synapse:latest
Synapse needs a PostgreSQL database created with UTF8 encoding and C collation — it verifies this at startup, and the only remedy afterwards is a dump and restore. It serves the client and federation APIs on 8008; put TLS in front of it and set x_forwarded: true so the client address survives the hop.
The container runs as uid 991 with no writable root filesystem, so mount the paths Synapse writes: its data directory (which holds the signing key — this server's federation identity, and unrecoverable if lost), the media store unless it is in object storage, and /tmp.
Both bundled modules are inert until homeserver.yaml names them; see the module documentation.
Contributing
- Fork the repository
- Submit Pull Requests / Merge Requests
- File issues with image tag, run/compose command, and environment details
Credits
- Powered by Synapse, maintained by Element
- Upstream source is mirrored at HomeLabHD/synapse-core — kept for source availability, not built from
Disclaimer
The Software provided hereunder ("Software") is licensed "as-is," without warranties of any kind — express, implied, or federated to you by a homeserver you have never heard of. The developer makes no promises about functionality, performance, compatibility, security, or availability. Not liable if your state groups grow larger than your storage budget, if a room join drags in a decade of someone else's history, or if removing
pipgives you such a smug sense of minimalism that you forget where the signing key is backed up.
Any positive experiences are owed entirely to the folks at Element and the unstoppable force that is the Open Source community. The developer claims no credit for anything that actually goes right.
License
Synapse is distributed under AGPL-3.0-or-later, or a commercial licence from Element. This packaging is maintained by HomeLabHD; the unmodified upstream source is mirrored at synapse-core.
Tag summary
Content type
Image
Digest
sha256:031573d6a…
Size
126.6 MB
Last updated
3 days ago
docker pull hlhd/synapse:dev-8614544