Self-Host Matrix (I) - Deploying Dendrite Homeserver with Docker

AI summary

type

status

date

slug

summary

😀 Intro

My old domain, mykeyvans.space, is up for renewal soon, but the renewal price has been increasing year after year, becoming prohibitively expensive. Therefore, I decided to activate the new domain mykeyvans.com.

Previously, I was using Synapse as my Matrix server, along with various bridges to consolidate messages from other chat applications like WhatsApp and Instagram. However, Synapse is a comprehensive platform, offering more features than I need for personal use. Its resource consumption is also quite high. Moreover, I am now primarily using Beeper to receive messages from most of my chat applications, making the need for self-hosted bridges less essential.

Given the domain's discontinuation and the need for a streamlined architecture, I have chosen Dendrite as the foundation for rebuilding my Matrix server. I will be documenting the entire setup process for future reference.

In subsequent posts, I will cover the use of Amazon S3 / CloudFlare R2 as media sources, enabling the latest features, importing a rich collection of Telegram emojis, and exploring backup and migration strategies. Stay tuned!

📙 My Philosophy of Self-host

Embrace Docker: Minimize system modifications, break free from architectural constraints, facilitate backups, streamline management, and enable seamless migrations.

Component Minimalism: Focus on essential server-side components, forgoing client-side deployments. Utilize official web/client applications for user interaction.

Non-Invasive Approach: Minimize changes to existing services, ensuring the uninterrupted operation of other applications.

💼 Getting Started

Cloudflare Domain Setup:

You'll need a domain and a subdomain hosted on Cloudflare. These domains need to be properly resolved and have CDN enabled.
Homeserver Domain: For example, my instance is matrix.mykeyvans.com.
Root Domain: My instance is mykeyvans.com, serving as the user identification domain.

Cloud Server:

Secure a cloud server (minimum 1 CPU core and 1 GB RAM). For instance, my server is running on a local Oracle ARM machine.

⚒️ Deploying

Create Necessary Directories

First, create the necessary directories within your desired data storage location. The directory names will correspond to the data stored for each feature.

Prepare the Database

Replace postgres user password with your own, then execute the following code within your data directory:

Open a new terminal and enter commands to enter interactive mode

When the execution is complete, close the newly opened terminal and press Ctrl+C in the original terminal to end the session, and the database creation step is successful.

Setting Up Dendrite

Generate Private Key

Run the following command in your project directory to generate the Matrix server private key.

⚠️

Important: This command should only be executed once! Executing it again will overwrite your key file.

Generate Configuration

Run the following command in your project directory to generate an initial configuration file:

After generating the configuration, open the /dendrite/config/dendrite.yaml file with a text editor and modify the following:

You can use openssl rand -base64 32 to generate a random string for the registration_shared_secret field.

Configure Nginx Reverse Proxy

Generate Certificate

Since we're using Cloudflare CDN, I recommend using a self-signed empty certificate to ensure security and prevent your origin IP from being exposed.

⭐

If you decide not to use CDN, you will need to configure valid certificates yourself. Caddy is recommended for automated certificate management.

Run the following commands one by one. For the certificate generation part, press enter for all prompts and use the default values.

Config for Nginx

Modify your domain name, then paste the following content into ./nginx/nginx.conf.

Remember to replace <Homeserver Domain> with your actual homeserver domain.

Run the Docker Image

Based on the docker-compose.yml provided by Dendrite, I have made some modifications and created the following file. You can simply copy and paste it.

Once all configurations are complete, the directory structure will look something like this:

If everything is set up correctly, run docker compose up -d in the project directory to start the containers.

First Run: Create an Account

After all containers have started successfully, you'll need to create a user account. Execute docker compose exec dendrite /bin/sh to access the Dendrite interactive command line.

⭐

You only need to enter the username part, not the full username + domain name

Using Cloudflare Workers for Service Discovery

🔑

If you want your main domain to be your Matrix service domain (e.g., @me:mykeyvans.com), this step is essential. If you only want to use a subdomain (e.g., @me:homeserver.mykeyvans.com), this step can be skipped.

Service discovery is a way for the Matrix network to find the location of servers. Our actual service runs on a subdomain, but we need to let other servers/clients know that we want to use the main domain. This requires providing the /.well-known/matrix information.

Since our main domain is hosted on Cloudflare and may be running other services, using Cloudflare Workers allows us to gracefully add this service discovery information to the main domain without modifying other project files.

Create a Cloudflare Worker

Create a new Worker in the Cloudflare Dashboard → Workers & Pages.

Use the Edit Code feature and paste the following code, replacing the Homeserver Domain with your actual domain:

This code does the following:

Matches the path /well-known/matrix.

Forwards network requests for service discovery to the Matrix server.

After pasting and modifying the code, click Deploy to deploy it to the Cloudflare network.

Set up Routing Rules

In Workers & Pages → Settings → Triggers, add a new route:

Route: Enter <Main Domain>/.well-known/matrix/*

Zone: Select your main domain.

Click Add Route to add the rule. You can then check if it's working by accessing https://<Main Domain>/.well-known/matrix/server and https://<Main Domain>/.well-known/matrix/server in your browser.

🏃‍♂️ Start Using Matrix!

Once all the steps above are completed, you can start using Matrix!

Open https://app.element.io in your browser and switch the Homeserver to your root domain.

If everything is configured correctly, you should be able to enter your username and password and log in to your newly configured server!

🔑

On your first login, you'll be prompted to set and save your keys. Make sure to download and save your keys in a safe place, otherwise you may lose your chat history later on.