Mastodon is free and open-source software for running self-hosted social networking services.
It offers microblogging features similar to the service X (formerly Twitter), provided by a variety of independently operated nodes called instances – each with its own code of conduct, terms of use, privacy policies, privacy settings, and moderation guidelines.
This guide focuses on installation on a Debian-based distro. Examples include Debian and Ubuntu. The instructions vary depending on the operating system used.
To set up a Mastodon instance on your server, you need the following:
- Domain
- Linux-based server
- Mail server
Then update your packages with the following command:
apt update && apt upgrade -y
Next, install Mastodon's dependencies:
# System repositories
apt install -y curl wget gnupg apt-transport-https lsb-release ca-certificates
# Node.js
curl -sL https://deb.nodesource.com/setup_16.x | bash -
# PostgreSQL
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
After installing Mastodon's dependencies, install the necessary system packages with these two commands:
apt update
apt install -y \
imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git-core \
g++ libprotobuf-dev protobuf-compiler pkg-config nodejs gcc autoconf \
bison build-essential libssl-dev libyaml-dev libreadline6-dev \
zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev \
nginx redis-server redis-tools postgresql postgresql-contrib \
certbot python3-certbot-nginx libidn11-dev libicu-dev libjemalloc-dev
Let the packages install; this may take some time. Then configure yarn, the package manager for the previously installed Node.js:
corepack enable
yarn set version stable
We create a separate user because managing Ruby versions is much easier this way. First, create a user named mastodon with login disabled. Then switch to the mastodon user. Use these commands:
# You can leave the fields empty
adduser --disabled-login mastodon
su - mastodon
Now install the Ruby manager rbenv, which greatly simplifies managing Ruby versions. Install it with these commands:
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
cd ~/.rbenv && src/configure && make -C src
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
After running these commands, you can install Ruby and bundler at the same time:
RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.0.3
rbenv global 3.0.3
gem install bundler --no-document
This may take a while, so enjoy a tea or coffee in the meantime. Afterward, you’re done with setup and can return to the root user with exit.
Mastodon uses PostgreSQL as its database system. Configure it as follows:
sudo -u postgres psql
At the PostgreSQL prompt, enter:
CREATE USER mastodon CREATEDB;
\q
Switch back to the mastodon user:
su - mastodon
Then download the latest Mastodon version with git using these two commands:
git clone https://github.com/tootsuite/mastodon.git live && cd live
git checkout $(git tag -l | grep -v 'rc[0-9]*$' | sort -V | tail -n 1)
Next, install the latest Ruby and JavaScript dependencies:
bundle config deployment 'true'
bundle config without 'development test'
bundle install -j$(getconf _NPROCESSORS_ONLN)
yarn install --pure-lockfile
Now create your Mastodon configuration file with:
RAILS_ENV=production bundle exec rake mastodon:setup
If database setup fails, please log into your Postgres database with sudo -u postgres psql and follow this guide:
https://gist.github.com/amolkhanorkar/8706915
Then switch back to the root user with exit.
Now comes the tricky part: the web server configuration. First, create an A record and/or AAAA record in your DNS pointing directly to your server. Alternatively, you can point the root record to your server.
Then copy and enable the Mastodon web server configuration with these two commands:
cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon
Edit the file /etc/nginx/sites-available/mastodon with a text editor like vim or nano and replace example.com with your desired domain.
Next, obtain an SSL certificate for your domain easily with:
certbot --nginx -d <your domain>
Enter your domain. You will be asked for some information. At the end, you will be asked whether HTTP requests should be automatically redirected to HTTPS – we recommend enabling this.
Finally, create a Mastodon system service. This is quite straightforward. Copy the default service configuration into your distribution’s service directory:
cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/
Enable and start your new services with these two commands:
systemctl daemon-reload
systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming
After a reboot, your setup should be complete. Enjoy your instance!