A workaround for docker container intialization requirements when using docker compose. #

Synapse is a great implementation of the [matrix] federated chat platform, but the official documentation expects you to run several manual initialization steps before your server is ready to use. This gets tedious when you’re just want to use a docker compose file to plug in your info and get going, especially if you are using tools like Portainer to administrate your containers.

This guide shows you how to bundle the entire initialization process into your docker-compose.yml so your [matrix] server goes from zero to fully operational with a single docker compose up. This compose file also includes element, which is a web-based client frontend for the [matrix] server. Note that I use HAProxy to terminate SSL within my network, so you may want to use traefic / let’s encrypt or some other proxy between your matrix server and the web if you are not in the same boat. Even if you don’t use HAProxy I think this can be a useful guide!

The Problem #

The standard [matrix] Synapse setup requires you to:

1. Generate the initial homeserver configuration
2. Create a registration shared secret
3. Wait for the server to start
4. Manually run register_new_matrix_user to create your admin account
5. Configure email settings
6. Set up your public base URL

If you’re deploying through a UI like Portainer or want to version control your entire setup, having to SSH into your server and run commands defeats the purpose. We can do better.

The Solution #

We’re going to use a custom entrypoint script that handles all the initialization automatically. All of our personal information will be stored in environment variables for easy access. These can be directly in the compose file, they can be in a separate .env file, or configured within the Portainer GUI. The script will check if this is the first run, generate the configuration if needed, inject our custom settings, start the server, and create the admin user once Synapse is ready.

Here’s a minimally censored docker-compose configuration to make it easier to understand:

version: '3'

services:
  synapse:
    image: docker.io/matrixdotorg/synapse:latest
    restart: unless-stopped
    environment:
      SYNAPSE_SERVER_NAME: matrix.karsttech.com
      SYNAPSE_REPORT_STATS: no
      SYNAPSE_ADMIN_USER: admin
      SYNAPSE_ADMIN_PASSWORD: [ADMIN_PASSWORD]
      TZ: America/New_York
      # SMTP Configuration
      SMTP_HOST: smtp.protonmail.ch
      SMTP_PORT: 587
      SMTP_USER: automation@karsttech.com
      SMTP_PASS: [SMTP_PASSWORD]
      SMTP_FROM: "Matrix <automation@karsttech.com>"
    volumes:
      - data:/data
      - media:/data/media
    ports:
      - 9447:8008/tcp # Reverse Proxy Should point http to this port

    entrypoint:
      - sh
      - -c
      - |
        if [ ! -f /data/homeserver.yaml ]; then
          /start.py generate;
          
          REG_SECRET=$$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1)
          echo "registration_shared_secret: \"$$REG_SECRET\"" >> /data/homeserver.yaml
          
          # Add public_baseurl
          echo "public_baseurl: https://matrix.karsttech.com" >> /data/homeserver.yaml
          
          echo "" >> /data/homeserver.yaml
          echo "email:" >> /data/homeserver.yaml
          echo "  smtp_host: $$SMTP_HOST" >> /data/homeserver.yaml
          echo "  smtp_port: $$SMTP_PORT" >> /data/homeserver.yaml
          echo "  smtp_user: $$SMTP_USER" >> /data/homeserver.yaml
          echo "  smtp_pass: $$SMTP_PASS" >> /data/homeserver.yaml
          echo "  require_transport_security: true" >> /data/homeserver.yaml
          echo "  notif_from: \"$$SMTP_FROM\"" >> /data/homeserver.yaml
          echo "  enable_notifs: true" >> /data/homeserver.yaml
        fi;
        
        /start.py run &
        SYNAPSE_PID=$$!
        
        if [ ! -f /data/.admin_created ]; then
          echo 'Waiting for Synapse to start...'
          sleep 5
          for i in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15; do
            if curl -s http://localhost:8008/_matrix/client/versions > /dev/null 2>&1; then
              echo 'Synapse is ready, creating admin user...'
              if register_new_matrix_user -u $$SYNAPSE_ADMIN_USER -p $$SYNAPSE_ADMIN_PASSWORD -a -c /data/homeserver.yaml http://localhost:8008; then
                touch /data/.admin_created
                echo 'Admin user created successfully!'
              else
                echo 'ERROR: Failed to create admin user!'
              fi
              break
            fi
            echo "Waiting... attempt $$i/15"
            sleep 2
          done
        else
          echo 'Admin user already created (skipping)'
        fi
        
        wait $$SYNAPSE_PID

  element:
    image: vectorim/element-web:latest
    restart: unless-stopped
    user: root
    environment:
      ELEMENT_SERVER_NAME: matrix.karsttech.com
      ELEMENT_BASE_URL: https://matrix.karsttech.com
    ports:
      - 9449:8080
    entrypoint: |
      sh -c '
      cat > /tmp/config.json <<EOF
      {
        "default_server_config": {
          "m.homeserver": {
            "base_url": "$$ELEMENT_BASE_URL",
            "server_name": "$$ELEMENT_SERVER_NAME"
          }
        },
        "brand": "Element",
        "disable_guests": false,
        "disable_3pid_login": false,
        "default_theme": "light",
        "room_directory": {
          "servers": ["$$ELEMENT_SERVER_NAME", "matrix.org"]
        },
        "enable_presence_by_default": true,
        "setting_defaults": {
          "breadcrumbs": true
        },
        "show_labs_settings": false
      }
      EOF
      cp /tmp/config.json /app/config.json
      exec nginx -g "daemon off;"
      '

volumes:
  media:
  data:

How It Works #

The magic happens in the custom entrypoint script. Let’s break down what’s happening:

First Run Detection #

if [ ! -f /data/homeserver.yaml ]; then

We check if the homeserver configuration exists. If it doesn’t, we know this is a fresh installation and we need to generate everything.

Configuration Generation #

/start.py generate;

REG_SECRET=$$(cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1)
echo "registration_shared_secret: \"$$REG_SECRET\"" >> /data/homeserver.yaml

We run the standard Synapse configuration generator, then immediately append our registration secret. The secret is randomly generated from /dev/urandom to ensure it’s unique and secure.

Configuration Injection #

Rather than manually editing the generated homeserver.yaml later, we append our custom configuration directly:

echo "public_baseurl: https://matrix.karsttech.com" >> /data/homeserver.yaml

echo "" >> /data/homeserver.yaml
echo "email:" >> /data/homeserver.yaml
echo "  smtp_host: $$SMTP_HOST" >> /data/homeserver.yaml
# ... more email config

This pulls values from environment variables, making the setup portable and easy to version control.

Background Server Start #

/start.py run &
SYNAPSE_PID=$$!

We start Synapse in the background and capture its process ID. This lets us continue with initialization while the server warms up.

Admin User Creation #

if [ ! -f /data/.admin_created ]; then
  echo 'Waiting for Synapse to start...'
  sleep 5
  for i in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15; do
    if curl -s http://localhost:8008/_matrix/client/versions > /dev/null 2>&1; then

We use a marker file (.admin_created) to track whether we’ve already created the admin user. Then we poll the Synapse API endpoint until it responds, indicating the server is ready to accept user registration.

Once ready, we create the admin user and touch the marker file so we don’t try to create it again on subsequent restarts.

Process Management #

wait $SYNAPSE_PID

Finally, we wait on the Synapse process. This ensures the container doesn’t exit and that Docker properly handles signals when you stop the container.

Element Web Client #

The Element service is simpler but uses the same pattern - we generate its configuration from environment variables on startup:

cat > /tmp/config.json <<EOF
{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "$$ELEMENT_BASE_URL",
      "server_name": "$$ELEMENT_SERVER_NAME"
    }
  },
  ...
}
EOF
cp /tmp/config.json /app/config.json

This lets you change Element’s configuration by updating environment variables rather than mounting configuration files.

Federation and .well-known #

For [matrix] federation to work properly, you need to serve the .well-known endpoints. If you’re using HAProxy like I am, here’s the configuration:

acl			matrix_wellknown_client_path_acl	var(txn.txnpath) -m str -i /.well-known/matrix/client
acl			matrix_wellknown_server_path_acl	var(txn.txnpath) -m str -i /.well-known/matrix/server
http-request return status 200 content-type application/json string '{"m.homeserver":{"base_url":"https://matrix.karsttech.com"}}'  if  matrix_wellknown_client_path_acl aclcrt_karsttech_ssl_offloading_frontend
http-request return status 200 content-type application/json string '{"m.server":"matrix.karsttech.com:443"}'  if  matrix_wellknown_server_path_acl aclcrt_karsttech_ssl_offloading_frontend

These rules tell other [matrix] servers where to find your homeserver and ensure clients can auto-discover your server configuration.

Deployment #

To deploy this setup:

1. Replace matrix.karsttech.com with your domain
2. Set your admin credentials in SYNAPSE_ADMIN_USER and SYNAPSE_ADMIN_PASSWORD
3. Configure your SMTP settings for email notifications
4. Run docker compose up -d

That’s it. The first startup will take a bit longer as it generates configuration and creates the admin user, but subsequent restarts will be fast since everything is already initialized.

A Quick Warning #

If you are new to [matrix] I highly recommend that the first thing you do when you set up a new account is to go to Settings -> Encryption and save / write down your Recovery Key! Without this if you clear your browser cache or move to a new computer you will lose access to your encrypted messages and will need to reestablish trust with your fellow [matrix] users.

A Small Invitation #

As a special way to reach out to any readers who also use [matrix] chat, the first 10 people to use THIS LINK will be able to create an account at matrix.karsttech.com

Happy self-hosting!