Experimenting with Matrix 2.0 using element-docker-demo

Matthew Hodgson -

Hi all,

Back in April 2020 I published a surprisingly popular guide of how to self-host a basic Matrix instance on Debian using Riot (as Element was called back then!), Synapse and Jitsi.  Since then, things have moved on a lot: the world is increasingly aware of the benefits of decentralisation; the need for self-sovereign communication is higher than ever; and we now have Matrix 2.0 implementations to show off - providing instant sync, encrypted group calls and conferences (MatrixRTC), next-gen auth and radically improved encryption UX.

Experimenting with Matrix 2.0 is a bit more involved: in order to use next-gen auth, you have to run a separate auth server (matrix-authentication-service), and in order to use MatrixRTC you have to run a separate media conferencing server (livekit-server).  So, to provide a really simple demonstration of how these fit together using the basic implementations from Element, we’ve published element-docker-demo: a trivial docker-compose based Matrix 2.0 environment:

Before you jump in: please understand that this is not intended for production use. It’s just a hacker-friendly way of experimenting with a Matrix 2.0 stack on your local workstation or a VPS.  In particular, to quote the readme, it comes with:

  • No support, security or maintenance guarantees whatsoever
  • No high availability, horizontal scalability, elastic scaling, clustering, backup etc.
  • No admin interface
  • No monitoring
  • No fancy config management (eg ansible), just env vars and templates
  • No fancy secret management (stored in plaintext on disk)
  • No UDP traffic or TURN for LiveKit (all traffic is tunnelled over TCP for simplicity)
  • No push server, integration manager, integrations, or identity lookup server

If you are an organisation wanting to run a proper production Matrix 2.0 deployment without any of these limitations, you should take a look at Element Server Suite - Element’s actual supported commercial product, built for workplace use.

That all having been said, experimenting with element-docker-demo is astonishingly simple. You can run it locally or remotely on macOS or Linux (and it probably works under WSL2): it’s just a matter of cloning the repository, running ./setup.sh to create an .env file, and then running docker compose up. For ease of copy-pasting:

git clone https://github.com/element-hq/element-docker-demo
cd element-docker-demo

./setup.sh
# review the .env file that setup.sh generated
# set up DNS (via /etc/hosts if running locally, or wildcard DNS for a server)
# tweak the templates in ./data-template if desired

docker compose up -d
docker compose exec mas mas-cli -c /data/config.yaml manage register-user

…and that’s it: just head over to the domain on your new server to start playing with it!

We hope this provides a super-easy way for curious sysadmins to experiment with the new Matrix 2.0 implementations and APIs, as well as providing an example of how a basic deployment plugs together.  

And, once again, for non-toy deployments, please use Element Server Suite!