Deploy Matrix Messaging Server

Private Matrix Messaging Server

In the previous tutorial, we learned how to deploy a simple Riot chat client to access a hosted Matrix server on In this tutorial, we'll deploying a private Matrix messaging server on Akash under your domain instead of using the hosted server.

This is an advanced tutorial as we'll learn how to securely share sensitive information using encrypted Git. For an introduction, please check out the previous guide.

About Matrix Messaging

Matrix is an open network for secure, decentralized communication; an ambitious new ecosystem for open federated Instant Messaging and VoIP.

Matrix is really a decentralized conversation store rather than a messaging protocol. When you send a message in Matrix, it is replicated over all the servers whose users are participating in a given conversation - similarly to how commits are replicated between Git repositories. There is no single point of control or failure in a Matrix conversation which spans multiple servers: the act of communication with someone elsewhere in Matrix shares ownership of the conversation equally with them. Even if your server goes offline, the conversation can continue uninterrupted elsewhere until it returns.

Before we Begin

You'll need a domain name you have DNS control over. We will be using as an example in this tutorial. For DNS, we recommend Cloudflare, its free to use.

In this step, you actually use the testnet to deploy a simple web app, paying with your testnet ATK tokens. Check out the testnet guide to request tokens. Make sure to have Akash client installed on your workstation, check install guide for instructions.

Additional Software Dependencies

  • Keybase: Keybase is used as the git hosting platform for various sensitive data we will be sharing on the cloud.

  • Docker: Docker container image is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries and settings. Deployments on Akash are done using Docker.

1. Keybase Git Repository for Sharing Secrets

When creating systems like this, there is sensitive local data that is needed to create the clusters and the applications on top of them. Keybase teams offers an easy programatic way to securely version, store and share this data.

To easily and securely share sensitive data with your team and the clusters, create a Keybase team using:

keybase team create <team>

And create a repo called matrix for that team using:

keybase git create matrix --team <team>

For example, let's say your team's name is dentacoin. We would first need to create the keybase team and then matrix git repository for it:

keybase team create dentacoin
keybase git create matrix --team dentacoin

Clone the empty repo to data directory:

git clone keybase://team/dentacoin/matrix data

You should see a response like:

Cloning into 'data'...
Initializing Keybase... done.
Syncing with Keybase... done.
Syncing encrypted data to Keybase: (100.00%) 3.72/3.72 KB... done.
warning: You appear to have cloned an empty repository

2. Generate Matrix Configuration

In this step, you'll create a configuration for synapse server for your hostname. For example, if your domain is

docker run -it --rm \
--mount type=bind,src="${PWD}/data",dst=/data \
ovrclk/synapse / \
--server-name ${HOST} \
--config-path /data/homeserver.yaml \
--generate-config \

You'll see a response similar to:

Generating config file /data/homeserver.yaml
Generating log config file /data/ which will log to /synapse/homeserver.log
Generating signing key file /data/
A config file has been generated in '/data/homeserver.yaml' for server name '' Please review this file and customise it to your needs.

Your data directory should look something like this:

├── homeserver.yaml

Replace the data/homeserver.yaml with the below configuration, (the generated configuration has imporper port listening configuration besides other issues). Ideally, you should replace registration_shared_secret form_secret macaroon_secret_key with the generated values but not required for the this tutorial.

For a full configuration sample, see Matrix sample_config.yaml.

Ensure HOST variable is set


Create homeserver.yaml configuration

cat > data/homeserver.yaml <<EOF
server_name: "${HOST}"
enable_registration: true
pid_file: /synapse/
- ''
- ''
- ''
- ''
- ''
- ''
- '::1/128'
- 'fe80::/64'
- 'fc00::/7'
- port: 8008
tls: false
type: http
x_forwarded: true
bind_addresses: ['::']
- names: [client, federation]
compress: false
enabled: false
port: 80
bind_addresses: ['::', '']
reprovision_threshold: 30
domain: ${HOST}
account_key_file: /synapse/acme_account.key
name: "sqlite3"
database: "/synapse/homeserver.db"
log_config: "/data/${HOST}.log.config"
media_store_path: "/synapse/media_store"
uploads_path: "/synapse/uploads"
registration_shared_secret: "FdvX6=Zl^criYPibk+=VkyS:_f*K#=kl#NZ0d;BE#3kL1YNSuE"
autocreate_auto_join_rooms: false
report_stats: true
macaroon_secret_key: "Oyy*=k5Ogwkx;oCZx7e;j@bC_iD,P^H-O3#AnszmRFEMm_lxu6"
form_secret: "P-qZnkpZpT4Y-kAH7ycH0;a#zVz#q#:.-0CD=0*B7;.3#zI&Yq"
signing_key_path: "/data/${HOST}.signing.key"
- server_name: ""
enabled: true
enabled: true
search_all_users: false

3. Commit and Push your Configuration

Since we'll be sharing the configuration and private keys, commit the configuration and push to keybase:

cd data
git add .
git commit -am 'add home server configuration'
git push

You should see a response similar to:

Initializing Keybase... done.
Syncing with Keybase... done.
Preparing and encrypting: (100.00%) 3/3 objects... done.
Indexing hashes: (100.00%) 3/3 objects... done.
Indexing CRCs: (100.00%) 3/3 objects... done.
Indexing offsets: (100.00%) 3/3 objects... done.
Syncing encrypted data to Keybase: (100.00%) 18.95/18.95 KB... done.
To keybase://team/dentacoin/matrix
c8adf78..d15b446 master -> master

4. Deploy on Akash

4.1 Authenticating Keybase on the Cluster

We'll be using keybase oneshot for logging into keybase from the cluster. keybase oneshot is used to establish a temporary device that will be thrown away after the corresponding "keybase service" process exits (or logout is called).

We'll need to create a paper key that'll be shared using an environment variable along with your Keybase username and the configuration repository.

Create a Keybase Paper Key, using:

keybase paperkey

The above will result in some thing similar to:

Generating a new paper key.
Here is your secret paper key phrase:
dry beauty false duck enroll age ozone acoustic truth picture thumb gasp toast
Write it down and keep somewhere safe.

Create a SDL file that looks like the below, replace the values for KEYBASE_PAPERKEY, HOST, KEYBASE_USERNAME and CONFIG_REPO with your values, like replace with your domain name.

Export the below environment variables:

export KEYBASE_PAPERKEY="dry beauty false duck enroll age ozone acoustic truth picture thumb gasp toast"
export KEYBASE_USERNAME=kn0tch
export CONFIG_REPO=keybase://team/dentacoin/matrix

Generate a deployment config using the below, here you're passing the Paper key and username using Environment variables as well as setting command line arguments the synapse container:

cat > deploy.yml <<EOF
version: "1.0"
image: ovrclk/synapse
- "-c"
- "/data/homeserver.yaml"
- port: 8008
as: 80
- ${HOST}
- global: true
cpu: "1"
memory: "1Gi"
disk: "1G"
sgx: enabled
synapse: 500u
profile: synapse
count: 1

Here's a sample of full SDL file for your reference.

Create a deployment on Akash using:

akash deployment create deploy.yml

You should see a response similar to:

(wait) [deploy] begin deployment from config: (...)
(wait) [broadcast] request deployment for group(s): global
(done) [broadcast] request accepted, deployment created with id: 5961e9263ca8e3a4fcff357a44272ca75266486d0633aec68daf8da63e5afa2c
(wait) [auction] waiting to create buy orders(s) for 1 deployment groups(s)
(wait) [auction] buy order (1) created with id: 5961e9263ca8e3a4fcff357a44272ca75266486d0633aec68daf8da63e5afa2c/1/2
(wait) [auction] waiting on fulfillment(s)
(wait) [auction] received fulfillment (1/1) with id:
(wait) [lease] waiting on lease(s)
(done) [auction] complete; received 1 fulfillment(s) for 1 order(s)
(wait) [lease] received lease (1) for group (1/1) [price 86] [id
(wait) [lease] send manifest to provider at
(done) [lease] manifest accepted by provider at
(done) [lease] complete; received 1 lease(s) for 1 groups(s)
(done) [deploy] deployment complete
Deployment ID: 5961e9263ca8e3a4fcff357a44272ca75266486d0633aec68daf8da63e5afa2c
Deployment Groups(s): Group: global
Resources: Count: 1
Price: 500
CPU: 1000
Memory: 1073741824
Disk: 1000000000
Fulfillment(s): Group: 1
Price: 86
Provider: f1695acb26884111d87e91d655fddc511a961987c846a61b62ce42f5ba1d90e7
Lease ID: 5961e9263ca8e3a4fcff357a44272ca75266486d0633aec68daf8da63e5afa2c/1/2/f1695acb26884111d87e91d655fddc511a961987c846a61b62ce42f5ba1d90e7
web 0 0
web 0 0
web 0 0

5. Update DNS by adding a CNAME

Add a CNAME dns record on your DNS provider to map, with For example:


Once that's complete, you can simply share with your community.

If you're hosting your DNS on Cloudflare, please make sure your SSL/TLS encryption mode is Flexible for DNS to work.

6. Login To Your Private Matrix Server using Riot

Set up the Riot Web client for Matrix by following this Guide. Alternatively, you could use the hosted riot client.

step 1

<<<<<<< Updated upstream

Create Account

Create a new Account by selecting the option and chose Advanced. Provide the url to your matrix server for Homeserver URL. Ignore the errors on screen if any as they are mostly configuration related.

6.1 Create Account

Create a new Account by selecting the option and chose 'Advanced'. Provide the url to your matrix server for 'Homeserver URL'. Ignore the errors on screen if any as they are mostly configuration related.

Stashed changes

The below example will create a user greg at

<<<<<<< Updated upstream step 2

Create a Room

And invite our community by showing what you built, join our chat

step 4

If you enjoyed this article, don't forget to subscribe to our newsletter, we have exciting things coming every week!

step 2

step 4 step 5

Stashed changes