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.
Table of Contents
- 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
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 <firstname.lastname@example.org> 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@example.com 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:
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.