Installing Mastodon from Source on Ubuntu: Step-by-Step Guide
Running your own decentralized social community gives you direct control over your server environment, data, and moderation policies. If you are comparing independent community options or exploring Forum Software Server Requirements Compared (phpBB, MyBB, Flarum, Discourse), hosting Mastodon directly on your own infrastructure is an option. According to the Installing from source - Mastodon documentation, setting up Mastodon from source on a machine running Ubuntu 24.04 provides a complete, bare-metal deployment. This guide walks you through every phase of the process, including system repositories, database creation, Ruby toolchains, and background system services.
Prerequisites and Repository Configuration
Before beginning the installation, ensure you have root access to a system running Ubuntu 24.04 (or Debian 13), an assigned domain name or subdomain such as example.com, and an active SMTP server or email delivery service. Switch to the root user by running sudo -i.
First, install the necessary baseline tools for managing keys and repositories:
apt install -y curl wget gnupg lsb-release ca-certificates
Next, configure the NodeSource repository for Node.js along with the PostgreSQL repository. Add the signing keys and source lists as specified in the Installing from source - Mastodon documentation:
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_24.x nodistro main" | tee /etc/apt/sources.list.d/nodesource.list
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
Installing System Packages and Preparing the User
Update your apt lists and install all the necessary build tools, libraries, and core servers:
apt update
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
Enable Corepack so that the required Yarn release installs properly, then create the system user under which Mastodon processes will operate:
corepack enable
adduser --disabled-password mastodon
Setting Up PostgreSQL
Mastodon requires a dedicated database user. In a straightforward setup, ident authentication allows the local Linux user named mastodon to access PostgreSQL without a separate password.
- Launch the PostgreSQL interactive terminal as the administrative postgres user:
sudo -u postgres psql - Execute the user creation query:
CREATE USER mastodon CREATEDB; - Exit the shell:
\q
For server performance tuning, you can optionally generate values using pgTune by selecting "Web application" for DB Type and applying the suggested settings inside /etc/postgresql/18/main/postgresql.conf before issuing systemctl restart postgresql.
Fetching Mastodon Code and Building Ruby
Switch over to the dedicated mastodon user to fetch the source repository and compile dependencies:
su - mastodon
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)
To ensure consistent Ruby runtime environments, install rbenv and ruby-build inside the user's home profile:
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
RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install
Compiling Dependencies and Generating Configuration
Once Ruby is ready, configure bundler and install the project gems alongside JavaScript assets:
bundle config deployment 'true'
bundle config without 'development test'
bundle install
yarn install
Launch the interactive configuration helper by executing RAILS_ENV=production bin/rails mastodon:setup. This wizard compiles assets, prepares database schemas, and produces your .env.production configuration file. When the wizard completes, return to your root shell by typing exit.
Web Server and SSL Setup
If you are maintaining secure transport for your community as outlined in our guide to Free HTTPS for Your Forum With Let's Encrypt, obtain your TLS certificate using Certbot:
certbot certonly --nginx -d example.com
Next, copy the provided Nginx template into place, create the enabled symlink, and clear the distribution default configuration:
cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon
rm /etc/nginx/sites-enabled/default
Edit /etc/nginx/sites-available/mastodon to substitute your actual domain name in place of example.com, and uncomment the directives pointing to /etc/letsencrypt/live/example.com/fullchain.pem and /etc/letsencrypt/live/example.com/privkey.pem. Ensure Nginx's www-data user can traverse files by running chmod o+x /home/mastodon, then reload Nginx with systemctl restart nginx.
Enabling Systemd Background Services
To manage application lifecycles cleanly, copy the systemd units into the system directory and activate them:
cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming
These commands launch the Puma web layer, the Sidekiq background queue, and Node-based streaming server units so they start automatically across reboots.
Sources
Published October 28, 2026. No affiliate links on this page. Facts come from the sources linked above; check them for updates.