Things They Don’t Tell You About Installing A Mastodon Server

I followed the directions in the Mastodon documentation for setting up a Mastodon server. Along the way, I discovered several stoppers that I had to figure out for myself. I’m writing these things down so I don’t forget how I addressed them.

I did the install on an Ubuntu 22.04.1 (Jammy) Linux server. (I used my “Always Free” server from Oracle.) I opted for the Installing From Source option. Some of the issues I encountered likely relate to that installation option, others may be more universal.

Grant Web Server Permission To Mastodon’s Files

The first time I tried to access the site after completing the instructions, I got error code messages back from the web server. The nginx error log showed permission was being denied when it tried to access the files in the /home/mastodon/live/public directory. I resolved this by adding the www-data userid which runs nginx to the mastodon user group on the server.

Precompile The Mastodon Assets

When I tried accessing the site again I still got 500 error code messages from the web server. The system log contained errors from the mastodon-web service saying that files were missing: “Webpacker can’t find media/images/preview.png …” I needed to run the asset precompile task to create the missing file packages. The troubleshooting notes mentioned this as something that needs to be done after upgrading the Mastodon code:

$ sudo su mastodon -
$ cd ~/live
$ RAILS_ENV=production bin/rails assets:precompile

Grant Public Access To The Object Store

When I set up my AWS S3 object store I discovered that I needed to enable public access to the S3 bucket that the mastodon server created. It would have perhaps been better if I had created the S3 bucket I was going to use before running the Mastodon server configuration wizard.

AWS Link In NGINX Configuration For The Object Store Proxy

The configuration for nginx that is suggested in the instructions includes this line defining the base URL for the files in the object store:

set $s3_backend 'https://YOUR_BUCKET_NAME.YOUR_S3_HOSTNAME';

The AWS S3 link should instead be in this format:

set $s3_backend 'https://s3.amazon.com/YOUR_BUCKET_NAME';

Establish A Secure Tunnel Between The Mastodon Server And The ElasticSearch Server

The installation instructions mention the fact that ElasticSearch, by default, provides no security layer to control access. To maintain a secure environment, ES should only be used by local processes or, if it must be accessed remotely, some sort of secure network connection should be used. I already had an ES server for another system that I run and I didn’t want to create another one just for Mastodon.

I used SSH secure tunneling to provide a secure connection between the mastodon server and the existing ES server. I use the autossh application on the mastodon server to set the tunnel up at system boot and to keep it running. The following two files define a systemd service for this purpose. SSH login between the two systems should be set up and tested before starting this service. Once the tunnel is in place the mastodon server can be configured to access ES at localhost:9200 and communications between it and the ES server will be secure and encrypted.

/etc/systemd/system/elasticsearch-tunnel.service:

[Unit]
Description=SSH tunnel to the elasticsearch server
Wants=network-online.target
After=network-online.target sshd.service

[Service]
Type=simple
Restart=on-failure
EnvironmentFile=/etc/default/elasticsearch-tunnel
ExecStart=/usr/bin/autossh -M 20000 -4 -L ${ES_PORT}:${PRIVATE_IP}:${ES_PORT} -N ${USER}@${PUBLIC_IP}

[Install]
WantedBy=multi-user.target

/etc/default/elasticsearch-tunnel:

#  This file contains the values required by the elasticsearch-tunnel systemd service.
#
#  This file should be located at /etc/default/elasticsearch-tunnel.

#  The publicly accessable IP address for the elasticsearch server
PUBLIC_IP=

#  The private network IP address where the elasticsearch server listens for connections
PRIVATE_IP=127.0.0.1

#  The userid on the elasticsearch server that will be used for the SSH login
USER=

#  The port on the elasticsearch private network IP address where the server listens for connections
ES_PORT=9200