mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Add Synapse + Element Web to docker-compose for dev environment #384

New Issue
Closed
opened 2026-02-15 07:01:55 +00:00 by jason.woltje · 1 comment
jason.woltje commented 2026-02-15 07:01:55 +00:00
Owner
Copy Link

Summary

Add Matrix homeserver (Synapse) and Element Web client to the development docker-compose stack so the Matrix bridge can be tested locally without external infrastructure.

IMPORTANT: Dev only. In production, Synapse is external shared infrastructure (like Authentik). The Stack connects via MATRIX_HOMESERVER_URL env var pointing to wherever Synapse lives. Bundling Synapse in the production Stack would couple it unnecessarily — Synapse serves multiple applications (comms, GoToSocial bridges, other projects).

Architecture Pattern

Service Dev Compose Production
PostgreSQL Bundled Bundled (data layer)
Valkey Bundled Bundled (internal queue)
Authentik Not included External (OIDC env vars)
Synapse Bundled (dev only) External (Matrix env vars)
Element Web Bundled (dev only) External (user's client)

Implementation

Option 1: Separate dev compose file (recommended)

Create docker-compose.matrix.yml as an optional overlay:

# Dev with Matrix:
docker compose -f docker-compose.yml -f docker-compose.matrix.yml up

# Dev without Matrix (default):
docker compose up

This keeps the base compose clean and makes Matrix opt-in for developers.

Option 2: Conditional in main compose

Add Synapse + Element to main docker-compose.yml with profiles:

  synapse:
    image: matrixdotorg/synapse:latest
    profiles: ["matrix"]
    ...

  element-web:
    image: vectorim/element-web:latest
    profiles: ["matrix"]
    ...

docker compose --profile matrix up

Synapse Configuration (dev)

  synapse:
    image: matrixdotorg/synapse:latest
    container_name: mosaic-synapse
    environment:
      SYNAPSE_SERVER_NAME: matrix.localhost
      SYNAPSE_REPORT_STATS: "no"
    volumes:
      - synapse-data:/data
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - internal

Element Web Configuration (dev)

  element-web:
    image: vectorim/element-web:latest
    container_name: mosaic-element
    volumes:
      - ./config/element-config.json:/app/config.json:ro
    ports:
      - "8501:80"
    depends_on:
      - synapse
    networks:
      - internal

Synapse Database

  • Use the same PostgreSQL instance (separate database: synapse)
  • Generate homeserver.yaml via synapse generate on first run
  • Registration disabled (bot account created via CLI)
  • Federation disabled for dev (single-server)

Element Configuration

Create config/element-config.json pointing to local Synapse.

Bot Account Setup

Script or make target to create the Mosaic bot account:

docker exec mosaic-synapse register_new_matrix_user \
  -u mosaic-bot -p <password> -a -c /data/homeserver.yaml \
  http://localhost:8008

Environment Variables

Add to .env.example:

# Matrix Bridge (optional — connects to external Synapse in production)
# For dev: use docker-compose.matrix.yml overlay
MATRIX_HOMESERVER_URL=http://synapse:8008
MATRIX_ACCESS_TOKEN=<generated after bot registration>
MATRIX_BOT_USER_ID=@mosaic-bot:matrix.localhost
MATRIX_CONTROL_ROOM_ID=

Makefile targets

matrix-up:     ## Start dev environment with Matrix
	docker compose -f docker-compose.yml -f docker-compose.matrix.yml up -d

matrix-setup:  ## Create bot account and generate access token
	@echo "Creating Mosaic bot account..."
	docker exec mosaic-synapse register_new_matrix_user ...

Acceptance Criteria

  • Synapse + Element available via optional compose overlay (NOT in base compose)
  • make matrix-up starts full stack with Matrix
  • Synapse uses shared PostgreSQL (separate database)
  • Element Web accessible at localhost:8501
  • Bot account creation scripted via make target
  • Matrix env vars in .env.example with clear comments
  • Dev setup does not require external Matrix server
  • Base docker compose up still works without Matrix (no regression)
  • README documents both dev (bundled) and production (external) patterns

Refs

## Summary Add Matrix homeserver (Synapse) and Element Web client to the **development** docker-compose stack so the Matrix bridge can be tested locally without external infrastructure. **IMPORTANT: Dev only.** In production, Synapse is external shared infrastructure (like Authentik). The Stack connects via `MATRIX_HOMESERVER_URL` env var pointing to wherever Synapse lives. Bundling Synapse in the production Stack would couple it unnecessarily — Synapse serves multiple applications (comms, GoToSocial bridges, other projects). ## Architecture Pattern | Service | Dev Compose | Production | |---------|-------------|------------| | PostgreSQL | Bundled | Bundled (data layer) | | Valkey | Bundled | Bundled (internal queue) | | Authentik | Not included | External (OIDC env vars) | | **Synapse** | **Bundled (dev only)** | **External (Matrix env vars)** | | **Element Web** | **Bundled (dev only)** | **External (user's client)** | ## Implementation ### Option 1: Separate dev compose file (recommended) Create `docker-compose.matrix.yml` as an optional overlay: ```bash # Dev with Matrix: docker compose -f docker-compose.yml -f docker-compose.matrix.yml up # Dev without Matrix (default): docker compose up ``` This keeps the base compose clean and makes Matrix opt-in for developers. ### Option 2: Conditional in main compose Add Synapse + Element to main docker-compose.yml with profiles: ```yaml synapse: image: matrixdotorg/synapse:latest profiles: ["matrix"] ... element-web: image: vectorim/element-web:latest profiles: ["matrix"] ... ``` ```bash docker compose --profile matrix up ``` ### Synapse Configuration (dev) ```yaml synapse: image: matrixdotorg/synapse:latest container_name: mosaic-synapse environment: SYNAPSE_SERVER_NAME: matrix.localhost SYNAPSE_REPORT_STATS: "no" volumes: - synapse-data:/data depends_on: postgres: condition: service_healthy networks: - internal ``` ### Element Web Configuration (dev) ```yaml element-web: image: vectorim/element-web:latest container_name: mosaic-element volumes: - ./config/element-config.json:/app/config.json:ro ports: - "8501:80" depends_on: - synapse networks: - internal ``` ### Synapse Database - Use the same PostgreSQL instance (separate database: `synapse`) - Generate homeserver.yaml via `synapse generate` on first run - Registration disabled (bot account created via CLI) - Federation disabled for dev (single-server) ### Element Configuration Create `config/element-config.json` pointing to local Synapse. ### Bot Account Setup Script or make target to create the Mosaic bot account: ```bash docker exec mosaic-synapse register_new_matrix_user \ -u mosaic-bot -p <password> -a -c /data/homeserver.yaml \ http://localhost:8008 ``` ### Environment Variables Add to `.env.example`: ``` # Matrix Bridge (optional — connects to external Synapse in production) # For dev: use docker-compose.matrix.yml overlay MATRIX_HOMESERVER_URL=http://synapse:8008 MATRIX_ACCESS_TOKEN=<generated after bot registration> MATRIX_BOT_USER_ID=@mosaic-bot:matrix.localhost MATRIX_CONTROL_ROOM_ID= ``` ### Makefile targets ```makefile matrix-up: ## Start dev environment with Matrix docker compose -f docker-compose.yml -f docker-compose.matrix.yml up -d matrix-setup: ## Create bot account and generate access token @echo "Creating Mosaic bot account..." docker exec mosaic-synapse register_new_matrix_user ... ``` ## Acceptance Criteria - [ ] Synapse + Element available via optional compose overlay (NOT in base compose) - [ ] `make matrix-up` starts full stack with Matrix - [ ] Synapse uses shared PostgreSQL (separate database) - [ ] Element Web accessible at localhost:8501 - [ ] Bot account creation scripted via make target - [ ] Matrix env vars in .env.example with clear comments - [ ] Dev setup does not require external Matrix server - [ ] Base `docker compose up` still works without Matrix (no regression) - [ ] README documents both dev (bundled) and production (external) patterns ## Refs - Current docker-compose: `docker-compose.yml` - Synapse Docker docs: https://element-hq.github.io/synapse/latest/setup/installation.html - Pattern precedent: Authentik is external in production, not bundled - EPIC: #377
jason.woltje added the devops label 2026-02-15 07:01:55 +00:00
jason.woltje added this to the M12-MatrixBridge (0.0.12) milestone 2026-02-15 07:02:56 +00:00
jason.woltje commented 2026-02-15 08:30:15 +00:00
Author
Owner
Copy Link

Completed in commit 4a5cb64 on branch feature/m12-matrix-bridge.

  • Added docker-compose.matrix.yml overlay with Synapse + Element Web
  • Synapse homeserver config for local dev
  • Element Web config for local dev
  • Bot setup script for creating bot user
Completed in commit 4a5cb64 on branch feature/m12-matrix-bridge. - Added docker-compose.matrix.yml overlay with Synapse + Element Web - Synapse homeserver config for local dev - Element Web config for local dev - Bot setup script for creating bot user
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
ai
AI/LLM integration
 api
Backend/API work
 api
auth
Authentication
 database
database
Database/schema work
 devops
Docker/deployment
 docs
Documentation
 frontend
graph
knowledge-module
migration
Data migration
 orchestrator
Orchestrator service (apps/orchestrator/)
 p0
Critical priority
 p1
High priority
 p2
Medium priority
 p3
Low priority
 performance
Performance work
 phase-1
phase-2
phase-3
phase-4
phase-5
plugin
MoltBot plugin work
 search
security
Security-related
 setup
Initial setup
 testing
Testing/QA
 web
Frontend work
No Label devops
Milestone
No items
No Milestone M12-MatrixBridge (0.0.12)
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaic/stack#384
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?