Deployment Overview of Element on Server¶

Prerequisites and Basic Requirements¶

The deployment requires a Linux-based server environment with the following specifications and privileges:

• Operating System: Ubuntu (verified via ansible_distribution and lsb codename checks).

• Privileges: Root access or sudo privileges are required to install system packages, configure the firewall, and manage Docker services.

• Docker Engine: The docker-ce package and associated CLI tools must be installed.

• Network Access: The server must have outbound internet access to pull Docker images and fetch SSL certificates.

FQDN of the Final Panel¶

The application is accessible via a fully qualified domain name (FQDN) constructed using the prefix element and the server identifier on the hostkey.in domain. The format is:

element<Server ID>.hostkey.in:443

Note that the standard HTTPS port (443) is used for the final access, while the proxy also listens on port 8448 for internal or specific routing configurations.

File and Directory Structure¶

The application utilizes a specific directory structure to separate configuration, data, and runtime files. The primary base directory for the Matrix stack is located at:

• Base Directory: /opt/matrix

• Synapse Data and Media: /opt/matrix/files

• Database Schemas: /opt/matrix/schemas

• Element Configuration: /opt/matrix/element-config.json

• Docker Compose Definition: /opt/matrix/docker-compose.yml

• Synapse Configuration: /opt/matrix/files/homeserver.yaml

The proxy and SSL certificate components utilize the following paths:

• Nginx Configuration Directory: /root/nginx

• Compose Definition: /root/nginx/compose.yml

• Nginx User Configuration: /data/nginx/user_conf.d

• SSL Certificates: /etc/letsencrypt/live/<domain>

• Nginx Secrets Volume: Managed externally as nginx_secrets.

Application Installation Process¶

The application is deployed using Docker containers orchestrated via Docker Compose. The installation involves the following stages:

1. Docker Installation: If not present, the Docker Engine (docker-ce, docker-ce-cli, containerd.io) and Docker Compose plugin are installed via the official Docker repository.

2. Directory Initialization: The script ensures the existence of /opt/matrix and its subdirectories (files, schemas) with appropriate ownership.

3. Configuration Deployment:

   • The Synapse configuration (homeserver.yaml) is placed in /opt/matrix/files.

   • The Element client configuration (element-config.json) is placed in /opt/matrix.

   • The Docker Compose file is generated at /opt/matrix/docker-compose.yml.

4. Container Deployment:

   • Images are pulled from the registry (matrixdotorg/synapse, vectorim/element-web, postgres).

   • The stack is started using Docker Compose.

   • A health check is performed against the Synapse endpoint (http://127.0.0.1:8008/health) to ensure the service is ready.

Docker Containers and Their Deployment¶

The application stack consists of three primary containers defined in the docker-compose.yml file located in /opt/matrix.

The deployment utilizes the following commands to manage the stack:

• Pull Images: docker compose pull --project-directory /opt/matrix

• Start Stack: docker compose up -d --project-directory /opt/matrix

The element container runs on port 80 and is exposed only to localhost (127.0.0.1:8080), relying on the Nginx proxy for external access. The synapse container exposes port 8008 to localhost.

Proxy Servers¶

Traffic to the application is handled by a separate Nginx stack running in a Docker container with network_mode: host. This stack uses jonasal/nginx-certbot to manage SSL certificates and routing.

Nginx Configuration¶

The proxy configuration is stored in /data/nginx/user_conf.d/element<Server ID>.hostkey.in.conf. The configuration includes:

• Server Name: Matches the FQDN element<Server ID>.hostkey.in.

• SSL Certificates: Managed by Certbot, stored in /etc/letsencrypt/live/.

• Routing Rules:

• Requests matching /_matrix or /_synapse/client are proxied to http://127.0.0.1:8008 (Synapse).

• All other requests are proxied to http://127.0.0.1:8080 (Element Web).

Ports¶

• Standard HTTPS: Port 443 (IPv4 and IPv6).

• Alternate HTTPS: Port 8448 (IPv4 and IPv6).

Databases¶

The application uses PostgreSQL version 15 (Alpine variant) for data persistence.

• Connection Method: Internal Docker network connection; Synapse connects to the database using the hostname db.

• Storage Location: Data is persisted in a named Docker volume postgres-data, which maps to /var/lib/postgresql/data inside the container.

• Database Settings:

• Database Name: synapse

• Username: synapse

• Password: synapse

• Encoding: UTF-8

• Locale: C

Permission Settings¶

File and directory permissions are strictly defined to ensure the security and proper functioning of the services:

• Base Directories: /opt/matrix, /opt/matrix/schemas are owned by root:root with mode 0755.

• Synapse Data Directory: /opt/matrix/files is owned by user/group 991:991 with mode 0755. This corresponds to the UID/GID used by the Synapse container.

• Configuration Files:

• homeserver.yaml: Owned by 991:991 with mode 0644.

• element-config.json: Owned by root:root with mode 0644.

• docker-compose.yml: Owned by root:root with mode 0644.

• Nginx Directories: /root/nginx and /data/nginx/user_conf.d are owned by root:root with mode 0755.

Location of Configuration Files and Data¶

Key configuration files are located in the following paths:

• Synapse Configuration: /opt/matrix/files/homeserver.yaml

• Defines server name, listeners (port 8008), database connection, and registration settings.

• Registration is enabled without verification in this configuration.

• Element Client Configuration: /opt/matrix/element-config.json

• Sets the default homeserver base URL, branding, and integration endpoints.

• Nginx Proxy Configuration: /data/nginx/user_conf.d/element<Server ID>.hostkey.in.conf

• Defines SSL parameters and reverse proxy rules.

• Docker Compose Definitions:

• Matrix Stack: /opt/matrix/docker-compose.yml

• Proxy Stack: /root/nginx/compose.yml

Available Ports for Connection¶

The following ports are utilized for external and internal communication:

Starting, Stopping, and Updating¶

The Matrix stack and the Proxy stack are managed via Docker Compose commands.

Matrix Stack¶

Located in /opt/matrix:

• Start:

  docker compose -f docker-compose.yml up -d
  

• Stop:

  docker compose -f docker-compose.yml down
  

• Update:

  docker compose -f docker-compose.yml pull
  docker compose -f docker-compose.yml up -d
  

Proxy Stack¶

Located in /root/nginx:

• Start:

  docker compose -f compose.yml up -d
  

• Stop:

  docker compose -f compose.yml down
  

Service Health Check¶

After starting the Matrix stack, verify the health of the Synapse service by checking the endpoint:

curl http://127.0.0.1:8008/health