Deployment Overview of Element on Server¶

Prerequisites and Basic Requirements¶

The deployment requires a Linux-based server running Ubuntu. The following components and privileges are necessary:

• Operating System: Ubuntu (specific version codename detected dynamically during installation).

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

• Domain: The server must be accessible via the hostkey.in domain.

• Ports: Ports 80, 443, and 8448 must be open for web traffic and SSL termination. Port 8008 is used internally for the Synapse API, and port 8080 is used internally for the Element web client.

FQDN of the Final Panel¶

The fully qualified domain name (FQDN) for the application follows the format:

element<Server ID>.hostkey.in

Replace <Server ID> with the specific identifier assigned to the server instance. The application is accessible via HTTPS on port 443.

File and Directory Structure¶

The application files, configurations, and data are organized in the following locations:

• Base Directory: /opt/matrix

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

• Synapse Schemas: /opt/matrix/schemas

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

• Nginx Secrets and Certificates: /etc/letsencrypt

• Nginx Compose Configuration: /root/nginx

Application Installation Process¶

The application is deployed using Docker Compose. The installation process involves the following steps:

1. Docker Installation: If Docker is not present, the system installs docker-ce, docker-ce-cli, containerd.io, and the docker-compose-plugin.

2. Directory Creation: The base directory /opt/matrix and subdirectories for files and schemas are created with appropriate ownership.

3. Configuration Deployment:

   • The docker-compose.yml file is generated in /opt/matrix.

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

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

4. Container Deployment: Docker images for PostgreSQL, Synapse, and Element Web are pulled and started using docker compose.

5. Health Check: The deployment waits for the Synapse health endpoint at http://127.0.0.1:8008/health to return a 200 status code before completing.

Docker Containers and Their Deployment¶

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

• Database (db):

• Image: postgres:15-alpine

• Purpose: Stores Synapse data.

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

• Synapse (synapse):

• Image: matrixdotorg/synapse:latest

• Purpose: The Matrix homeserver backend.

• Volume: Host directory /opt/matrix/files mounted to /data.

• Port: Exposes port 8008 internally.

• Element (element):

• Image: vectorim/element-web:latest

• Purpose: The web client interface.

• Volume: Host file /opt/matrix/element-config.json mounted to /app/config.json.

• Port: Exposes port 80 internally, bound to 127.0.0.1:8080.

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

Proxy Servers¶

Nginx is used as a reverse proxy and SSL terminator. It is deployed via a separate Docker Compose stack located in /root/nginx.

• Image: jonasal/nginx-certbot:latest

• Function: Handles SSL certificates via Certbot and routes traffic to the internal services.

• Configuration:

• The Nginx configuration for the Matrix domain is stored at /data/nginx/user_conf.d/<matrix_domain>.conf.

• SSL certificates are stored in /etc/letsencrypt/live/<matrix_domain>.

• Routing:

• Requests to /_matrix and /_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).

Databases¶

The application uses PostgreSQL for data storage.

• Database Name: synapse

• User: synapse

• Password: synapse

• Host: db (internal Docker network hostname)

• Storage: Data is persisted in the Docker volume postgres-data.

• Connection Settings:

• Driver: psycopg2

• Encoding: UTF-8

• Collation: C

• Ctype: C

Permission Settings¶

File and directory permissions are set as follows to ensure security and proper operation:

• /opt/matrix: Owned by root:root with mode 0755.

• /opt/matrix/files: Owned by 991:991 (Synapse user) with mode 0755.

• /opt/matrix/schemas: Owned by root:root with mode 0755.

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

• /opt/matrix/files/homeserver.yaml: Owned by 991:991 with mode 0644.

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

• /root/nginx: Owned by root:root with mode 0755.

• /data/nginx/user_conf.d: Owned by root:root with mode 0644.

Location of Configuration Files and Data¶

Key configuration files are located in the following paths:

Available Ports for Connection¶

The following ports are utilized by the deployment:

• 443: HTTPS traffic for the web interface and API (via Nginx).

• 8448: Alternative HTTPS port (via Nginx).

• 8008: Internal Synapse API port (bound to localhost).

• 8080: Internal Element Web port (bound to localhost).

Starting, Stopping, and Updating¶

Service management is handled via Docker Compose commands executed in the respective project directories.

• Start/Restart Matrix Stack:

  cd /opt/matrix
  docker compose up -d
  

• Stop Matrix Stack:

  cd /opt/matrix
  docker compose down
  

• Update Matrix Stack:

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

• Start/Restart Nginx Stack:

  cd /root/nginx
  docker compose up -d
  

• Stop Nginx Stack:

  cd /root/nginx
  docker compose down