How to Install Mastodon CMS on Ubuntu Linux

Mastodon is a free, open-source social networking platform that lets you run your own website. It works like other major social networks, letting you post messages, share images, and follow people. Because you host it yourself, you have full control over your community.

Install Dependencies

First, we need to prepare your server. This installs the basic tools required to run Mastodon.

Why: Your server needs specific software tools to translate and run the code Mastodon is built with.

What happens: Your system updates its library of available software and installs the essential compilers and database connectors.

sudo apt update
sudo apt install software-properties-common dirmngr apt-transport-https ca-certificates redis-server curl gcc g++ make imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git-core libprotobuf-dev protobuf-compiler pkg-config autoconf bison build-essential libssl-dev libyaml-dev libreadline-dev libidn11-dev libicu-dev libjemalloc-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev

Install Node.js and Yarn

Mastodon uses JavaScript to manage its interface. We will use the modern setup script for Node.js 22.x.

Why: Mastodon requires a current version of Node.js to handle the frontend assets.

What happens: Your server gains the ability to run JavaScript applications.

curl -fsSL https://deb.nodesource.com/setup_22.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt install nodejs

How to install Node.js on Ubuntu Linux

Next, enable the Yarn package manager using corepack.

corepack enable

How to install Yarn on Ubuntu Linux

Install PostgreSQL

Mastodon stores all your data in a database. We will use PostgreSQL.

Why: A database is needed to save user accounts, posts, and settings.

What happens: A secure database is created on your server.

sudo apt install postgresql postgresql-contrib
sudo -u postgres psql
CREATE USER mastodon WITH PASSWORD 'your_secure_password';
ALTER USER mastodon CREATEDB;
\q

How to install PostgreSQL on Ubuntu Linux.

Install Ruby

Mastodon is built on the Ruby on Rails framework. We will use rbenv to manage the version.

Why: Different software needs specific versions of Ruby to work correctly.

What happens: You will have a controlled environment to run Ruby version 3.3.x.

sudo adduser --disabled-login --gecos 'Mastodon Server' mastodon
sudo su - mastodon
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
exec bash
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
rbenv install 3.3.6
rbenv global 3.3.6
gem install bundler

General Setup

Now we download the Mastodon code and prepare the system to run it.

Why: This pulls the latest files and installs the specific libraries needed for your server.

What happens: Your server is configured with the Mastodon application files, database structure, and web server settings.

git clone https://github.com/mastodon/mastodon.git ~/live
cd ~/live
bundle config deployment 'true'
bundle config without 'development test'
bundle install
corepack prepare yarn@stable --activate
yarn install
RAILS_ENV=production bundle exec rake mastodon:setup

Web Server and Services

Finally, we link Mastodon to Nginx so people can visit your site, and set up systemd to keep Mastodon running in the background.

Why: Systemd ensures Mastodon starts automatically if your server reboots, and Nginx acts as the front door for internet traffic.

What happens: Your site becomes live on the internet.

sudo cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming
sudo cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
sudo ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/
sudo systemctl restart nginx

How to set up Let’s Encrypt SSL certificate for Nginx on Ubuntu Linux

Open your browser and visit your domain to see your new social network.

[0-9]