How to Install Mastodon CMS on Ubuntu Linux

Install Dependencies

Getting Mastodon running starts with installing 💿 essential build tools and system updates. The server relies on these packages to compile source code without errors.

Why do we need this? Your server requires specific software tools to translate and run Mastodon’s code, much like a translator helps us understand a new language.

Your system updates its software library to include essential compilers and database connectors. For PostgreSQL, this includes `libpq-dev`.

This process ensures your Ubuntu Linux system has the necessary tools to build and run the Mastodon content management system (CMS).

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 requires Node.js version 22.x to handle its interactive features, so we will install this JavaScript tool on your Ubuntu server. Installing Node.js gives your server the ability to run JavaScript applications, which is crucial for Mastodon's frontend.

Mastodon installation needs a current Node.js version, as Node.js handles the frontend assets. This ensures Mastodon’s website elements, like buttons and text, display and work correctly. Your server then 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 (a tool for managing project dependencies) using corepack.

corepack enable

How to install Yarn on Ubuntu Linux

Install PostgreSQL

Mastodon needs a database to store all its information like user accounts, posts, and settings, which is why we install PostgreSQL on your Ubuntu server. A database is essential for saving all this data securely, ensuring your Mastodon instance functions properly.

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

Since Mastodon is built with Ruby on Rails, we need to install Ruby version 3.3.x on your Ubuntu server using rbenv. Using a specific Ruby version ensures Mastodon and its components work correctly because different software often needs precise versions to function properly.

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

This provides a controlled environment for running Ruby version 3.3.x.

Mastodon's general setup involves downloading the application code and installing specific libraries that your Ubuntu server needs to run Mastodon. This step pulls the latest Mastodon files and sets up necessary software components, configuring your server with Mastodon and Mastodon's database structure.

Running the `git pull` command fetches the most recent Mastodon files and installs the exact libraries required for your Mastodon server to function correctly.

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 connect your Mastodon site to the Nginx web server, which handles incoming internet traffic like a front desk. We also use systemd, a service manager, to ensure Mastodon runs reliably and starts automatically if your server restarts, 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

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

[0-9]