Synapse on StartOS

Upstream docs: https://element-hq.github.io/synapse/latest

Everything not listed in this document should behave the same as upstream Synapse. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable.

Synapse is the battle-tested, reference implementation of the Matrix protocol -- a next-generation, federated, full-featured, encrypted, independent messaging system.

Image and Container Runtime

Property	Value
Synapse image	`ghcr.io/element-hq/synapse` (upstream pre-built image)
Nginx image	`nginx` Alpine (upstream unmodified)
PostgreSQL image	`postgres` Alpine (database sidecar)
Architectures	x86_64, aarch64

Synapse runs behind an Nginx reverse proxy. Nginx handles client requests on port 80, proxies Matrix API traffic to Synapse on port 8008, and serves the Synapse Admin dashboard on port 8080.

Volume and Data Layout

Volume	Mount Point	Purpose
`main`	`/data`	Synapse config, media, keys, appservices, StartOS state
`db`	`/var/lib/postgresql`	PostgreSQL data

Key files on the main volume:

homeserver.yaml -- primary Synapse configuration (managed by StartOS)
homeserver.signing.key -- server signing key (auto-generated by Synapse)
homeserver.log.config -- logging configuration
media_store/ -- uploaded media files
store.json -- StartOS metadata (admin state, postgres password, SMTP config)
appservices/*.yaml -- registered bridge/appservice configurations

Installation and First-Run Flow

Step	Upstream	StartOS
Generate config	`python -m synapse.app.homeserver --generate-config`	Automatic via `setupOnInit`
Set server name	Edit `homeserver.yaml`	"Set Server Address/URL" action (critical task)
Create admin user	`register_new_matrix_user` CLI	"Set Admin Password" action (critical task) -- generates a password; the actual user is registered when the service first starts

Key difference: On first install, StartOS generates the initial Synapse config automatically. You must run the "Set Server Address/URL" action (created as a critical task) to choose your permanent domain before starting. Completing it surfaces "Set Admin Password" as a second critical task; running that generates and shows the credentials. Starting the service then registers the admin user with the chosen password.

Warning: The server address/URL is permanent and cannot be changed after the first start.

Configuration Management

Setting	Upstream Method	StartOS Method
`server_name`	`homeserver.yaml`	"Set Server Address/URL" action (one-time)
`enable_registration`	`homeserver.yaml`	"Config" action
Federation	`homeserver.yaml` listeners	"Config" action (enable/disable + domain whitelist)
`max_upload_size`	`homeserver.yaml`	"Config" action (1-2000 MB)
SMTP/email	`homeserver.yaml`	"Config" action (disabled/system/custom)
Admin password	`register_new_matrix_user`	"Set Admin Password" action
Appservices	Manual YAML files	Register/List/Delete Appservice actions

Configuration NOT exposed on StartOS:

log_config -- fixed logging configuration
database -- always PostgreSQL via sidecar container
trusted_key_servers -- defaults to matrix.org
report_stats -- always disabled
Listener bind addresses and ports

Network Access and Interfaces

Interface	Port	Protocol	Type	Purpose
Homeserver	80 (nginx)	HTTP	API	Matrix client and federation API
Admin Dashboard	8080 (nginx)	HTTP	UI	Synapse Admin web interface

Internally, Synapse listens on port 8008. Nginx proxies traffic from port 80, handles .well-known/matrix/server responses, and enforces max_upload_size on Matrix API routes.

Actions (StartOS UI)

Set Server Address/URL

Property	Value
ID	`set-server-name`
Visibility	Hidden after first start
Availability	Only when stopped
Purpose	Choose permanent server domain (clearnet or Tor)

Presents available hostnames from the homeserver interface. Sets server_name and public_baseurl in homeserver.yaml. Cannot be changed after first start.

Set Admin Password

Property	Value
ID	`set-admin-password`
Visibility	Enabled
Availability	Any status
Purpose	Set or reset the admin account password

Generates a random 22-character password, stores it in store.json as pendingAdminPassword, and displays it. The next time the service starts, an apply-admin-password oneshot in the daemon chain consumes the pending password: if no users exist in PostgreSQL it runs register_new_matrix_user to create the admin; otherwise it hashes the password with hash_password and UPDATEs the first-registered user's password_hash. The pending field is cleared on success.

Config

Property	Value
ID	`config`
Visibility	Enabled
Availability	Any status
Purpose	Configure registration, federation, upload limits, SMTP

Settings:

Setting	Default	Description
Registration	Disabled	Allow public account creation
Federation	Disabled	Enable/disable with optional domain whitelist
Max Upload Size	50 MB	File upload limit (1-2000 MB)
SMTP	Disabled	Email notifications (disabled/system/custom)

Register Appservice

Property	Value
ID	`register-appservice`
Visibility	Enabled
Availability	Any status
Purpose	Register a Matrix bridge with the homeserver

Accepts appservice credentials (ID, tokens, URL, namespace regex) and writes the registration YAML. Typically triggered automatically by bridge services via the exported ensureAppserviceRegistration API.

List Appservices

Property	Value
ID	`list-appservices`
Visibility	Enabled
Availability	Any status
Purpose	View all registered bridges

Delete Appservice

Property	Value
ID	`delete-appservice`
Visibility	Enabled
Availability	Any status
Purpose	Remove a registered bridge

Create Bot User

Property	Value
ID	`create-bot-user`
Visibility	Hidden
Availability	Only when running
Purpose	Create non-admin bot accounts for bridge services

Backups and Restore

Included in backup:

main volume -- Synapse config, media, keys, appservice registrations, StartOS state
db volume -- PostgreSQL database (backed up via pg_dump, restored via pg_restore)

Restore behavior:

All data, users, rooms, and settings are restored
Server name, keys, and admin credentials remain the same

Health Checks

Check	Method	Grace Period	Display
Database	`pg_isready`	Default	"Database"
Homeserver	HTTP GET `http://localhost:8008/health`	15 seconds	"Homeserver"
Nginx	Port listening on 80	Default	Hidden
Admin Dashboard	HTTP GET `http://localhost:8080`	Default	"Admin Dashboard"

Dependencies

None.

Limitations and Differences

Server name is permanent -- once set and started, the server address/URL cannot be changed
Admin username fixed -- always admin; only password can be changed
No workers -- runs as a single monolith process (no worker-based scaling)
Fixed logging -- log configuration is not user-configurable (INFO level, 100 MB rotation)
No direct homeserver.yaml editing -- configuration is managed through StartOS actions
Tor federation limitations -- .onion servers can only federate with other .onion servers

What Is Unchanged from Upstream

Full Matrix protocol compliance (client-server and server-server APIs)
End-to-end encryption support
Federation (when enabled)
Room creation, membership, and permissions
Media uploads and downloads
Push notifications
Account data and device management
Presence and typing indicators
All Matrix client compatibility (Element, FluffyChat, etc.)

Contributing

See CONTRIBUTING.md for build instructions and development workflow.

Quick Reference for AI Consumers

package_id: synapse
images:
  synapse: dockerTag (ghcr.io/element-hq/synapse)
  nginx: nginx (Alpine)
  postgres: postgres (Alpine)
architectures: [x86_64, aarch64]
volumes:
  main: /data
  db: /var/lib/postgresql
ports:
  homeserver: 80 (nginx proxy to synapse:8008)
  admin: 8080 (synapse-admin dashboard)
dependencies: none
database: PostgreSQL (sidecar, localhost-only, password auth)
startos_managed_config:
  - server_name (one-time, permanent)
  - enable_registration
  - federation (listeners + domain whitelist)
  - max_upload_size
  - smtp
actions:
  - set-server-name (enabled/hidden, only-stopped)
  - set-admin-password (enabled, any)
  - config (enabled, any)
  - register-appservice (enabled, any)
  - list-appservices (enabled, any)
  - delete-appservice (enabled, any)
  - create-bot-user (hidden, only-running)
health_checks:
  - pg_isready (postgres)
  - http_get: /health (port 8008, 15s grace)
  - port_listening: 80
  - http_get: / (port 8080)
backup_method: pg_dump + main volume
public_api:
  - ensureAppserviceRegistration (for bridge services)

Name		Name	Last commit message	Last commit date
Latest commit History 237 Commits
.github/workflows		.github/workflows
assets		assets
startos		startos
.dockerignore		.dockerignore
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
TODO.md		TODO.md
UPDATING.md		UPDATING.md
icon.svg		icon.svg
instructions.md		instructions.md
package-lock.json		package-lock.json
package.json		package.json
s9pk.mk		s9pk.mk
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Synapse on StartOS

Table of Contents

Image and Container Runtime

Volume and Data Layout

Installation and First-Run Flow

Configuration Management

Network Access and Interfaces

Actions (StartOS UI)

Set Server Address/URL

Set Admin Password

Config

Register Appservice

List Appservices

Delete Appservice

Create Bot User

Backups and Restore

Health Checks

Dependencies

Limitations and Differences

What Is Unchanged from Upstream

Contributing

Quick Reference for AI Consumers

About

Uh oh!

Releases 19

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Synapse on StartOS

Table of Contents

Image and Container Runtime

Volume and Data Layout

Installation and First-Run Flow

Configuration Management

Network Access and Interfaces

Actions (StartOS UI)

Set Server Address/URL

Set Admin Password

Config

Register Appservice

List Appservices

Delete Appservice

Create Bot User

Backups and Restore

Health Checks

Dependencies

Limitations and Differences

What Is Unchanged from Upstream

Contributing

Quick Reference for AI Consumers

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 19

Uh oh!

Contributors

Uh oh!

Languages