How to Install Mastodon CMS on Ubuntu Linux

Install Dependencies

To install Mastodon CMS Ubuntu dependencies, you need to update your system packages and set up essential build tools like compilers and database connectors. These tools allow your server to build and compile the software source code without running into errors during the setup process.

Do this first on a fresh server. Installing the build tools now means later steps, such as compiling Ruby, don’t stop halfway with missing-library errors.

Your server requires specific software tools to compile Mastodon’s source code without errors.

Mastodon is not a ready-made program. It is built from source on your own machine, and that needs compilers, image and video libraries, and database client libraries.

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).

1. Connect to your server over SSH.
2. Run the commands in this section. They refresh the package list, apply pending updates, and install the💿 build tools.
3. If the installer asks you to confirm, type Y and press Enter. The package output scrolls past, and you should be back at the prompt with no error messages when it finishes.
4. If the update installed a new kernel, restart the🔄 server before you continue.

If a package can’t be found, the package list is usually out of date. Run the update step again and check that your server has internet access.

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 libidn-dev libicu-dev libjemalloc-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev

Install Node.js and Yarn

To install Node.js and Yarn for your Mastodon CMS Ubuntu server, you must download and run the setup script for Node.js version 22.x. This JavaScript runtime environment manages the frontend assets and interactive website interface elements that users see when they visit your site.

The default Ubuntu repositories often carry an older Node.js release, so you add the Node.js 22.x repository first and then install from it. That way you get the version Mastodon expects.

Node.js handles Mastodon’s frontend assets and website interface elements.

Without it, the web interface can’t be built, and the site would load without its pages and styling.

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.

1. Confirm Node.js is installed by checking its version. It should report a 22.x number.
2. Run the corepack command in this section. Corepack ships with Node.js, so you don’t need to install Yarn from a separate source.
3. Check the Yarn version afterwards. If it prints a version number, Yarn is ready.

If the corepack command is refused with a permissions error, run it with sudo.

sudo corepack enable

How to install Yarn on Ubuntu Linux

Install PostgreSQL

To install PostgreSQL for your Mastodon CMS Ubuntu server, you set up a secure relational database that stores all user accounts, posts, and system settings. This database is essential for keeping your instance data safe and ensuring your server functions properly at all times.

Mastodon only supports PostgreSQL. You install the server, then create a database user for Mastodon so the app doesn’t connect with an administrator account.

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

Everything people see on your instance lives here, apart from uploaded media files. Back it up regularly once the server is in use.

A secure database is created on your server.

1. Install PostgreSQL with the commands in this section.
2. Open the PostgreSQL prompt as the postgres system user and create the database user for Mastodon, as shown.
3. Leave the prompt when you are done. The service should be running, and it should start by itself after a reboot.

Only the local server needs to reach the database, so don’t open the PostgreSQL port to the internet.

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

To install Ruby for your Mastodon CMS Ubuntu server, you use rbenv to set up Ruby version 3.3.x. Because the platform runs on Ruby on Rails, having this exact version installed ensures that the backend code and all its components work together correctly without breaking.

It is best to run Mastodon under its own unprivileged user rather than your admin account or root. Install rbenv for that user, so Ruby sits in that user’s home directory and doesn’t touch the system Ruby.

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

Mastodon pins the Ruby versions it supports. A version that is too old or too new can fail while installing gems or when the app starts.

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

1. Switch to the Mastodon user account.
2. Install rbenv and its Ruby build plugin with the commands in this section.
3. Install Ruby 3.3.x. Ruby is compiled from source, so this takes several minutes with little output. Don’t interrupt it.
4. Check the Ruby version. It should report 3.3.x.

If the Ruby build fails, the cause is usually a missing library or too little memory. Check the last lines of the error and make sure the build tools from the first section are installed. Adding swap space helps on small servers.

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.

This is the longest part of the install. You work as the Mastodon user, fetch the code, install the Ruby and JavaScript libraries, and then run the setup process that asks for your settings.

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

Check out a stable release rather than the development branch, so you run tested code.

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

1. Download the⬇️ Mastodon code and move into its folder, using the commands in this section.
2. Install the💿 Ruby and JavaScript libraries. This can take a few minutes.
3. Start the setup process. It asks for your domain name, database details, email settings, and whether to create an admin account.
4. Enter your answers. The domain name can’t be changed after people start using your instance, so type it carefully.
5. Let the process finish. It creates the database tables and builds the frontend assets, and it prints the admin account details at the end.

Write down the admin username and password it shows. If a step stops with an error, fix the cause and run the same step again.

git clone https://github.com/mastodon/mastodon.git live
cd live
git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1)
bundle config deployment 'true'
bundle config without 'development test'
bundle install
yarn install
RAILS_ENV=production bundle exec rake mastodon:setup

Web Server and Services

To configure your web server and services for Mastodon CMS Ubuntu, you connect your site to Nginx (a web server that handles incoming internet traffic) and use systemd (a service manager). This setup ensures your site goes live on the internet and starts automatically if your server reboots.

Nginx needs a site configuration for your domain, and systemd needs service files for Mastodon’s web, background job and streaming processes. Get an HTTPS certificate too, because Mastodon instances need HTTPS to work with other servers.

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

Without these, Mastodon would only run while your terminal session stays open, and visitors couldn’t reach it on the standard web ports.

Your site becomes live on the internet.

1. Install Nginx if it isn’t already on the server.
2. Copy in the Nginx site configuration and edit it so it uses your own domain name.
3. Request a certificate for your domain and update the configuration to use it.
4. Test the Nginx configuration, then reload Nginx. If the test reports a problem, it names the file and line to fix.
5. Copy the systemd service files into place, then enable and start the services, as shown in this section.

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.

You should see the Mastodon welcome page. Sign in with the admin account you created during setup, then open the administration settings to set your server name, rules and registration options.

If the page doesn’t load, check these in order:

• The DNS record points to your server’s IP address.
• Ports 80 and 443 are open.
• Nginx and all three Mastodon services are running.

Check the service logs for the exact error.