How to Host Your Own Mastodon Instance

Mastodon is a decentralized, open-source social network that provides a Twitter-like experience. Hosting your own Mastodon instance allows you to control your community, privacy, and server resources.

This tutorial will guide you through the complete process of setting up a Mastodon instance on a server running Ubuntu 24.04 or Debian 13. We’ll cover everything from system setup to SSL configuration and starting the Mastodon services.

Prerequisites

Before you begin, ensure you have:

A server running Ubuntu 24.04 LTS or Debian 13 with root access.
A domain name (e.g., example.com) or a subdomain pointing to your server’s IP.
An SMTP server or an email delivery service (e.g., SendGrid, Mailgun, or a local MTA like Postfix).

Replace example.com with your actual domain throughout this guide.

Step 1: Initial System Setup

sudo -i

Update System Repositories

Install essential tools and update your package list:

apt update && apt upgrade -y
apt install -y curl wget gnupg lsb-release ca-certificates

Step 2: Install Node.js

Add the official NodeSource repository for Node.js 20:

curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list

Update the package list:

apt update

Install Node.js:

apt install -y nodejs

Step 3: Install PostgreSQL

Add the PostgreSQL APT repository:

wget -O /usr/share/keyrings/postgresql.asc https://www.postgresql.org/media/keys/ACCC4CF8.asc
echo "deb [signed-by=/usr/share/keyrings/postgresql.asc] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/postgresql.list

Update and install PostgreSQL:

apt update
apt install -y postgresql postgresql-contrib

Step 4: Install System Packages

Install all required dependencies for Mastodon:

apt install -y \
  imagemagick ffmpeg libvips-tools libpq-dev libxslt1-dev file git \
  protobuf-compiler pkg-config autoconf bison build-essential \
  libssl-dev libyaml-dev libreadline-dev zlib1g-dev libffi-dev \
  libgdbm-dev nginx nodejs redis-server postgresql certbot \
  python3-certbot-nginx libidn-dev libicu-dev libjemalloc-dev

Step 5: Install Yarn

Enable Corepack to manage Yarn version automatically:

corepack enable

Step 6: Create the Mastodon User

Mastodon should run under a dedicated user for security:

adduser --disabled-password mastodon

Switch to the mastodon user:

su - mastodon

Step 7: Set Up PostgreSQL for Mastodon

Access the PostgreSQL prompt:

sudo -u postgres psql

Inside the PostgreSQL prompt, create a database user:

CREATE USER mastodon CREATEDB;
\q

Exit back to root:

exit

Step 8: Download and Install Mastodon

Switch back to the mastodon user:

su - mastodon

Clone the latest stable Mastodon release:

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)

Step 9: Install Ruby via rbenv

Install rbenv and ruby-build:

git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc

git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

Install the correct Ruby version (as specified in .ruby-version):

RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install
rbenv global $(cat .ruby-version)

Step 10: Install Dependencies

Configure bundler for production and install Ruby and JavaScript dependencies:

bundle config deployment 'true'
bundle config without 'development test'
bundle install -j$(nproc)

yarn install

After the first installation, just use bundle install and yarn install when updating.

Step 11: Generate Configuration

Run the Mastodon setup wizard:

RAILS_ENV=production bin/rails mastodon:setup

This will:

Generate the .env.production configuration file
Precompile assets
Create the database schema

You can edit the .env.production file later for advanced settings.

Step 12: Obtain an SSL Certificate with Let’s Encrypt

Install Certbot and get a certificate:

certbot certonly --nginx -d example.com

Replace example.com with your domain.

Step 13: Configure Nginx

Copy the Mastodon Nginx template:

cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/
rm /etc/nginx/sites-enabled/default

Edit the Nginx config:

nano /etc/nginx/sites-available/mastodon

Make sure to:

Replace example.com with your domain.
Uncomment and set the correct paths for SSL certificates:

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

Allow Nginx to access Mastodon files:

chmod o+x /home/mastodon

Restart Nginx:

systemctl restart nginx

At this point, visiting your domain should show the default Mastodon maintenance page.

Step 14: Set Up Systemd Services

Copy Mastodon’s systemd service files:

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

Edit them to ensure paths and users are correct:

nano /etc/systemd/system/mastodon-*.service

Start and enable the services:

systemctl daemon-reload
systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming

Check service status:

systemctl status mastodon-web mastodon-sidekiq mastodon-streaming

Step 15: (Optional) Tune PostgreSQL for Performance

Use pgTune to generate an optimized postgresql.conf for your server’s specs.

After generating the config, edit:

nano /etc/postgresql/18/main/postgresql.conf

Then restart PostgreSQL:

systemctl restart postgresql

Step 16: Final Steps

Open your domain in a browser – you should see the Mastodon registration page.
Create your first account – this will become the admin account.
Configure your instance settings via the admin panel (available after logging in).
Set up your SMTP server in the .env.production file or via the admin panel to enable email notifications.

Troubleshooting Tips

SSL errors? Re-run certbot or check Nginx config.
Web interface not loading? Check systemctl status mastodon-web.
Email not sending? Verify SMTP settings in .env.production.
Redis not connected? Ensure redis-server is running: systemctl status redis-server.

Maintenance and Updates

To update Mastodon:

su - mastodon
cd live
git pull origin main
RAILS_ENV=production bin/rails db:migrate
RAILS_ENV=production yarn install
RAILS_ENV=production bin/rails assets:precompile
systemctl restart mastodon-*

Happy federating! 🐘

Like my content? Support me with a tip!