How to Install Mastodon CMS on Ubuntu Linux

Install Dependencies

Installing Mastodon CMS on Ubuntu starts with getting the basic software your server needs, like tools to update your system and build code.

Why do we need this? Your server requires specific software tools to translate and run the code Mastodon is built with.

Your system updates its library of available software and installs 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 needs Node.js version 22.x to run its interactive parts, so we’ll install this JavaScript tool on your Ubuntu server.

Why do we need this? Mastodon requires a current version of Node.js to handle the frontend assets.

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 needs a database to store all user accounts, posts, and settings, so we’ll install PostgreSQL on your Ubuntu server.

Why is a database needed? A database is essential for saving user accounts, posts, and settings.

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 using Ruby on Rails, so we need to install Ruby version 3.3.x on your Ubuntu server using rbenv to make sure it works right.

Why is this necessary? Different software needs specific versions of Ruby to work correctly.

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

The general setup for Mastodon involves downloading the application code and installing the specific libraries your Ubuntu server needs to run it.

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

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

We’ll connect your Mastodon site to the Nginx web server and use systemd to make sure it runs reliably on your Ubuntu server, making it accessible online.

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

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]