Note: Updated for Mastodon 4.5

Introduction

Mastodon and the Fediverse have gained significant popularity, especially during times of uncertainty with traditional social media platforms. As users seek alternative spaces, many are discovering the decentralized nature of Mastodon instances. However, this influx of users has led to challenges for unprepared instances, including performance issues and moderation difficulties.

This guide aims to provide a comprehensive walkthrough for installing Mastodon on a FreeBSD jail, managed by BastilleBSD. While Mastodon documentation tends to be Linux-centric, this tutorial fills the gap for FreeBSD users.

Note: This guide describes a simple, single-jail installation. For production environments, it's recommended to separate services (Valkey, PostgreSQL, etc.) into individual jails. This tutorial assumes a basic understanding of FreeBSD and Unix-like systems.

Prerequisites

• A FreeBSD system with BastilleBSD installed
• Basic knowledge of FreeBSD jail management
• Familiarity with command-line operations

Step 1: Creating the Jail

Let's start by creating a new jail using BastilleBSD:

bastille create mdontest 14.3-RELEASE 10.0.0.42 bastille0

Step 2: Configuring the Jail

As we'll be installing PostgreSQL in the jail, we need to add some configurations to the jail's jail.conf:

sysvmsg=new;
sysvsem=new;
sysvshm=new;

After adding these lines, restart the jail:

bastille restart mdontest
bastille console mdontest

Step 3: Installing Dependencies

Now, let's install the necessary packages:

pkg install -y curl wget gnupg gmake git-lite vips node22 yarn-node22 postgresql18-server postgresql18-contrib ImageMagick7 ffmpeg autoconf nginx valkey py311-certbot py311-certbot-nginx sudo rubygem-bundler rubygem-posix-spawn

Step 4: Enabling and Configuring Services

Enable Valkey, Nginx, and PostgreSQL:

service valkey enable
service nginx enable
service postgresql enable

Valkey Configuration

For simplicity in this jail environment, we'll disable Valkey's protected mode. However, this is not recommended for production environments without proper security measures.

Edit /usr/local/etc/valkey.conf and set:

protected-mode no

Important: In a production environment, ensure proper authentication and network security measures are in place before disabling protected mode.

PostgreSQL Initialization and Configuration

Initialize the PostgreSQL database:

service postgresql initdb

Modify PostgreSQL to accept connections from the jail's services. Edit /var/db/postgres/data18/pg_hba.conf and add:

host    all    all    10.0.0.42/32    trust

Note: In a production environment, consider using more restrictive authentication methods.

Start PostgreSQL and Valkey:

service postgresql start
service valkey start

Step 5: Database Setup

Create the Mastodon database user:

sudo -u postgres psql
CREATE USER mastodon CREATEDB;
\q

Step 6: Creating the Mastodon User

Create a dedicated user for Mastodon:

pw add user mastodon -m
echo 'export LC_ALL="en_US.UTF-8"' >> /home/mastodon/.profile

Step 7: Installing Mastodon

Enable corepack, switch to the Mastodon user and install the software:

corepack enable
su -l mastodon
git clone https://github.com/mastodon/mastodon.git live && cd live
git checkout $(git tag -l | grep '^v[0-9.]*$' | sort -V | tail -n 1)
corepack prepare

Install Ruby and Node dependencies:

export CONFIGURE_ARGS="--with-cflags=\"-Wno-error=incompatible-function-pointer-types\""
export NODE_OPTIONS="--openssl-legacy-provider"
bundle config deployment 'true'
bundle config without 'development test'
bundle install -j$(getconf _NPROCESSORS_ONLN)
yarn install --immutable

Step 8: Mastodon Setup

Run the Mastodon setup command:

RAILS_ENV=production bundle exec rake mastodon:setup

When prompted for the PostgreSQL host, enter 127.0.0.1 (or 10.0.0.42).

Mastodon can now use libvips as a lighter and more modern alternative to ImageMagick. ImageMagick support is being deprecated, so it's suggested to switch to libvips.

To use libvips instead of ImageMagick, set the MASTODON_USE_LIBVIPS environment variable to true into the .env.production:

[...]
MASTODON_USE_LIBVIPS=true

Step 9: Nginx Configuration

In the dist/ directory, you'll find an nginx.conf file. This is not a complete Nginx configuration but a partial one for Mastodon. Integrate this with your existing Nginx setup based on your specific requirements.

Note: Many administrators advise against exposing Mastodon through Cloudflare, as it may interfere with some APIs and disrupt Fediverse interactions.

Step 10: Creating FreeBSD RC Scripts

To manage Mastodon services on FreeBSD, we'll create custom rc scripts. You can find the scripts for mastodon_sidekiq, mastodon_web, and mastodon_streaming at the provided links.

Place these scripts in the /usr/local/etc/rc.d/ directory, make them executable (chmod a+rx /usr/local/etc/rc.d/mastodon_*) and enable them:

service mastodon_sidekiq enable
service mastodon_web enable
service mastodon_streaming enable

Conclusion

Restart the jail or start the services individually. Logs will be appended to /var/log/messages.

You now have a functioning Mastodon instance running in a FreeBSD jail. All services are run by the "daemon" user and are supervised.

Remember to regularly update your Mastodon instance and monitor its performance. For production environments, consider implementing additional security measures and potentially separating services into individual jails.

If you want to change the characters or poll limits, you can refer to this article.

Enjoy your new Mastodon instance!