Step-by-step Guide to Installing Mastodon on Ubuntu 24.04 Server

Discover Mastodon’s Standout Features

Mastodon has grown in popularity as a self-hosted, decentralized social media platform, giving users and administrators the power to create an open, privacy-focused online community.

In this guide, we will walk you through the installation process for Mastodon on an Ubuntu 24.04 server, from setting up your database to configuring Nginx and securing your server with HTTPS.

Mastodon Features

• Complete control over your data.
• Decentralization, since Mastodon isn’t controlled by a single entity.
• Autonomy of Mastodon instances.
• Responsive and intuitive web design.
• Free of charge and open-source.
• Support of official mobile Mastodon apps for iOS and Android.

What You’ll Need Before Starting (Prerequisites)

Before we begin, ensure you have the following:

• An Ubuntu 24.04 server with root access and at least 2 GB of RAM.
• A domain name with DNS pointing to your server’s IP address.
• An SMPT Service.
• SSL certificates (we’ll use Let’s Encrypt in this guide).
• Basic familiarity with terminal commands.

Step 1: Set Up Your PostgreSQL Database Like a Pro

Log into your server through SSH.

Add the upstream repository:

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

Transfer the PostgreSQL public key:

sudo mkdir -p /etc/apt/keyrings/

wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo tee /etc/apt/keyrings/postgresql.asc

Update repository index and install PostgreSQL:

sudo apt update

sudo apt upgrade

sudo apt install -y postgresql postgresql-contrib

Create a Mastodon Database and User: 

sudo -u postgres psql CREATE USER mastodon WITH CREATEDB PASSWORD 'securepassword'; CREATE DATABASE mastodon_production OWNER mastodon; \q

Make sure you replace 'securepassword' with a strong password.

Step 2: Install Ruby on Ubuntu 24.04

Since Ubuntu 24.04 repository includes the ruby package, and Mastodon requires Ruby 3.0 - 3.2, you can run the following command:

sudo apt install ruby ruby-dev

Check the Ruby version number with the following command:

ruby -v

The output should look like this:

ruby 3.2.3 (2024-01-18 revision 52bb2ac0a6) [x86_64-linux-gnu]

Step 3: Get Mastodon Downloaded and Ready to Configure

Create a mastodon user:

sudo adduser mastodon --system --group --disabled-login

Install the git tool:

sudo apt install git

Clone the Mastodon code repository from Github with the following command:

git clone https://github.com/tootsuite/mastodon.git

Create the /var/www/ directory (skip this step, if it already exists):

sudo mkdir -p /var/www/

Move the mastodon directory to /var/www/:

sudo mv mastodon/ /var/www/

Make mastodon the owner:

sudo chown mastodon:mastodon /var/www/mastodon/ -R

Check out the latest stable release of Mastodon:

cd /var/www/mastodon/

sudo -u mastodon git checkout v4.2.8

Install bundler: the Ruby dependency manager:

sudo gem install bundler

Install Node.js v18:

curl -sL https://deb.nodesource.com/setup_18.x | sudo bash -

sudo apt install nodejs

Install Yarn (a Node.js package manager):

echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -

sudo apt update

sudo apt -y install yarn

Install packages to compile source code:

sudo apt install redis-server optipng pngquant jhead jpegoptim gifsicle nodejs imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file g++ libprotobuf-dev protobuf-compiler pkg-config gcc autoconf bison build-essential libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev libidn11-dev libicu-dev libjemalloc-dev

Install dependency packages for Mastodon:

sudo -u mastodon bundle config deployment 'true'

sudo -u mastodon bundle config without 'development test'

sudo -u mastodon bundle install -j$(getconf _NPROCESSORS_ONLN)

sudo -u mastodon yarn install

Run the setup wizard:

sudo -u mastodon RAILS_ENV=production bundle exec rake mastodon:setup

First, it will ask you a series of questions.

• Domain name: Choose a domain name for your Mastodon instance.
• Enable single-user mode: Enable single-user mode if you want visitors to be able to register on your Mastodon instance.
• Are you using Docker to run Mastodon: No.
• PostgreSQL host: 127.0.0.1
• PostgreSQL port: 5432
• PostgreSQL database: mastodon
• PostgreSQL user: mastodon
• PostgreSQL user password: The password for the mastodon user was created in step 1.
• Redis host: 127.0.0.1
• Redis port: 6379
• Redis password: Press Enter.
• Do you want to store uploaded files on the cloud? If you want to store files on your own server, choose No.
• Do you want to send emails from localhost? If this is your mail server, or you have set up an SMTP relay, then you can choose Yes, otherwise enter your SMTP server login credentials.
• E-mail address to send e-mails “from”: Press Enter to use the default sender email address.
• Send a test e-mail with this configuration right now. Choose Yes to send a test email.
• Send a test e-mail to: Enter the test email address.
• Save configuration? Choose Yes.

Next, press Yes to set up the database. Now that configuration is saved, the database schema must be loaded. Next, choose Yes to compile CSS/JS assets. Finally, compile CSS/JS assets.

Now, you can create an admin user.

Step 4: Power Up Mastodon and Launch Your Instance.

Copy systemd service templates to the /etc/sysetmd/system/ directory:

sudo cp /var/www/mastodon/dist/mastodon.service /etc/systemd/system/

Change the directory to /var/www/mastodon/:

sudo sed -i 's/home\/mastodon\/live/var\/www\/mastodon/g' /etc/systemd/system/mastodon-.service

Change /home/mastodon/.rbenv/shims/bundle to /usr/local/bin/bundle:

sudo sed -i 's/home\/mastodon\/.rbenv\/shims/usr\/local\/bin/g' /etc/systemd/system/mastodon-.service

Reload systemd to activate the changes:

sudo systemctl daemon-reload

Start the systemd services:

sudo systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming

Check status:

sudo systemctl status mastodon-web mastodon-sidekiq mastodon-streaming

Run the following command to check if Mastodon is listing on port 3000:

sudo ss -lnpt | grep 3000

If port 3000 is already occupied by another process, you need to edit the /etc/systemd/system/mastodon-web.service file:

sudo nano /etc/systemd/system/mastodon-web.service

Change the port number tp 3001, reload systemd and restart Mastodon:

sudo systemctl daemon-reload

sudo systemctl restart mastodon-web

Step 5: Master Nginx Reverse Proxy Setup for Mastodon

Install Nginx web server from the Ubuntu 24.04 software repository:

sudo apt install nginx

Copy the Nginx template configuration file:

sudo cp /var/www/mastodon/dist/nginx.conf /etc/nginx/conf.d/mastodon.conf

Edit the new file:

sudo nano /etc/nginx/conf.d/mastodon.conf

Find the server_name example.com line in the port 80 server block and port 443 server block. Change the server name, and add DNS A record for the domain name:

server_name social.example.com;

Find the following line in the port 80 server block and port 443 server block:

root /home/mastodon/live/public;

Change it to:

root /var/www/mastodon/public;

Find the following two lines:

# ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;

ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

Change them to the following:

ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem; ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key;

Save and close the file. Create the cache directory:

sudo mkdir -p /var/nginx/cache/

Test Nginx configuration:

sudo nginx -t

Reload Nginx for the changes to take effect:

sudo systemctl reload nginx

Step 6: Secure Your Mastodon Site with HTTPS

Use Let’s Encrypt to secure your site with HTTPS.

Install Certbot:

sudo apt install certbot python3-certbot-nginx

Obtain an SSL certificate:

sudo certbot --nginx -d example.com

Set up auto-renewal:

sudo certbot renew --dry-run

Backup and Restore Your Mastodon Database

Creating regular backups ensures data safety. Here’s a simple way to back up.

Back up your database:

sudo -u postgres pg_dump mastodon_production > mastodon_backup.sql

Restore from a backup:

sudo -u postgres psql mastodon_production < mastodon_backup.sql

Solve Mastodon Runtime Errors Like a Pro

Based on our experience in troubleshooting Mastodon errors, try the following to resolve them:

• Check logs with journalctl -u mastodon or tail -f log/production.log.
• Restart services: Restart Nginx or the Mastodon services if needed.
• Update dependencies: Keep Ruby, PostgreSQL, and Mastodon up-to-date.

PostgreSQL Upgrade for Mastodon

If you need to upgrade PostgreSQL, make sure to back up your database before proceeding:

pg_dump -U mastodon mastodon_production > mastodon_backup.sql

Then, follow the upgrade instructions for PostgreSQL, re-importing the data afterward.

Wrapping It Up

Congratulations! You’ve successfully installed and configured Mastodon on your Ubuntu 24.04 server. With your instance now live, you’re ready to welcome users to a new, decentralized social experience. Make sure to monitor your server, keep it updated, and regularly back up your database for smooth and secure operation.