Note: Updated for Mastodon 4.3
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.2-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 node20 yarn-node20 postgresql15-server postgresql15-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/data15/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!