Matrix Server (ESS CE) is a full Matrix homeserver stack: Synapse + Element Web + Element Call (Voice/Video) + LiveKit SFU + Synapse Admin + PostgreSQL — as a single Home Assistant Add-on.

⚠️ server_name cannot be changed after first start. Choose carefully.

#Component Overview

Component	Version	Purpose
Synapse	1.148.0	Matrix homeserver
PostgreSQL 15	Debian pkg	Database
Element Web	v1.12.11	Web client
Element Call	latest	Voice / Video calls
LiveKit SFU	latest	WebRTC media server
Synapse Admin	v0.10.3-etke32	Admin UI

Synapse Admin uses the etkecc fork — required for Synapse 1.14x compatibility.

#Minimum Operating Model

Browser           → Element Web    :7080 (via NPM)
Browser           → Synapse Admin  :8090 (via NPM)
Matrix Clients    → Synapse API    :8008 (via NPM)
Federation        → Synapse        :8448 (direct, router forward)
Element Call/VC   → LiveKit SFU    :7880 (via NPM, WebSocket)

#Step 1 — Add Repository

1. Open Home Assistant.
2. Go to Settings → Add-ons → Add-on Store.
3. Open ⋮ → Repositories.
4. Add:

https://github.com/pol4rfuchs/ha-apps

#Step 2 — Configure Before First Start

Set at minimum before starting:

server_name: "your-domain.duckdns.org"
element_web_url: "https://your-domain.duckdns.org"
postgres_password: "strong_password_here"
enable_registration: false

server_name cannot be changed after first start. It becomes your permanent Matrix ID (@user:server_name).

#Step 3 — Start

First start takes 2–3 minutes. Element Web and Synapse Admin are downloaded at runtime.

#Step 4 — Create Admin User

docker exec -it addon_local_matrix_server \
  /opt/synapse/bin/register_new_matrix_user \
  -c /data/matrix/synapse/homeserver.yaml \
  --admin -u admin -p YourSecurePassword \
  http://localhost:8008

#Required

Option	Description
server_name	Your Matrix domain. No trailing slash. Cannot change after first start.
postgres_password	PostgreSQL password. Set before first start.

#General

Option	Default	Description
element_web_url	—	External HTTPS URL for Element Web.
element_call_url	—	External HTTPS URL for Element Call.
livekit_url	—	WebSocket URL for LiveKit SFU.
livekit_jwt_url	—	HTTPS URL for LiveKit JWT bridge.
ntfy_url	—	Optional external ntfy URL for UnifiedPush.
enable_registration	false	Allow public registration.
enable_federation	true	Connect to the Matrix federation.
max_upload_size_mb	50	Max media upload size in MB.
log_level	WARNING	DEBUG / INFO / WARNING / ERROR

Port	Service	Access
7080	Element Web	Via NPM → element.your-domain
8008	Synapse API	Via NPM → matrix.your-domain
8090	Synapse Admin UI	Via NPM → admin.your-domain
8448	Matrix Federation	Direct — port-forward required on router
7880	LiveKit SFU	Via NPM (WebSocket required)
8089	LiveKit JWT Bridge	Via NPM

See NPM_SETUP.md in the add-on repo for the complete Nginx Proxy Manager configuration.

#Access

External: https://admin.your-domain.duckdns.org
Local:    http://HA-IP:8090

Homeserver URL: https://matrix.your-domain.duckdns.org
Username:       admin

NPM Access List for admin.* must be set to Publicly Accessible — the auth comes from the Synapse Admin login itself, not NPM.

#Get Admin Token Manually

curl -s -X POST http://HA-IP:8008/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","user":"admin","password":"YourPassword"}' \
  | jq .access_token

Matrix + ntfy add-on = privacy-friendly Android push without Google Firebase.

Element Android
  → selects ntfy as UnifiedPush distributor
  → registers push gateway with Synapse:
      https://ntfy.your-domain/_matrix/push/v1/notify
  → Synapse sends pushes to ntfy
  → ntfy delivers to your device

#Setup

1. Set ntfy_url in the add-on config to your external ntfy URL.
2. Install ntfy from F-Droid (Play Store version has no UnifiedPush).
3. In Element Android: Settings → Notifications → UnifiedPush → select ntfy.

Synapse does not need the ntfy URL in its config — the client registers the gateway automatically.

/data/matrix/
├── postgresql/           # PostgreSQL database
├── synapse/
│   ├── homeserver.yaml   # Synapse config
│   ├── signing.key       # ⚠️ BACKUP — loss = loss of federation identity
│   └── media_store/      # Uploaded media
├── element-web/          # Element Web (persistent)
├── synapse-admin/        # Synapse Admin (persistent)
└── .webapps_downloaded   # Skip re-download marker

signing.key is critical. Keep it in a secure offline backup. Loss means your server loses its Matrix federation identity permanently.

#Force Web App Re-download

docker exec addon_local_matrix_server rm /data/matrix/.webapps_downloaded
# Then restart the add-on

# configuration.yaml
notify:
  - platform: matrix
    name: matrix_notify
    homeserver: https://matrix.your-domain.duckdns.org
    username: "@homeassistant:your-domain.duckdns.org"
    password: "ha_user_password"
    default_room: "#homeassistant:your-domain.duckdns.org"

See ha_matrix_integration.yaml in the add-on repo for automation examples.

Problem	Cause	Fix
Server name has invalid format	Trailing slash in server_name.	Remove the trailing slash.
Admin Panel "Something went wrong"	Stale browser cache.	F12 → Application → Clear Site Data.
Admin Panel 401	NPM Access List active.	Set Access List to "Publicly Accessible".
Element Web wrong server	Wrong config.json loaded.	Clear browser cache.
Web apps 0 files	Extraction failed on startup.	Delete .webapps_downloaded marker and restart.
Synapse token invalid	Add-on reinstalled, DB empty.	Re-create admin user.
Federation broken	Port 8448 not forwarded.	Router: 8448 → HA-IP:8448.

#Resources

# Test federation
https://federationtester.matrix.org/#your-domain.duckdns.org

# Resource usage (Pi 4, 8 GB RAM)
PostgreSQL:   ~100 MB   <1% CPU
Synapse:      ~300-500 MB   1-3% CPU
Element Web:  ~10 MB   <1% CPU
Total:        ~450-650 MB   ~3-5% CPU

Unofficial, community-maintained HA add-on. Synapse is AGPL-3.0. The add-on wrapper is MIT.