Mastodon

Updated 2 August 2021

Mastodon is a free distributed microblogging platform running on a federated network.

Preparing a LXC container

We suggest that you install Mastodon in a separate container and configure it according to the manual.

Installing and configuring PostgreSQL

Install and configure PostgreSQL according to the manual.

Enable peer authentication for local connections only:

# TYPE  DATABASE        USER            ADDRESS                 METHOD

# "local" is for Unix domain socket connections only
local   all             all                                     peer
# IPv4 local connections:
#host    all             all             127.0.0.1/32            trust
# IPv6 local connections:
#host    all             all             ::1/128                 trust
# Allow replication connections from localhost, by a user with the
# replication privilege.
#local   replication     all                                     trust
#host    replication     all             127.0.0.1/32            trust
#host    replication     all             ::1/128                 trust

Create a user named mastodon and enable them to create databases:

psql (12.2)
Type "help" for help.

postgres=# CREATE USER mastodon CREATEDB;
CREATE ROLE
postgres=# \q

Install Mastodon

Installing system packages

Install the necessary accessories:

Starting Redis

Start Redis and add it to autostart:

Creating a system user

Create a system user called mastodon:

Installing and configuring rbenv and rbenv-build

Install rbenv and rbenv-build to the user's home directory and configure them:

Installing Ruby

Install the required version of Ruby, 2.7.2 in our case:

The default version of gem associated with ruby_2.7.2 is not compatible with the latest version of bundler. Therefore, update gem:

And install bundler:

Installing Node.js and Yarn

Install Node.js and Yarn to the user's home directory:

Fetching Mastodon sources from Git

Install the source code:

Installing Ruby and Node.js dependencies

Install Ruby dependencies:

Install Node.js dependencies:

Installing and configuring Mastodon

Create a configuration for ~mastodon.example.org~~ with the following command:

Your instance is identified by its domain name. Changing it afterward will break things.
Domain name: mastodon.example.org

Single user mode disables registrations and redirects the landing page to your public profile.
Do you want to enable single user mode? No

Are you using Docker to run Mastodon? no

PostgreSQL host: /var/run/postgresql
PostgreSQL port: 5432
Name of PostgreSQL database: mastodon_production
Name of PostgreSQL user: mastodon
Password of PostgreSQL user:
Database configuration works! 🎆

Redis host: localhost
Redis port: 6379
Redis password:
Redis configuration works! 🎆

Do you want to store uploaded files on the cloud? No

Do you want to send e-mails from localhost? No
SMTP server: mail.example.org
SMTP port: 465
SMTP username:
SMTP password:
SMTP authentication: starttls
SMTP OpenSSL verify mode: none
E-mail address to send e-mails "from": Mastodon <notifications@mastodon.example.org>
Send a test e-mail with this configuration right now? Yes
Send test e-mail to: admin@example.org

This configuration will be written to .env.production
Save configuration? Yes

Now that configuration is saved, the database schema must be loaded.
If the database already exists, this will erase its contents.
Prepare the database now? Yes
Running `RAILS_ENV=production rails db:setup` ...

Created database 'mastodon_production'
...
Done!

The final step is compiling CSS/JS assets.
This may take a while and consume a lot of RAM.
Compile the assets now? Yes
Running `RAILS_ENV=production rails assets:precompile` ...

yarn install v1.15.2
...
Done!

All done! You can now power on the Mastodon server 🐘

Do you want to create an admin user straight away? Yes
Username: admin
E-mail: admin@example.org
You can login with the password: e3b316f78cbc2ec0bde5118c68414d73
You can change your password once you login.

Exit the user session:

Getting Let's Encrypt certificate

Get the ~~mastodon.example.org~ domain certificate ~ for Nginx, according to the manual.

Installing and configuring Nginx

Install and configure a Nginx Web server as a reverse proxy according to the manual.

Copy the example of Nginx configuration for Mastodon:

Specify the paths and the server name, mastodon.example.org:

server {
  listen 80;
  listen [::]:80;
  server_name mastodon.example.org;
  root /var/calculate/www/mastodon/live/public;
  location /.well-known/acme-challenge/ { allow all; }
  location / { return 301 https://$host$request_uri; }
}
server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;
  server_name mastodon.example.org;

  # Uncomment these lines once you acquire a certificate:
  ssl_certificate /etc/letsencrypt/live/mastodon.example.org/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/mastodon.example.org/privkey.pem;
  ...
  root /var/calculate/www/mastodon/live/public;
  ...
}

Starting Mastadon

Create OpenRC scripts for managing the services:

Here is an init script for Mastodon Web:

#!/sbin/openrc-run

name="Mastodon Web daemon"
description=""
pidfile=/run/mastodon-web.pid
extra_commands="reload"
command_user=mastodon
output_log=/var/log/mastodon-web.log
error_log=/var/log/mastodon-web.log
directory=/var/calculate/www/mastodon/live
start_stop_daemon_args="-e RAILS_ENV=production -e PORT=3000"
command=/var/calculate/www/mastodon/.rbenv/shims/bundle
command_args="exec puma -C config/puma.rb"
command_background=true

depend() {
    use postgresql net redis
}

start_pre() {
    checkpath -f -o mastodon -m 0600 /var/log/mastodon-web.log
}

reload() {
    einfo "Reload $name"
    kill -USR1 $(cat $pidfile)
}

Here is an init script for Mastodon Streaming:

#!/sbin/openrc-run
name="Mastodon streaming daemon"
description=""
pidfile=/run/mastodon-streaming.pid
command_user=mastodon
output_log=/var/log/mastodon-streaming.log
error_log=/var/log/mastodon-streaming.log
directory=/var/calculate/www/mastodon/live
start_stop_daemon_args="-e NODE_ENV=production -e PORT=4000 -e STREAMING_CLUSTER_NUM=1"
command=/var/calculate/www/mastodon/.node-live/bin/node
command_args="./streaming"
command_background=true

depend() {
    use postgresql net redis
}

start_pre() {
        checkpath -f -o mastodon -m 0600 /var/log/mastodon-streaming.log
}

and the one for Mastodon Sidekiq:

#!/sbin/openrc-run

name="Mastodon Sidekiq daemon"
description=""
pidfile=/run/mastodon-sidekiq.pid
command_user=mastodon
output_log=/var/log/mastodon-sidekiq.log
error_log=/var/log/mastodon-sidekiq.log
directory=/var/calculate/www/mastodon/live
start_stop_daemon_args="-e RAILS_ENV=production -e DB_POOL=25 -e MALLOC_ARENA_MAX=2"
command=/var/calculate/www/mastodon/.rbenv/shims/bundle
command_args="exec sidekiq -c 25"
command_background=true

depend() {
    use postgresql net redis
}

start_pre() {
    checkpath -f -o mastodon -m 0600 /var/log/mastodon-sidekiq.log
}

Set up privileges for Mastodon services:

Launch the Mastodon services:

Add them to autostart:

Updating Mastodon

Git update

Update the Git repository containing Mastodon source code:

Make sure that the version of the source code has changed:

HEAD detached at v2.8.0
nothing to commit, no changes detected

Ruby update

As of today, Mastodon uses Ruby 2.7.2. If you have a lower version of Ruby, please update it.

Log in to the user session:

Update the control environment for Ruby:

Install the required version of Ruby, 2.7.2 in our case:

The default version of gem associated with ruby_2.7.2 is not compatible with the latest version of bundler. Therefore, update gem:

And install bundler:

Go to the Mastodon application directory and make sure it uses version 2.6.6:

2.7.2

To update Ruby dependencies, run:

Exit the user session:

Node.js update

If you update a Mastodon under v3.4, make sure to use at least Node.js 12:

v12.22.4

If the version is older than 12, install version 12.22.4 in the new .node-12 environment and make it the current one:

Update Ruby and Node.js dependencies

You may need to update Ruby and Node.js after upgrading to a new version of Mastodon. The above-mentioned release notes will tell you if you need to do the rest of this section.

To update Ruby dependencies, run:

To update Node.js dependencies, run:

Database schema update

Update the database schema at every update time, up to the new version of Mastodon. This operation is safe, since the update will be skipped anyway if there is no new schema.

For database migration, run:

Pre-compilation of updated resources

You may need to pre-compile updated resources after upgrading to a new version of Mastodon. The above-mentioned release notes will tell you if you need to do the rest of this section.

For pre-compilation, run:

Cache clearing

Clear the cache:

Additional update time actions

Release notes may contain relevant instructions marked Non-Docker that you may need when you want to update to a new Mastodon version.

Exit the user session:

Restore Ruby environment after updating system packages

Log in to the user session:

Reinstall the packages belonging to the Ruby environment:

Exit the user session:

Restarting Mastodon

Mastodon operates in RAM only, so you will need to restart it for any of the previously described updates to take effect. To restart, run: