Freedom from Facebook: Hosting Matrix on Le Potato

This article is a tutorial describing how to install and host a Matrix server on a Libre AML-S905X-CC board - also known as "Le Potato". A quick intro explaining why this might be something you might want to do:

What is Matrix?

Matrix is an open standard and communication protocol for text, audio, and even video. Because it is an open standard, a bunch of different people have written open source versions of servers that can talk to each other using the Matrix standard, as well as open source versions of client apps that offer similar features to apps like Discord, Facebook Messenger, WhatsApp, Slack, Instagram, etc.

Why host a Matrix server?

I'm involved in organizing events for a couple of clubs at my school, and for both of them there was an existing habit of using Facebook Messenger for all communications to the members. After asking around a little bit, it seemed like many of the other clubs at the school had also settled on using Facebook. That started to seem to me like not a great situation because:

• Only boomers use Facebook (no offense boomers!)
• Facebook seems to have a whole lot of disinformation and privacy problems, partially because of the boomer thing (no offense again!), but mainly because of the way they make money by maximizing views and personal info about their users.

Having learned about Matrix while working with some other students on a "disinformation in social media" project, it looked like it might work as a decent Facebook replacement for all of our school clubs, and by using it, we might make a tiny little dent in the whole screwed up social media landscape. If you're reading this, maybe you can think of some other use that will have a similar effect? Couldn't hurt!

Why use the Libre "Le Potato"?

You might think that a Raspberry Pi would be a great starting point for a project like this, and I did in fact think that, until I looked at the current prices on Amazon, which were pretty crazy! It seems like some combo of the popularity of the RPi, and the ongoing chip shortage from the pandemic has made using the RPi quite expensive, and not great for a student budget. Luckily, I found the Libre board, also recommended on Amazon, as a nice alternative to the Raspberry Pi 3. For this reason I chose a Libre board aml-s905x-cc (nicknamed "le potato"), a very budget friendly option to establish and use as a home Matrix server. The catch (there's always a catch of course) is that there isn't quite as much info available on getting "le potato" up and running as there is about the Raspberry Pi, but hopefully, this article will help to improve that situation a little bit, as I will cover some of the little annoying problems I ran into along the way, and how I got around them.

Getting "le potato" up and running:

For simplicity, I will be using Debian as the operating system, and to do so, I will be downloading the Armbian 22.11 Jammy file from the Armbian site:

Le Potato – Armbian

armbian.com

Once the file is downloaded, you will need to transfer the file to a micro SD card, which you will insert into the Libre board to act as the boot drive. I used the free utility etcher to transfer the files to the micro SD card, found here:

balenaEtcher - Flash OS images to SD cards & USB drives

A cross-platform tool to flash OS images onto SD cards and USB drives safely and easily. Free and open source for makers around the world.

balena.io

• In keeping with the "on a budget" theme, I tried to scrounge up some old micro SD cards to use for this, and I found that you need at least a 4GB card to hold the smallest uncompressed Armbian Jammy OS. This shouldn't be a problem if you buy a new micro SD card because they don't seem to really sell smaller sizes than 8GB anymore.

Once you have loaded the OS onto the micro SD card, insert it into the provided slot on le potato. It should smoothly click into place, so no need to use much pressure. In order to boot up the board, connect it to a power source via a micro usb cable. If it is powered correctly a red and blue light will appear first. Wait until a green light appears to show that the board has booted up sucessfully and is usable. The blue light will flash when the board is processing or active.

• Note: the process of booting and getting the green light may take longer than you expect (several minutes), especially the very first time you boot for some reason, so you need to have some patience here. I initially had some issues with a flaky SD card, so this is something I learned the hard way.

Connecting remotely to the server:

I did the rest of the setup of the server through a remote terminal using putty on my desktop PC. If you don't already have it, you can download putty here: https://www.putty.org

For simplicity, you should connect le potato to your home router with a wired Ethernet connection. Once the connection has been made, your router should assign an IP address to le potato. You will need this IP address in order to connect remotely using putty. Every router will be slightly different, but if you log into your router's control panel, you should hopefully be able to be able to find under the "Network Map" or "LAN" menus. For example, I have an ASUS router, and it shows the IP addresses under the Network Map menu on the right hand side:

While you are logged into your router control panel, you might also need to set up your router's firewall to let port 443 be accessed from the outside world. You'll have to figure out how that works for your particular router, but for my ASUS router the menu looks something like:

Once you have figured out the IP address for le potato, run putty, and type the address into the "Host Name:" field and hit open:

A new terminal window should open up on your desktop containing a login prompt.
Login as root, the default password is 1234.
Set up a new password for the root user, and select bash as the default system command shell.
Select a new non-root username, and create a password for that username.
To set up with language, set yes, then 1 for english.
The board should now be ready to install any additional software you want.

Installing the Matrix Server (Synapse)

There are a bunch of different versions of servers that will work with Matrix, but I used Synapse, which is a Matrix server written in Python, and is relatively straightforward to install.

To install Synapse first we will have to install some prerequisite software. To simplify the install, you can enter the supervisor (root) mode by running the command
$ sudo -s

First its a good idea to update the original Linux OS that came with the downloaded image with any recent changes.
# apt-get update
# apt-get upgrade

Now, since Synapse is written in Python we must install Python first.

# apt-get install python3-pip python3-certbot-nginx libffi-dev sqlite3 libssl-dev libjpeg-dev libxslt1-dev libsodium-dev libopenjp2-7

Next, in order to avoid having other Python programs causing a conflict with Synapse, we will setup a Python virtual environment, which is a kind of special sub directory folder structure that we will use just for Synapse:
# pip3 install virtualenv
Python is continuously changing versions, so we want to make sure that we set up python to use the latest version used by the OS.
Python 3.10 is the latest version of python at the time of this guide, but make sure to check for the latest version and install that instead of 3.10 if it has changed.

# update-alternatives --install /usr/bin/python python /usr/bin/python3.10 1

You can now exit out of supervisor (root) mode:
# exit

OK, we are ready to install the programs that run the server.
We first must make the directory and create a virtual environment, as described above, to configure the server.
$ mkdir ~/synapse
$ virtualenv ~/synapse/env

Then we can enter the virtual environment with
$ source ~/synapse/env/bin/activate

Once we are inside the virtual environment, we need to install some additional python software packages that Synapse will use.
$ pip3 install --upgrade pip virtualenv six packaging appdirs setuptools
Now we are finally ready to install Synapse!
$ pip3 install matrix-synapse

Setting up a dynamic DNS service so you can access your server from the outside world:

If you are installing this server using your home internet connection (like I have), there is a good chance that you don't have a static IP address. If you are lucky enough to have a static IP address, you can skip this section.
I used a free service called duckdns.org, that lets you set up a custom domain name that will point to your server, and can automatically update if and when your IP address gets changed by your ISP. Go to https://duckdns.org, register for an account and create your own domain name: mydomainname.duckdns.org

Now if your IP address changes for some reason, you can update it at duckdns by typing this address into your browser:
https://www.duckdns.org/update?domains=YOUR_DOMAIN&token=YOUR_TOKEN&ip=
Where you can find YOUR_TOKEN at your duckdns.org control panel after you login there. This is something that can also be automated, but I'll leave that for a later tutorial.

Now we will configure the server. Make sure to replace “you.example.com” with your domain name

$ python -m synapse.app.homeserver \
    --server-name you.example.com \
    --config-path homeserver.yaml \
    --generate-config \
    --report-stats=yes

Getting a certificate using certbot:
Since part of the reason to use Matrix is to improve privacy, its helpful to get a certificate for the server, which will be used to encrypt all of the communications back and forth. Certbot is a program used by a nonprofit called Let's Encrypt, that offers free certificates for this purpose.

Since we already installed the certbot library earlier, we can start the certificate process with:
$ sudo certbot certonly --nginx -d you.example.com

This will lead to an interactive session with many questions that you will be required to fill out. After answering a bunch of questions, you should eventually see something that looks like this:

Please deploy a DNS TXT record under the name
_acme-challenge.example.duckdns.org with the following value:

NaM0ODwHZfL6b1pjM_rrgfCSwVcy_CALKkxR2YzyE7A

Before continuing, verify the record is deployed.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Press Enter to Continue

When you see this, you need to make a request in a browser window in order to verify that you own the domain name:
https://www.duckdns.org/updatedomains=YOUR_DOMAIN&token=YOUR_TOKEN&txt=CERTBOTTXT
For this example
CERTBOTTXT = NaM0ODwHZfL6b1pjM_rrgfCSwVcy_CALKkxR2YzyE7A
but this will be different for each use. Once you have requested this web page, you can hit Enter in the terminal window to finish the certificate process.

• Its very important to make sure that you use www.duckdns.org and not just plain duckdns.org in the web address above. There are some people on the web who have suggested that you can use duckdns.org in the address, and I spent quite a bit of time trying to figure out why that didn't work correctly. Don't be like me!

This certificate will last you for three months, and then you'll have to re-enter this command. This is also something that can be automated, so stay tuned for the next tutorial.

Then we will configure a proxy using nginx, and we will have to modify a file and restart nginx
$ sudo nano /etc/nginx/conf.d/matrix.conf

Copy these into an empty file, and replace you.example.com with your domain name

server {
    listen 80;
    listen [::]:80;
    server_name you.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name matrix.example.com;

    ssl on;
    ssl_certificate /etc/letsencrypt/live/you.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/you.example.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}
server {
    listen 8448 ssl default_server;
    listen [::]:8448 ssl default_server;
    server_name you.example.com;

    ssl on;
    ssl_certificate /etc/letsencrypt/live/you.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/you.example.com/privkey.pem;
    location / {
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

Save and exit the file, then restart nginx to apply the changes:
$ sudo systemctl restart nginx
$ sudo systemctl enable nginx

Adding users to your Matrix(Synapse) server:

Now we will enable user registration on the server. We will still have to make an admin account manually, but this will allow others to use this server to store their accounts.

First we must edit the server file.
$ nano ~/synapse/homeserver.yaml

We will then look for the line we want to uncomment. We want to uncomment the line and we will search for it by doing ctrl+w “enable_registration”. Uncomment the line, then change false to true

Now to register a user, we must be in the python virtual environment, so make sure the command prompt looks like this: (env) pi@matrix:~/synapse $

Start the synapse server
$ synctl start

Start the user configuration program

$ register_new_matrix_user -c homeserver.yaml http://localhost:8008

Follow the inputs, make sure to say “yes” for “make admin” when you are registering yourself or any other users that you want to give admin rights to. Otherwise say "no".

New user localpart [root]: [your username]
Password: [hidden]
Confirm password: [hidden]
Make admin [no]: yes
Sending registration request...
Success.

Leave the virtual environment with:
$ deactivate
You will now be able to safely close the session.

If at any time in the future you need to change settings for the server, stop the server first with
$ synctl stop

This will allow you to edit the homeserver.yaml file.
Make sure to start the server again with:
$ synctl start 
After you have finished.

You can now use one of the client apps or other software that Matrix has listed on their website to connect to the server. A really nice client app is called Element, and is available for iOS, Android, Windows, Mac, and Linux. You can get it here:

It has very similar features to many of the popular message / social media apps, so it makes a great replacement!