Deployment Overview of Element on Server¶

Prerequisites and Basic Requirements¶

The deployment requires a Linux server running Ubuntu with root privileges. The system must have internet access to download Docker images and SSL certificates. The following components are required:

• Operating System: Ubuntu (specific version codename is detected dynamically during installation).
• Privileges: Root access or sudo privileges are required to install Docker and manage system services.
• Domain: A valid domain name (matrix_domain) must be configured and pointed to the server's IP address.
• Ports:
• Port 8008: Internal Synapse API.
• Port 8080: Internal Element Web interface.
• Port 443: HTTPS traffic for the public interface.
• Port 8448: Alternative HTTPS port for Matrix federation.

File and Directory Structure¶

The application utilizes a specific directory structure to separate configuration, data, and certificates. The base directory for the Matrix stack is defined as matrix_base_dir (typically /data/matrix or similar, depending on the variable assignment).

• Base Directory: {{ matrix_base_dir }}
• Synapse Data: {{ matrix_base_dir }}/files
  • Stores media, signing keys, and the Synapse configuration file (homeserver.yaml).
  • Owned by user ID 991 and group ID 991.
• Database Schemas: {{ matrix_base_dir }}/schemas
  • Stores PostgreSQL schema definitions.
• Element Configuration: {{ matrix_base_dir }}/element-config.json
  • Contains the JSON configuration for the Element web client.

• Docker Compose: {{ matrix_base_dir }}/docker-compose.yml

  • Defines the services for Synapse, Element, and the database.

• Nginx and SSL Directory: /root/nginx

• Compose File: /root/nginx/compose.yml
  • Defines the Nginx and Certbot stack.
• User Configuration: /data/nginx/user_conf.d/
  • Contains the specific server block configuration for the Matrix domain ({{ matrix_domain }}.conf).
• SSL Secrets: /etc/letsencrypt
  • Managed by the nginx_secrets volume for storing Let's Encrypt certificates.

Application Installation Process¶

The deployment is performed using Docker Compose to orchestrate the Matrix homeserver (Synapse), the Element web client, and the PostgreSQL database.

1. Docker Installation: If Docker is not present, the system installs the following packages:
2. docker-ce
3. docker-ce-cli
4. containerd.io
5. docker-buildx-plugin

6. docker-compose-plugin

7. Docker Daemon Configuration: The Docker daemon is configured with an empty JSON object in /etc/docker/daemon.json to ensure default settings are applied.

8. Service Deployment: The application stack is deployed using the docker-compose.yml file located in the base directory. The process involves:

9. Pulling the latest images for postgres:15-alpine, matrixdotorg/synapse:latest, and vectorim/element-web:latest.
10. Creating the necessary volumes and networks.

11. Starting the containers in the order defined by dependencies (Database first, then Synapse, then Element).

12. Health Check: After startup, the system verifies the Synapse service by checking the health endpoint at http://127.0.0.1:8008/health until it returns a 200 status code.

Docker Containers and Their Deployment¶

The application consists of three primary containers managed via Docker Compose:

• Database (db):
• Image: postgres:15-alpine
• Environment Variables:
  • POSTGRES_USER: synapse
  • POSTGRES_PASSWORD: synapse
  • POSTGRES_INITDB_ARGS: --encoding=UTF-8 --lc-collate=C --lc-ctype=C

• Volume: postgres-data mounted to /var/lib/postgresql/data.

• Synapse (synapse):

• Image: matrixdotorg/synapse:latest
• Configuration Path: /data/homeserver.yaml
• Volume: ./files mounted to /data.
• Port Mapping: 8008:8008 (Internal only).

• Dependencies: Waits for the db container.

• Element (element):

• Image: vectorim/element-web:latest
• Configuration: ./element-config.json mounted to /app/config.json.
• Port Mapping: 127.0.0.1:8080:80 (Bound to localhost only).

Proxy Servers¶

Access to the application is provided through an Nginx reverse proxy with SSL termination managed by Certbot.

• Nginx Stack:
• Image: jonasal/nginx-certbot:latest
• Deployment: Managed via /root/nginx/compose.yml.
• Network Mode: host.
• Environment:
  • CERTBOT_EMAIL: [email protected]
  • Configuration loaded from /data/nginx/nginx-certbot.env.

• Volumes:

  • nginx_secrets mounted to /etc/letsencrypt.
  • /data/nginx/user_conf.d mounted to /etc/nginx/user_conf.d.
  • /usr/share/element-web mounted read-only to /usr/share/element-web.

• Server Configuration: The Nginx configuration file ({{ matrix_domain }}.conf) listens on ports 443 and 8448 for SSL traffic.

• SSL Certificates:
  • Certificate: /etc/letsencrypt/live/{{ matrix_domain }}/fullchain.pem
  • Key: /etc/letsencrypt/live/{{ matrix_domain }}/privkey.pem
  • Chain: /etc/letsencrypt/live/{{ matrix_domain }}/chain.pem
• Routing:
  • Requests to /_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).
• Headers:
  • Host, X-Forwarded-For, and X-Forwarded-Proto are set to ensure proper request handling.
  • client_max_body_size is set to 50M for Matrix API requests.

Databases¶

The application uses PostgreSQL version 15 for data storage.

• Connection Method: Synapse connects to the database via the internal Docker network using the hostname db.
• Database Name: synapse
• User: synapse
• Password: synapse
• Storage: Data is persisted in the Docker volume postgres-data, which maps to the host filesystem.
• Connection Pooling:
• Minimum connections (cp_min): 5
• Maximum connections (cp_max): 10

Permission Settings¶

File and directory permissions are strictly defined to ensure security and proper operation of the containers.

• Base Directory: {{ matrix_base_dir }}
• Owner: root
• Group: root

• Mode: 0755

• Synapse Data Directory: {{ matrix_base_dir }}/files

• Owner: 991 (Synapse user)
• Group: 991

• Mode: 0755 (Recursive)

• Schema Directory: {{ matrix_base_dir }}/schemas

• Owner: root
• Group: root

• Mode: 0755

• Configuration Files:

• homeserver.yaml: Owned by 991:991, Mode 0644.
• element-config.json: Owned by root:root, Mode 0644.

• docker-compose.yml: Owned by root:root, Mode 0644.

• Nginx Configuration:

• /root/nginx: Owned by root:root, Mode 0755.
• /root/nginx/compose.yml: Owned by root:root, Mode 0644.
• /data/nginx/user_conf.d/{{ matrix_domain }}.conf: Owned by root:root, Mode 0644.

Starting, Stopping, and Updating¶

The services are managed using Docker Compose commands executed from the respective project directories.

• Starting the Matrix Stack: Execute the following command from the base directory:

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

• Starting the Nginx/Certbot Stack: Execute the following command from the /root/nginx directory:

  docker compose -f compose.yml up -d
  

• Updating Images: To pull the latest versions of the containers without recreating them immediately:

  docker compose -f docker-compose.yml pull
  

  To recreate containers with the new images:

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

• Stopping Services: To stop the Matrix stack:

  docker compose -f docker-compose.yml down
  

  To stop the Nginx stack:

  docker compose -f compose.yml down
  

• Cleaning Docker Resources: The deployment process includes commands to clean the builder cache and system resources:

  docker builder prune -f
  docker system prune -f