🌐 Element Stack

Complete Docker-based Element Web deployment with SSL certificate management and identity integration for production and development environments.

🧩 Components

🔐 SSL Automation

🔒 Let's Encrypt Manager

Automatic SSL certificate management from Let's Encrypt for production deployments. Provides seamless HTTPS integration for Docker containers using nginx-proxy and acme-companion. Learn more about Let's Encrypt Manager configuration.

🏠 Step CA Manager

Local domain stack with trusted self-signed certificates for virtual network deployments. Includes private CA management and local DNS resolution for development environments. Learn more about Step CA Manager configuration.

🔑 Identity Management

🔐 Keycloak

Enterprise-grade identity and access management solution. Provides authentication, authorization, and user management for secure application access. Learn more about Keycloak configuration.

For Element integration, see: Keycloak OIDC Integration

🔐 Kanidm

Modern identity and access management server with comprehensive authentication capabilities. Provides secure identity management with modular configuration system and multiple deployment modes. Learn more about Kanidm configuration.

💬 Matrix Services

🏠 Synapse

Matrix homeserver implementation providing the backend infrastructure for Element Web client. Includes PostgreSQL backend, OIDC integration, and multiple deployment configurations. Learn more about Matrix Synapse configuration.

🌐 Services

🌐 Element Web

Modular Docker Compose configuration system for Element Web client with support for multiple environments and OIDC integration capabilities. Provides complete Matrix web client deployment with customizable configurations for development and production. Learn more about Element Web configuration.

🚀 Quick Start

Each component has its own README with detailed setup instructions. Choose the certificate management solution and identity provider that fits your deployment scenario.

Basic Setup

1. Choose SSL Management:

   • Production: Use Let's Encrypt Manager
   • Development: Use Step CA Manager

2. Configure Identity (Optional):

   • Enterprise: Use Keycloak
   • Modern: Use Kanidm

3. Deploy Matrix Backend:

   • Set up Synapse homeserver

4. Deploy Element Web:

   • Configure Element client to connect to your Matrix homeserver

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Element Web   │────│  Matrix Synapse │────│   PostgreSQL    │
│   (Frontend)    │    │   (Homeserver)  │    │   (Database)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │
         │                       │
┌─────────────────┐    ┌─────────────────┐
│ Identity Server │    │  SSL Manager    │
│ (Keycloak/      │    │ (Let's Encrypt/ │
│  Kanidm)        │    │  Step CA)       │
└─────────────────┘    └─────────────────┘

📋 Requirements

• Docker & Docker Compose
• Domain name (for production deployments)
• Email address (for Let's Encrypt)
• yq tool for configuration building

🔧 Configuration

All services use modular Docker Compose configurations with:

• Base components: Core service definitions
• Environment components: Development, production, SSL configurations
• Extension components: OIDC, identity integration, additional features
• Build system: Automatic generation of deployment combinations

🌍 Deployment Scenarios

Development Environment

# Element with port forwarding
cd src/element/build/forwarding/base/
docker-compose up -d

# Synapse with port forwarding
cd src/matrix/synapse/build/forwarding/base/
docker-compose up -d

Production Environment

# Element with Let's Encrypt SSL
cd src/element/build/letsencrypt/base/
docker-compose up -d

# Synapse with Let's Encrypt SSL and OIDC
cd src/matrix/synapse/build/letsencrypt/oidc/
docker-compose up -d

DevContainer Environment

# Element in DevContainer
cd src/element/build/devcontainer/base/
docker-compose up -d

# Synapse in DevContainer with OIDC
cd src/matrix/synapse/build/devcontainer/oidc/
docker-compose up -d

🔐 Security Features

• SSL/TLS Encryption: Automatic certificate management
• Identity Integration: OIDC/SAML authentication
• Network Isolation: Docker network segmentation
• Secret Management: Environment-based configuration
• Access Control: Role-based permissions

🆘 Troubleshooting

Common Issues

• SSL Certificate Issues: Check Let's Encrypt/Step CA configuration
• Identity Integration: Verify OIDC provider settings
• Network Connectivity: Ensure proper Docker network configuration
• Database Connection: Check PostgreSQL connectivity for Synapse

Logs

# Element logs
docker logs element

# Synapse logs
docker logs matrix

# Identity provider logs
docker logs keycloak  # or kanidm

📚 Documentation

• Element Web Configuration
• Matrix Synapse Setup
• SSL Automation
• Identity Management

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test configurations
5. Submit a pull request

📄 License

This project is dual-licensed under:

• Apache License 2.0
• MIT License

🔗 Related Projects

• Matrix.org - Open network for secure, decentralized communication
• Element.io - Secure collaboration and messaging
• Synapse - Matrix homeserver implementation
• Keycloak - Identity and access management
• Kanidm - Modern identity management