Installing Mastodon 4.3 on a Raspberry Pi

Sun, 20 Oct 2024 21:02:53 +0000

Although the official Mastodon installation docs are quite thorough, I did find a few quirks when installing on a Raspberry Pi (both 4B and 5). I've brought together various guides that I used (sources are cited) into a single set of instructions which have repeatedly worked for me.

Step 1. Increase the swap file

If you're using a 4GB Raspberry Pi (4B or 5), you will need to increase the size of the swap file, at least temporarily, otherwise the process (in Step 9) to compile CSS/JS assets may crash. Obviously, the 1GB and 2GB models should not be used here as they lack sufficient memory.

You can set the swap file back to its original size—once Mastodon is installed—by following these steps again, but this is not necessary.

⚠️ If you're using a Raspberry Pi (4B or 5) with 8GB of RAM, you can safely skip this and move straight on to Step 2.

Stop the system from using the current swap file:
```
sudo dphys-swapfile swapoff
```
Open the swap file configuration file:
```
sudo nano /etc/dphys-swapfile
```
Find the following line of text within the file (value may vary):
```
CONF_SWAPSIZE=200
```
and change the value to 2048 (MB):
```
CONF_SWAPSIZE=2048
```
Save the file by pressing CTRL + X, followed by Y, then Enter.
Re-initialise the swap file (removes the original swap file and recreates it to fit the newly defined size):
```
sudo dphys-swapfile setup
```
Turn the swap back on:
```
sudo dphys-swapfile swapon
```
Reboot the device to allow all programs to be reloaded with access to the new memory pool:
```
sudo reboot
```

Step 2. SSH Keys

Using SSH keys for authentication instead of passwords is a great way of securing the Raspberry Pi, as well as making logins much quicker.

Find your public SSH key on your computer. On macOS, this will be a file ending .pub in the ~/.ssh directory.
Create a .ssh directory in your home directory on the Raspberry Pi:
```
install -d -m 700 ~/.ssh
```
Create (and edit) an authorized_keys file in the new directory:
```
nano ~/.ssh/authorized_keys
```
Paste the contents of your public SSH key into this file, then save.
Ensure the file has the correct permissions:
```
sudo chmod 644 ~/.ssh/authorized_keys
```
Ensure the file has the correct owner (if not using pi as the default user, replace it below with the name of your default user):
```
sudo chown pi:pi ~/.ssh/authorized_keys
```

Step 3. NGINX web server

We want the ability to host other websites on this server so we will use NGINX as a reverse proxy for Mastodon.

Update the package list and upgrade existing packages:
```
sudo apt update && sudo apt upgrade
```
Install NGINX:
```
sudo apt install -y nginx
```
Start the NGINX service:
```
sudo systemctl start nginx
```

Install PHP-FPM and recommended PHP modules:

sudo apt install -y php8.2-fpm php8.2-mbstring php8.2-mysql php8.2-curl php8.2-gd php8.2-zip php8.2-xml

Step 4. SSL certificates

I am using Cloudflare for DNS and tunnelling so I need to follow these steps to create and deploy an Origin CA certificate.

⚠️ If you don't use Cloudflare, install your own SSL certificate here instead of following the exact instructions below.

Log in to the Cloudflare dashboard and select an account.
Choose your domain.
Go to SSL/TLS > Origin Server.
Select Create Certificate.
Choose Generate private key and CSR with Cloudflare and leave all other options as they are. Click the Create button.
Ensure the Key Format is PEM and then copy the signed Origin Certificate and Private Key into separate .pem and .key files. Click the OK button.
Copy the .pem and .key files to your Raspberry Pi in the /etc/ssl directory.

Change the owner of both files to root:

sudo chown root:root /etc/ssl/filename.key /etc/ssl/filename.pem

Restart NGINX:
```
sudo systemctl restart nginx
```
Back in the Cloudflare dashboard, go to SSL/TLS > Overview and click Configure. Under the option Custom SSL/TLS click Select. Change the option to Full (Strict) and click Save.

Step 5. Mastodon pre-installation

Update and upgrade system packages:
```
sudo apt update && sudo apt upgrade
```

Install dependencies:

sudo apt install -y curl lsb-release imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git-core g++ libprotobuf-dev protobuf-compiler pkg-config nodejs gcc autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev nginx redis-server redis-tools certbot python3-certbot-nginx libidn11-dev libicu-dev libjemalloc-dev

Create a mastodon user:
```
sudo useradd mastodon -m
```

Step 6. Install NodeJS

Update the package list and upgrade existing packages:
```
sudo apt update && sudo apt upgrade
```
To ensure we have all of the packages we need to access the Nodesource repository, run the following command:
```
sudo apt install -y ca-certificates curl gnupg
```

Download the Nodesource GPG key and store it within the /usr/share/keyrings directory:

curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/nodesource.gpg

Set an environment variable that we will reference next:
```
NODE_MAJOR=20
```

Add the NodeJS repository to your sources list:

echo "deb [signed-by=/usr/share/keyrings/nodesource.gpg] https://deb.nodesource.com/node_$NODE_MAJOR.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list

Since we made changes to the sources list, we need to update the package list:
```
sudo apt update
```
Install the NodeJS package:
```
sudo apt install -y nodejs
```

Step 7. Install PostgreSQL (and enable Yarn)

Save the GPG key for the PostgreSQL repository:

curl -L https://www.postgresql.org/media/keys/ACCC4CF8.asc | gpg --dearmor | sudo tee /usr/share/keyrings/postgresql-archive-keyring.gpg >/dev/null

Add the repository to our sources list:

echo "deb [arch=arm64 signed-by=/usr/share/keyrings/postgresql-archive-keyring.gpg] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" | sudo tee  /etc/apt/sources.list.d/postgresql.list

As we changed the available repositories, we need to update the package list cache again:
```
sudo apt update
```

Install the PostgreSQL package:

sudo apt install -y postgresql postgresql-contrib

Launch the PostgreSQL command line interface (CLI):
```
sudo -u postgres psql
```
Create a PostgreSQL user named mastodon:
```
CREATE USER mastodon CREATEDB;
```
Quit out of the CLI:
```
\q
```
To build and run Mastodon, we need to enable Yarn (the NodeJS package manager). Do this now:
```
sudo corepack enable && sudo yarn set version classic
```

Step 8. Install Ruby

Switch to the mastodon user:
```
sudo su mastodon
```
Change to the home directory:
```
cd ~
```

Clone the code repository for the rbenv utility:

git clone https://github.com/rbenv/rbenv.git ~/.rbenv

Clone the code repository for the ruby-build plugin:

git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build

Adjust the .bashrc file to initialise the rbenv utility to set up the Ruby environment:
```
echo 'eval "$(~/.rbenv/bin/rbenv init - bash)"' >> ~/.bashrc
```
To ensure the changes we made are available immediately:
```
exec bash
```
Install Ruby 3.3.5:
```
RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.3.5
```
⚠️ This step can take a long time to complete.
Declare the installed Ruby version 3.3.5 as the global version to use:
```
rbenv global 3.3.5
```
Use the Ruby package manager to install bundler:
```
gem install bundler --no-document
```

Step 9. Install Mastodon

Make sure that you are still running as the mastodon user; switch to that user now, if not:
```
sudo su mastodon
```
Change to the home directory:
```
cd ~
```
Clone the code repository for Mastodon, then change to the new live directory:
```
git clone https://github.com/mastodon/mastodon.git live && cd live
```

Change to the latest stable release of Mastodon:

git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)

Set the deployment option to true and exclude any packages that are only used for development or test purposes:
```
bundle config deployment 'true' && bundle config without 'development test'
```
Install all of the Ruby dependencies for Mastodon:
```
bundle install -j$(nproc)
```
Note: we use the -j option to tell the package manager to use as many CPU cores as we have.
Install all of the NodeJS dependencies for Mastodon:
```
yarn install
```
⚠️ You can safely ignore any warnings thrown here.

Configure Mastodon:

RAILS_ENV=production bundle exec rake mastodon:setup

Follow the on-screen prompts for how you would like to set up Mastodon. You can leave the PostgreSQL and Redis options as default (just press Enter on each option).
Switch back to your default user:
```
exit
```
Update the default NGINX host file using the template provided on the Mastodon docs website, or replace the file with a copy of a previously backed-up host file.
Reload NGINX web server:
```
sudo systemctl reload nginx
```

Copy the systemd services for Mastodon to the relevant directory:

sudo cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/

Start the services now and enable them to start automatically at logon in future:
```
sudo systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming
```

Step 10. Post-installation customisation (optional)

Import a blocklist

Download this blocklist.
In Mastodon, go to Moderation > Federation and click on the Import button at the top of the page.
Choose the blocklist file you previously downloaded and click Upload.
You should now see a long list of domain blocks. Make sure the Select All checkbox is selected and then click on Import.

Change the maximum post length and poll limit

Switch to the mastodon user:
```
sudo su mastodon
```
Change to the home directory:
```
cd ~
```

Edit the compose_form_container.js file:

nano -w live/app/javascript/mastodon/features/compose/containers/compose_form_container.js

Search for the line:

maxChars: state.getIn(['server', 'server', 'configuration', 'statuses', 'max_characters'], 500)

and change the value 500 to the new limit (e.g. 2000).

Save the file by pressing CTRL + X, followed by Y, then Enter.

Edit the status_length_validator.rb file:

nano -w live/app/validators/status_length_validator.rb

Search for the line:
```
MAX_CHARS = 500
```
and change the value 500 to the same new limit as above.
Save the file by pressing CTRL + X, followed by Y, then Enter.

Edit the poll_options_validator.rb file:

nano -w live/app/validators/poll_options_validator.rb

Search for the line:
```
MAX_OPTIONS = 4
```
and change the value 4 to the new limit (e.g. 12).
Save the file by pressing CTRL + X, followed by Y, then Enter.

Rebuild the assets:

cd live && RAILS_ENV=production bundle exec rails assets:precompile

Switch back to the main user:
```
exit
```

Restart the Mastodon services:

sudo systemctl restart mastodon-sidekiq mastodon-web mastodon-streaming

Change the username, display name, and notes limits

Switch to the mastodon user:
```
sudo su mastodon
```
Change to the home directory:
```
cd ~
```
Edit the account.rb file:
```
nano -w live/app/models/account.rb
```

Search for the following lines and amend as required:

USERNAME_LENGTH_LIMIT = 30

DISPLAY_NAME_LENGTH_LIMIT = 30

NOTE_LENGTH_LIMIT = 500

Save the file by pressing CTRL + X, followed by Y, then Enter.