Deployment Overview of Element on Server¶
Prerequisites and Basic Requirements¶
To successfully deploy the application, ensure the following requirements are met:
-
Operating System: Ubuntu (recommended).
-
Privileges: Root or sudo access is required for package installation and service management.
-
Domain: A valid FQDN must be configured to handle SSL termination via Certbot.
-
Ports: The following ports must be open on the host firewall:
-
80/tcp: For HTTP (Certbot validation). -
443/tcp: For HTTPS traffic. -
8448/tcp: For Matrix federation.
FQDN of the final panel on the hostkey.in domain¶
The application uses a specific domain template for its matrix communication 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 the Synapse configuration (homeserver.yaml) and media storage. -
/opt/matrix/schemas: Directory for database schemas. -
/root/nginx: Configuration files for the Nginx reverse proxy. -
/data/nginx/user_conf.d/: Custom Nginx virtual host configurations.
Application installation process¶
The application is deployed using a combination of system package management and Docker Compose. The process follows these steps:
-
System Preparation: The system updates the package cache and installs necessary dependencies such as
ca-certificates,curl,gnupg, andlsb-release. -
Docker Installation: If Docker is not present, the installer adds the official Docker GPG key and repository, then installs
docker-ce,docker-ce-cli,containerd.io,docker-buildx-plugin, anddocker-compose-plugin. -
Directory Setup: The installation creates the necessary directory structure in
/opt/matrixwith appropriate ownership for the Synapse user (UID 991). -
Configuration Deployment: Configuration files including
homeserver.yamlandelement-config.jsonare generated and placed in their respective directories. -
Container Orchestration: The application uses Docker Compose to pull images and start the service stack, ensuring all dependencies (like the database) are running before finalizing the setup.
Access Rights and Security¶
-
Firewall: Only necessary ports (
80,443,8448) should be exposed to the public internet. -
User Permissions:
-
Files in
/opt/matrix/filesare owned by user991. -
Nginx configuration files are managed under
/root/nginxand/data/nginx/user_conf.d/. -
Docker Security: The Docker daemon is configured via
/etc/docker/daemon.json.
Databases¶
The application utilizes a PostgreSQL database for storing Matrix data.
| Component | Details |
|---|---|
| Database Engine | postgres:15-alpine |
| User | synapse |
| Database Name | synapse |
| Storage Location | Docker volume named postgres-data |
Docker Containers and Their Deployment¶
The deployment consists of several containers managed via Docker Compose.
Matrix Stack (Main Application)¶
These services are defined in /opt/matrix/docker-compose.yml.
PostgreSQL Container
-
Image:
postgres:15-alpine -
Restart Policy:
unless-stopped -
Environment Variables:
-
POSTGRES_USER=synapse -
POSTGRES_PASSWORD=synapse -
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
Nginx Proxy Stack¶
These services are defined in /root/nginx/compose.yml.
Nginx Certbot Container
-
Image:
jonasal/nginx-certbot:latest -
Restart Policy:
unless-stopped -
Network Mode:
host -
Environment Variables:
-
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, navigate to the installation directory and run the following commands:
Location of configuration files and data¶
| File/Directory | Path |
|---|---|
| Synapse Configuration | /opt/matrix/files/homeserver.yaml |
| Element Web Config | /opt/matrix/element-config.json |
| Nginx Vhost Configs | /data/nginx/user_conf.d/ |
| Matrix Media Data | /opt/matrix/files/media_store |
Available ports for connection¶
-
HTTPS (Web Interface):
443 -
Matrix Federation:
8448 -
Internal Synapse API:
8008 -
Internal Element Web:
8080
Starting and Stopping the application¶
The application is managed via Docker Compose.
To start the application:
To stop the application:
Proxy Servers¶
The deployment uses a Nginx proxy container (jonasal/nginx-certbot) to handle SSL termination and routing. It is configured via custom virtual host files located in /data/nginx/user_conf.d/.
The proxy routes traffic as follows:
-
Requests matching
/_matrixor/_synapse/clientare forwarded to the Synapse container on port8008. -
All other requests are forwarded to the Element Web interface on port
8080.