Deployment Overview of Element on Server¶

This document provides technical details regarding the deployment and configuration of the Element (Matrix Synapse) application stack. The deployment utilizes a containerized architecture to run the Matrix homeserver, its database, and the Element web client, managed via Docker Compose.

Prerequisites and Basic Requirements¶

To ensure successful deployment, the following environment requirements must be met:

Operating System: Ubuntu
Privileges: Root or sudo access is required for package installation and service management.
Dependencies: The system requires ca-certificates, curl, gnupg, and lsb-release.
Docker Engine: Docker CE, Docker Compose plugin, and containerd must be installed.

FQDN of the final panel on the hostkey.in domain¶

The application uses a dynamic subdomain based on the server ID for its Matrix federation and web interface.

Parameter	Value
Prefix	`element`
Domain	`hostkey.in`
Full template	`element{Server_ID_from_Invapi}.hostkey.in`

File and Directory Structure¶

The application data and configuration files are organized as follows:

/opt/matrix: Base directory for the Matrix stack.
/opt/matrix/files: Contains Synapse data, including homeserver.yaml, element-config.json, and media storage.
/opt/matrix/schemas: Directory for database schema files.
/root/nginx: Configuration directory for the Nginx reverse proxy.
/data/nginx/user_conf.d: Location of custom Nginx virtual host configurations.

Application installation process¶

The application is installed using a combination of system package management and Docker orchestration:

System Preparation: The system updates its package cache and installs necessary dependencies for repository management.
Docker Installation: If Docker is not present, the official Docker repository is added to the system, and docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin, and docker-compose-plugin are installed via apt.
Directory Setup: The application creates the necessary directory structure under /opt/matrix with appropriate ownership (UID 991 for Synapse data).
Configuration Deployment: Configuration files (homeserver.yaml, element-config.json) and the Docker Compose file are generated in their respective directories.
Container Orchestration: The application stack is deployed using docker compose.

Access Rights and Security¶

Firewall/Ports:
Port 8008 is used for Matrix client-server federation and internal communication.
Port 443 (HTTPS) is managed by the Nginx proxy for external access.
Port 8448 is reserved for Matrix Federation (SSL).
Permissions:
Data directories are owned by user 991:991 to ensure compatibility with the Synapse container.
Configuration files in /opt/matrix/files are secured with specific ownership and permissions.

Databases¶

The application uses a PostgreSQL database for storing Matrix events, users, and metadata.

Component	Details
Database Engine	`postgres:15-alpine`
Database Name	`synapse`
Connection Host	`db` (via Docker network)
Storage Location	Managed via Docker volume `postgres-data`

Docker Containers and Their Deployment¶

The deployment consists of several containers working in a coordinated stack.

Matrix Application Stack¶

These services are managed within /opt/matrix/docker-compose.yml.

PostgreSQL Container

Image: postgres:15-alpine
Restart Policy: unless-stopped
Environment Variables:
POSTGRES_USER: synapse
POSTGRES_PASSWORD: synapse
POSTGRES_INITDB_ARGS: --encoding=UTF-8 --lc-collate=C --lc-ctype=C
Volumes: postgres-data:/var/lib/postgresql/data

Synapse Container (Matrix Homeserver)

Image: matrixdotorg/synapse:latest
Restart Policy: unless-stopped
Environment Variables:
SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
Volumes: ./files:/data
Ports: 8008:8008

Element Web Container

Image: vectorim/element-web:latest
Restart Policy: unless-stopped
Volumes: ./element-config.json:/app/config.json
Ports: 127.0.0.1:8080:80

Proxy Stack¶

These services are managed within /root/nginx/compose.yml.

Nginx Certbot Container

Image: jonasal/nginx-certbot:latest
Restart Policy: unless-stopped
Network Mode: host
Environment Variables:
CERTBOT_EMAIL: [email protected]
Volumes:
nginx_secrets:/etc/letsencrypt
/data/nginx/user_conf.d:/etc/nginx/user_conf.d
/usr/share/element-web:/usr/share/element-web:ro

Application Update Instructions¶

To update the main application components, execute the following commands in the respective configuration directories:

For the Matrix Stack (Synapse, DB, Element):

cd /opt/matrix
docker compose pull && docker compose up -d

For the Nginx Proxy:

cd /root/nginx
docker compose pull && docker compose up -d

Location of configuration files and data¶

Synapse Configuration: /opt/matrix/files/homeserver.yaml
Element Web Configuration: /opt/matrix/files/element-config.json
Nginx Virtual Host Configs: /data/nginx/user_conf.d/
PostgreSQL Data Volume: Managed by Docker (internal to Docker volumes)

Available ports for connection¶

Port	Service	Access Type
`443`	HTTPS Web Interface	Public
`8448`	Matrix Federation	Public
`8008`	Synapse API	Internal/Local
`8080`	Element Local Proxy	Localhost only

Starting and Stopping the application¶

Starting the Matrix Stack:

cd /opt/matrix
docker compose up -d

Stopping the Matrix Stack:

cd /opt/matrix
docker compose down

Proxy Servers¶

The deployment utilizes an Nginx proxy container (jonasal/nginx-certbot) to handle SSL termination and routing. It uses Certbot for automated SSL certificate management via a shared volume nginx_secrets. The proxy routes traffic based on the following logic:

Traffic to /_matrix or /_synapse/client is proxied to the Synapse container on port 8008.
All other traffic is proxied to the Element Web interface on port 8080.