Element Server Suite for Cloudron

Complete Matrix communication platform packaged for Cloudron. All components run in a single app.

Components

Component	Version	Description
Synapse	1.146.0	Matrix homeserver
MAS	1.10.0	Matrix authentication service
Element Web	1.12.9	Web client
Synapse Admin	0.11.1	Admin interface (see known issues)
Hookshot	7.3.2	GitHub/GitLab/webhooks bridge
LiveKit	1.9.11	WebRTC SFU for calls
LK-JWT-Service	0.4.1	Matrix RTC auth

Cloudron addons used

• PostgreSQL - primary database
• Redis - caching and pub/sub
• Sendmail - email notifications
• OIDC - single sign-on

Build and deploy

Prerequisites

• Docker
• Cloudron CLI (npm install -g cloudron)
• Access to a container registry

Build

cd ess-cloudron

# build and tag as latest
docker build -t your-registry/ess-cloudron:latest .

# push to registry
docker push your-registry/ess-cloudron:latest

Install on Cloudron

# install the app
cloudron install --image your-registry/ess-cloudron:latest

# or update an existing installation
cloudron update --app matrix.yourdomain.com --image your-registry/ess-cloudron:latest

Ports

Port	Protocol	Purpose
8080	TCP	HTTP (Cloudron managed)
8448	TCP	Matrix federation
7881	TCP	WebRTC TCP fallback
7882	UDP	WebRTC UDP (muxed)
3479	UDP	TURN relay (LiveKit built-in)

Post-installation setup

1. Configure domain well-known records

Matrix clients discover your homeserver and calling infrastructure via .well-known records served from your base domain (the server name part of your Matrix IDs, e.g., yourdomain.com).

Cloudron can serve these automatically. Use the Cloudron API to configure both records at once (replace my.yourdomain.com, matrix.yourdomain.com, and yourdomain.com with your actual domains, and use your Cloudron API token):

curl -sk -X POST \
  "https://my.yourdomain.com/api/v1/domains/yourdomain.com/wellknown?access_token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wellKnown": {
      "matrix/server": "{\"m.server\":\"matrix.yourdomain.com:443\"}",
      "matrix/client": "{\"m.homeserver\":{\"base_url\":\"https://matrix.yourdomain.com:443\"},\"org.matrix.msc4143.rtc_foci\":[{\"type\":\"livekit\",\"livekit_service_url\":\"https://matrix.yourdomain.com/lk-jwt\"}]}"
    }
  }'

Your Cloudron API token is in ~/.cloudron.json.

Verify both records are working:

curl https://yourdomain.com/.well-known/matrix/server
# should return: {"m.server":"matrix.yourdomain.com:443"}

curl https://yourdomain.com/.well-known/matrix/client
# should return JSON with m.homeserver AND org.matrix.msc4143.rtc_foci

Important: The matrix/client record must include org.matrix.msc4143.rtc_foci for voice/video calls to work. Without it, clients will show a MISSING_MATRIX_RTC_FOCUS error when attempting calls.

2. Create admin user

See ADMIN.md for instructions on making a user an admin.

3. Configure Hookshot integrations

See the Hookshot section in ADMIN.md for GitHub, GitLab, Jira, and Figma setup.

Architecture

graph TD
    subgraph Cloudron
        subgraph ESS["ESS container (s6-overlay)"]
            Nginx[":8080 Nginx"]
            Synapse[":8008 Synapse"]
            MAS[":8081 MAS"]
            Hookshot[":9000 Hookshot"]
            LiveKit[":7880 LiveKit + built-in TURN :3479"]
            LkJwt["LK-JWT-Service"]
        end

        Proxy["Cloudron proxy"]
        PG["PostgreSQL (addon)"]
        Redis["Redis (addon)"]
    end

    Proxy --> Nginx
    Nginx --> Synapse
    Nginx --> MAS
    Nginx --> Hookshot
    Nginx --> LiveKit

    Synapse --> PG
    MAS --> PG
    Hookshot --> PG
    Synapse --> Redis

    LkJwt --> LiveKit
    LkJwt --> Synapse

Loading

Environment variables

Cloudron environment variables are automatically used:

• CLOUDRON_APP_DOMAIN - app domain
• CLOUDRON_POSTGRESQL_* - database connection
• CLOUDRON_REDIS_* - Redis connection
• CLOUDRON_MAIL_* - SMTP settings
• CLOUDRON_OIDC_* - SSO configuration

Logs

Access logs via the Cloudron dashboard or:

cloudron logs --app matrix.yourdomain.com -f

Individual service logs are in /app/data/logs/.

Backup

Cloudron automatically backs up:

• /app/data/ (configs, media, secrets)
• PostgreSQL database
• Redis data

Updating

# build new image
docker build -t your-registry/ess-cloudron:latest .
docker push your-registry/ess-cloudron:latest

# update app
cloudron update --app matrix.yourdomain.com --image your-registry/ess-cloudron:latest

Troubleshooting

Services not starting

cloudron exec --app matrix.yourdomain.com -- s6-rc -a list
cloudron exec --app matrix.yourdomain.com -- cat /app/data/logs/nginx-error.log

Database issues

cloudron exec --app matrix.yourdomain.com -- \
  psql -h $CLOUDRON_POSTGRESQL_HOST -U $CLOUDRON_POSTGRESQL_USERNAME $CLOUDRON_POSTGRESQL_DATABASE

Federation issues

Test federation at: https://federationtester.matrix.org/

Calls fail with MISSING_MATRIX_RTC_FOCUS

This means your base domain's /.well-known/matrix/client is missing the org.matrix.msc4143.rtc_foci field. See post-installation setup to configure it via the Cloudron API.

Known issues

Synapse Admin incompatibility with MAS

Synapse Admin doesn't currently work with Matrix Authentication Service (MAS). The admin API auth model changed with MAS and Synapse Admin hasn't caught up. There's a partial workaround using database triggers that can make it somewhat functional. This is being actively investigated.

License

AGPL-3.0 (following Element Server Suite licensing)

Credits

• Element - Synapse, Element Web, MAS
• Matrix.org - Hookshot
• LiveKit - WebRTC SFU
• Cloudron - platform