In this tutorial, we will guide and walk you through the process of installing Mastodon on a Debian 9 VPS.

Mastodon is an open-source free social network based on the open web protocol. It uses Ruby on Rails for the back-end, and React.js and Redux for the front-end. This social media platform is a lot like Twitter, with a focus towards text and media sharing. This platform being open-source means that you can run a private social network for your and your friends to use privately and with no ads.

This guide should work on other Linux VPS systems as well, but it was tested and written for a Debian 9 VPS. The install process shouldn’t take too long, the longest part being the compilation process. Let’s begin with the installation.

Prerequisites:

  • A Debian 9 VPS.
  • A user account with sudo privileges, or access to the ‘root’ user itself.

Step 1: Install Required Packages

Log in to your VPS via SSH as root or as a sudo user:

ssh userame@IP_Address -p Port_Number

Replace “IP_Address” and “Port_Number” with your server’s respective IP address and SSH port numbers. Additionally, replace “username” with ‘root’ for the root user, or with the name of the admin account you plan to use.

Once logged in, issue the following commands to update all installed packages to their latest available versions:

sudo apt-get update
sudo apt-get upgrade

Install the required packages using the following command:

sudo apt-get install 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 \
zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev \
libidn11-dev libicu-dev libjemalloc-dev

These packages cover all of the requirements for Mastodon, from media conversion, to streaming services.

Step 2: Install Node.js and Yarn

We will install Node.js and Yarn from their official repositories.

Enable the NodeSource repository with the following curl command:

curl -sL https://deb.nodesource.com/setup_8.x | sudo bash -

To install Node.js 8.x LTS Carbon and npm, run this next command:

sudo apt-get install nodejs

Import the Yarn APT repository’s GPG key and enable it by running:

curl -sL https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add -
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

Install Yarn using the following command:

sudo apt-get update && sudo apt-get install yarn

Step 3: Install PostgreSQL

Mastodon can use PostgreSQL as its database back-end.

If the PostgreSQL server is not already installed on your server, you can install the latest PostgreSQL version by executing the following command:

sudo apt-get install postgresql postgresql-contrib

Once the installation is complete, log in to the PostgreSQL shell:

sudo -u postgres psql

Create a new user for the Mastodon instance:

CREATE USER mastodon CREATEDB;

Step 4: Install Redis

Installing Redis is pretty straightforward, just run the following command:

sudo apt-get install redis-server

Step 5: Create a New System User

Create a new system user that will run the Mastodon server:

sudo adduser --home /opt/mastodon --disabled-login --gecos 'Mastodon Application' mastodon

Step 6: Install Ruby

We will install Ruby using the Rbenv script.

Before cloning the rbenv repository, switch to the new mastodon user that we created in the previous step:

sudo su - mastodon

Set up ‘rbenv’ and ‘ruby-build’ with the following commands:

cd
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

Once both ‘rbenv’ and ‘ruby-build’ are set, install the latest Ruby version with:

RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 2.6.1
rbenv global 2.6.1

Update the gem and install bundler so that they work with the version of rbenv that we just installed.:

gem update --system
gem install bundler --no-document

To verify everything is done correctly, use the command ruby --version.

The output should be similar to the following:

ruby --version
ruby 2.6.1p33 (2019-01-30 revision 66950) [x86_64-linux]

Step 7: Setting up Mastodon

The following commands are also run as mastodon user.

Clone the mastodon git repository into the ~/live directory and checkout to the latest stable Mastodon branch:

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

Install the ruby dependencies with the following command:

bundle install -j$(getconf _NPROCESSORS_ONLN) --deployment --without development test

Install the node.js dependencies with:

yarn install --pure-lockfile

Change to the Mastodon installation directory and run the following command to start the setup:

cd ~/live
RAILS_ENV=production bundle exec rake mastodon:setup

The installer will ask you several questions, generate a new app secret, set up the database schema, and compile the assets. This may take a while, depending on your server’s hardware:

Your instance is identified by its domain name. Changing it afterward will break things.
Domain name: your-domain.com

Single user mode disables registrations and redirects the landing page to your public profile.
Do you want to enable single user mode? No

Are you using Docker to run Mastodon? no

PostgreSQL host: /var/run/postgresql
PostgreSQL port: 5432
Name of PostgreSQL database: mastodon_production
Name of PostgreSQL user: mastodon
Password of PostgreSQL user:
Database configuration works! 🎆

Redis host: localhost
Redis port: 6379
Redis password:
Redis configuration works! 🎆

Do you want to store uploaded files on the cloud? No

Do you want to send e-mails from localhost? yes
E-mail address to send e-mails "from": Mastodon <[email protected]>
Send a test e-mail with this configuration right now? no

This configuration will be written to .env.production
Save configuration? Yes

Now that configuration is saved, the database schema must be loaded.
If the database already exists, this will erase its contents.
Prepare the database now? Yes
Running `RAILS_ENV=production rails db:setup` ...

Created database 'mastodon_production'

...

Done!

The final step is compiling CSS/JS assets.
This may take a while and consume a lot of RAM.
Compile the assets now? Yes
Running `RAILS_ENV=production rails assets:precompile` ...

yarn install v1.9.4

...

Using /opt/mastodon/live/config/webpacker.yml file for setting up webpack paths
Compiling…
  Compiled all packs in /opt/mastodon/live/public/packs
  Rendering errors/500.html.haml within layouts/error
  Rendered errors/500.html.haml within layouts/error (2596.9ms)
Done!

All done! You can now power on the Mastodon server 🐘

Do you want to create an admin user straight away? Yes
Username: admin
E-mail: [email protected]
You can login with the password: 7594c5bab89c1f0b0e47438f6074fb02
You can change your password once you login.

When done, switch back to your sudo user by running:

exit

Step 8: Setting up Nginx

Install Nginx and Certbot using the following command:

sudo apt-get install nginx certbot

Once Nginx is installed, copy the Nginx configuration template from the Mastodon installation directory:

sudo cp /opt/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon.conf
sudo ln -s /etc/nginx/sites-available/mastodon.conf /etc/nginx/sites-enabled/mastodon.conf

Run the following command to change the Mastodon installation directory path and the domain name. Don’t forget to replace ‘your-domain.com‘ with your registered domain name:

sudo sed -i 's/home/opt/g' /etc/nginx/sites-enabled/mastodon.conf
sudo sed -i 's/example.com/your-domain.com/g' /etc/nginx/sites-enabled/mastodon.conf

Restart Nginx for changes to take effect:

sudo systemctl restart nginx

Next, use certbot to get a free SSL certificate using Let’s Encrypt:

sudo certbot --nginx -d your-domain.com

The toll will obtain a free Let’s encrypt SSL certificate and reconfigure the Nginx configuration.

Step 9: Setting up systemd Services

Copy the systemd unit files from the Mastodon directory:

sudo cp /opt/mastodon/live/dist/mastodon-*.service /etc/systemd/system/

Run the following command to change the Mastodon installation directory path:

sudo sed -i 's/home/opt/g' /etc/systemd/system/mastodon-*.service

Finally, start and enable the new systemd services:

for i in mastodon-web mastodon-sidekiq mastodon-streaming; do
   sudo systemctl start $i
   sudo systemctl enable $i
done

At this point, you can open your domain in the browser and finish up the Mastodon install.

That’s it. You have successfully installed Mastodon on your Debian 9 VPS. For more information about how to manage your Mastodon installation, please refer to the official Mastodon documentation.


Of course, you don’t have to do any of this if you use one of our Linux VPS Hosting services, in which case you can simply ask our expert Linux admins to setup this for you. They are available 24×7 and will take care of your request immediately.

PS. If you liked this post, please share it with your friends on the social networks using the share shortcuts below, or simply leave a comment down in the comments section. Thanks.