Install Mastodon Social Media App on Ubuntu 18.04

The Mastodon social media application is a self-hosted Twitter alternative you can use to communicate with a private community or the Fediverse.

Mastodon requires a Linux Ubuntu server (version 18.04 or greater). We recommend using a clean operating system (OS) image if possible as the Mastodon installation process requires many dependencies including PostgreSQL, Ruby, and Certbot.

• Install the Mastodon Social Media App
  • Initial Mastodon Setup
  • Install an SSL Certificate
• Getting Started with the Mastodon Social Media App
  • Log into Mastodon
  • Manually Confirm a Mastodon Account
  • Admin Settings
• Learning Mastodon
  • Profile Settings
  • Backups
  • Third Party Integrations

Install the Mastodon Social Media App

1. Log into SSH.
2. Download Node.js from the NodeSource repository (for greater reliability compared to other repos):

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

3. Install Node.js:

   sudo apt-get install -y nodejs

4. Download the Yarn GPG key:

   curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add -

5. Add Yarn to your repo sources file:

   echo "deb https://dl.yarnpkg.com/debian/ stable main" | tee /etc/apt/sources.list.d/yarn.list

6. Update packages:

   apt update

7. Install all dependencies:

   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 yarn libidn11-dev libicu-dev libjemalloc-dev

   
   This will take a few minutes.
8. Mastodon developers recommend using rbenv to ensure you get the latest Ruby versions as soon as possible. However, it requires a dedicated system user. Create a system user without the ability to login from SSH:

   adduser --disabled-login mastodon

9. Switch to the new user:

   su - mastodon

10. Download rbenv:

    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

11. Start the installation:

    RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 2.7.2

    
    This may take a few minutes.

    rbenv global 2.7.2

12. Install Bundler:

    gem install bundler --no-document

13. Switch back to the root user:

    exit

14. Log into PostgreSQL:

    sudo -u postgres psql

    
    The following warning doesn’t affect the installation process: “could not change directory to “/root”: Permission denied.”
15. Create a mastodon database user:

    CREATE USER mastodon CREATEDB;

16. Exit the PostgreSQL CLI:

    \q

17. Switch back to the mastodon system user:

    su - mastodon

18. Download Mastodon and switch to the “live” directory:

    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)

19. Install Ruby and JavaScript dependencies:

    bundle config deployment 'true'

    bundle config without 'development test'

    bundle install -j$(getconf _NPROCESSORS_ONLN)

    
    This might take a few minutes.
20. Install dependencies:

    yarn install --pure-lockfile

    
    If you receive the following error you’ll need to install the latest Yarn version with NPM.
    yarn: error: no such option: --pure-lockfile
    If you don’t receive the error, continue to the next section.
    Return to the root user:

    exit

    
    Remove the Yarn executable:

    rm /usr/bin/yarn

    
    Install Yarn with NPM:

    npm install --global yarn

    
    Log back into the mastodon user:

    su - mastodon

    
    Return to the “live” directory:

    cd live/

    
    Try again:

    yarn install --pure-lockfile

    
    You should see “Done in X.XXs” when it finishes.

Initial Mastodon Setup

Ensure there are no other resource intensive tasks running before continuing (e.g. antivirus scans). 

1. Run the Mastodon setup:

   RAILS_ENV=production bundle exec rake mastodon:setup

2. Type the domain name for your Mastodon instance.
3. Specify whether your instance will be for a single user. Single user mode disables registrations and redirects the landing page (for registrations and logins) to your public profile.
4. Answer “n” for having not used Docker.
5. Accept the default PostgreSQL options unless you have a more complex setup.
6. Accept the default Redis options.
7. Decide whether to store uploaded files “on the cloud.”
8. Decide whether you’ll send emails from your system.
9. Set an email address to send emails. The default is “notifications@.” You’ll also have the option to send a test email.
10. Type “Y” to save the configuration.
11. Prepare the PostgreSQL database.
12. Compile the assets.
13. Pay attention to any notices. For example, we got a recommendation to update caniuse-lite:

    npx browserslist@latest --update-db

14. Select “Y” to create an admin user.
15. Specify the username and email address. Note that this will be a Mastodon social media account. Consider using a name instead of something like “admin.”
16. Save the password in a password manager.
17. Return to the root user.

    exit

18. Copy the downloaded Mastodon NGINX configuration file to your NGINX web server:

    cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon

19. Create a symlink:

    ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon

20. Edit the Mastodon NGINX configuration file:

    nano /etc/nginx/sites-available/mastodon

21. Replace every instance of “example.com” (4). The quickest way in Nano is to type Ctrl + \, “example.com,” Enter, your Mastodon domain, and Enter.
22. Save changes.
23. Restart NGINX:

    systemctl restart nginx

    
    Simply reboot the system if you encounter the error “Failed to start A high performance web server and a reverse proxy server.”

Install an SSL Certificate

Certbot manages Let’s Encrypt SSL certificates for your domain(s). It is one of the dependencies installed earlier.

1. Create an SSL certificate with Certbot, replacing “example.com” with your domain:

   certbot --nginx -d example.com

2. You’ll need to provide an email account, agree to the terms of service, and decide whether to share your email with the Electronic Frontier Foundation (EFF).
3. Choose “1” if you have apps that cannot use an SSL certificate. You can create the redirect manually later.
   Choose “2” to redirect all web traffic to HTTPS (recommended).
4. Copy the downloaded Mastodon service file:

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

5. Reload Systemd:

   systemctl daemon-reload

6. Start Mastodon:

   systemctl enable --now mastodon-web mastodon-sidekiq mastodon-streaming

Getting Started with the Mastodon Social Media App

Log into Mastodon

1. Visit your new Mastodon instance in a web browser.

   

2. Log into Mastodon on the right. When you login you’ll see the following notice at the top: “Waiting for e-mail confirmation to be completed. Didn’t receive confirmation instructions?”

   

3. Check your email and confirm your Mastodon account if you received the email. Then skip to the admin settings. If you didn’t receive the confirmation email, continue to the next section.

Manually Confirm a Mastodon Account

1. If you didn’t receive the confirmation email, log into SSH and the mastodon user.

   su - mastodon

2. Navigate to the “live” directory:

   cd live/

3. Manually confirm the Mastodon account with the following command, replacing “username” with the user you created:

   RAILS_ENV=production bin/tootctl account modify username --confirm

4. If you registered another username from the registration page you can use the following command to grant admin privileges to that user as well:

   RAILS_ENV=production bin/tootctl account modify username --role admin

5. Refresh the Mastodon page.

Admin Settings

Administrators have access to two restricted sections for managing the Mastodon server:

To delete admin accounts you must do one of the following:

• Login as the account and delete it under “Account settings”
• Run the following terminal command as the mastodon system user:

  RAILS_ENV=production bin/tootctl accounts delete username

Learning Mastodon

Select “Back to Mastodon” at the top of the settings page to see the local timeline.

View profile options and create “toots” (messages under 500 characters) on the left. Posts show in the center section. Options on the right display:

• Account notifications
• Different timelines (local or federated)
• Direct messages (DMs)
• Bookmarked toots
• Lists you’ve created
• Profile directory for your instance

Social media managers may prefer an interface that shows multiple timelines at once, similar to TweetDeck.

1. Select “Edit profile” at the top to view profile settings.
2. Select “Preferences” > “Appearance.”
3. Check the box for “Enable advanced web interface.”
4. Save changes.
5. Select “Back to Mastodon” to see the multiple columns available.

Profile Settings

Select “Profile” > “Appearance” to edit the following:

• Display name
• Bio
• Header image
• Avatar (profile image)

Profile metadata: these links are listed under your profile. The label is the link title and the content is the URL.

At the bottom you can transfer or delete your account.

Backups

Select “Import and export” > “Data export” to download an ActivityPub compliant CSV file including your:

• Posts
• Accounts followed
• Lists
• Followers
• Blocked users
• Muted users
• Blocked domains
• Bookmarks

Third Party Integrations

Applications integrated with your Mastodon account show in “Account” > “Authorized apps.” You’ll have the “Web” app by default. Here’s our guide on integrating WordPress with Mastodon.

Web developers can create apps with the Mastodon API in the Development page.Check back often to learn more about Fediverse apps.