Matrix Synapse Homeserver

Run Matrix Synapse Homeserver as Docker Container with SQLite DB

Source/Based on:

Tested on Ubuntu 18.04 (used sqlite DB)

  1. Install required Python 3.8:

     sudo apt install python3.8
  2. Clone Synapse repo:

     git clone
     cd synapse
  3. Build Synapse Docker image from source:

     docker build -t matrixdotorg/synapse -f docker/Dockerfile .
  4. Generate and adapt configuration files:

     docker run -it --rm \
     --mount type=volume,src=synapse-data,dst=/data\
     -e SYNAPSE_SERVER_NAME=synapse \
     matrixdotorg/synapse:latest generate

    Command generates a homeserver.yaml in (typically) /var/lib/docker/volumes/synapse-data/_data, customise homeserver.yaml to use sqlite DB:

    sudo nano /var/lib/docker/volumes/synapse-data/_data/homeserver.yaml

    Changed following part to:

     # Example Postgres configuration:
     #  name: psycopg2
     #  args:
     #    user: synapse
     #    password: Our_supersecret_postgrespassword
     #    database: synapse
     #    host: postgres
     #    cp_min: 5
     #    cp_max: 10
     # For more information on using Synapse with Postgres, see `docs/`.
       name: sqlite3
         database: /data/homeserver.db

    Enable user registration for the Matrix Synapse homeserver:

     ## Registration ##
     # Registration can be rate-limited using the parameters in the "Ratelimiting"
     # section of this file.    
     # Enable registration for new users.   
     enable_registration: true

    Session lifetime can be defined (by default it is infinite):

     # Time that a user’s session remains valid for, after they log in.
     # Note that this is not currently compatible with guest logins.
     # Note also that this is calculated at login time: changes are not applied
     # retrospectively to users who have already logged in.
     # By default, this is infinite.
     #session_lifetime: 24h
  5. Run Matrix Synapse Docker container:

     docker run -d --name synapse \
     --mount type=volume,src=synapse-data,dst=/data\
     -p 8008:8008 \

    Matrix Synapse homeserver is available at http://localhost:8008, but a client (e.g. Element) is necessary to access it.

  6. If anything goes wrong:

     docker logs synapse    # check the docker logs
     docker container ls    # list running container
     docker container stop synapse  # stop container
     docker container start synapse # start container
     docker container rm synapse # delete container
     docker image rmsynapse # delete synapse docker image and build a new one

Links/additional resources:

  • Synapse installation without Docker is described here:
  • Installed Synapse version can be identified via: http://localhost:8008/_matrix/federation/v1/version
  • http://localhost:8008/_matrix/client/versions shows the versions of the Client-Server API supported (and unstable features).

Run Matrix Synapse Homeserver as Docker Container with Postgres DB

Create an .env file as described in the .env.example file:

# Postgres DB connection

# synapse settings

Download and run a Postgres Docker image (check for correct path of .env file):

    docker run --name postgres --env-file=./resources/.env  -p 5432:5432 -d  --mount type=volume,src=postgres-data,dst=/data postgres:11

Connect to container and create the Synapse database:

docker exec -it postgres psql -U  synapse_user
\l 				# show  databases
\q 				# exit

Generate a new volume and Matrix homeserver configuration file (check for correct path of .env file):

 docker run -it --rm  --env-file=./resources/.env  --mount type=volume,src=synapse-data,dst=/data matrixdotorg/synapse:latest generate

The homeserver.yaml is (typically) stored in /var/lib/docker/volumes/synapse-data/_data; customise homeserver.yaml to use Postgres database:

  sudo nano /var/lib/docker/volumes/synapse-data/_data/homeserver.yaml

Change the following part to use a Postgres DB:

# Example Postgres configuration:

   name: psycopg2
     user: synapse_user
     password: secretpassword
     database: synapse
     host: postgres
     cp_min: 5
     cp_max: 10

and enable Matrix Synapse registration: uncomment and set to true

# Enable registration for new users.
enable_registration: true

The current release (Synapse v1.34) has a writing permission issue (cf., therefore open the synapse.log.config and change the log file path:

sudo nano /var/lib/docker/volumes/synapse-data/_data/synapse.log.config

filename: /data/homeserver.log

Start the Matrix-Synapse Docker container:

docker run -d --env-file=./resources/.env  --name synapse --mount type=volume,src=synapse-data,dst=/data --link postgres:postgres -p 8008:8008 matrixdotorg/synapse:latest

User and room creation at Matrix Synapse homeserver

Platform: Debian / Ubuntu (64-bit)


  • testuser
    • Installs Element (Matrix client)
    • Creates a Matrix room
    • Sends an invite to the SAMR21-xpro users
  • samr21node
    • Creates an access token via login
    • Joins the room
  1. Install Matrix Client “Element-Desktop” for Testing purpose:


     sudo apt install -y wget apt-transport-https
     sudo wget -O /usr/share/keyrings/riot-im-archive-keyring.gpg
     echo "deb [signed-by=/usr/share/keyrings/riot-im-archive-keyring.gpg] default main" | sudo tee /etc/apt/sources.list.d/riot-im.list
     sudo apt update
     sudo apt install element-desktop

    Alternatively you can run “Element-Web” as Docker container and access it via http://localhost (source:

     docker run -p 80:80 vectorim/riot-web
  2. Register the following users (these are created for testing purposes): admin, testuser and samr21node

     docker exec -it synapse register_new_matrix_user http://localhost:8008 -c /data/homeserver.yaml -u admin -a -p <adminpwd>
     docker exec -it synapse register_new_matrix_user http://localhost:8008 -c /data/homeserver.yaml -u testuser -p <testpwd>
     docker exec -it synapse register_new_matrix_user http://localhost:8008 -c /data/homeserver.yaml -u samr21node -p <samr21pwd>
  3. Start the Element client and login as testuser, create a new room, and check the room ID in the room settings: Element Login/Homeserver Config Element check room ID

  4. Create an invite for the @samr21node:synapse user ( client: Room options->Invite people), this creates an invite event which can be viewed by view source:

       "type": "",
       "sender": "@testuser:synapse",
       "content": {
         "membership": "invite",
         "displayname": "samr21node"
       "state_key": "@samr21node:synapse",
       "origin_server_ts": 1619515917506,
       "unsigned": {
         "age": 106
       "event_id": "$pwssXPgZ6_qiliLYmG2Kcj0vZPKUo_cWPKdp7zspc0Q",
       "room_id": "!kYsGiNgnRRVZCizHAF:synapse"

Create invite via commandline:

    curl -XPOST -d '{"user_id":"@myfriend:localhost"}' "http://localhost:8008/_matrix/client/r0/rooms/<room_id>/invite?access_token=<YOUR_ACCESS_TOKEN>"
  1. [Optional] Get the access token for the samr21node user via commandline:

     curl -XPOST -d '{"type":"m.login.password", "user":"samr21node", "password":"samr21pwd"}' "http://localhost:8008/_matrix/client/r0/login"
     {"user_id":"@samr21node:synapse","access_token":"<access token>","home_server":"synapse","device_id":"OPJPRXXURH"}
  2. [Optional] Join the room with the samr21node user:

      curl -XPOST -d '{ "room_id": "!kYsGiNgnRRVZCizHAF:synapse"}' "http://localhost:8008/_matrix/client/r0/rooms/%21kYsGiNgnRRVZCizHAF:synapse/join?access_token=<access token>"