How to Install Mastodon CMS on Ubuntu Linux

If you’re looking to set up your own social media server or a community hub, installing Mastodon CMS on Ubuntu Linux is a powerful way to do so. Mastodon is an open-source, decentralized social networking platform that offers users an alternative to mainstream social media. This guide walks you through the entire process of installing Mastodon CMS on an Ubuntu server, ensuring you can launch your own instance smoothly. Before starting, ensure your server meets the minimum requirements, and you have root or sudo privileges to install and configure necessary software.

What You’ll Need

An Ubuntu Linux server (preferably Ubuntu 22.04 LTS or later) with root or sudo access
At least 4GB RAM (8GB recommended for better performance)
Domain name pointed to your server’s IP address (e.g., mastodon.example.com)
Basic knowledge of Linux command line and server administration
Optional: SSL certificate for HTTPS (recommended for security)

Step-by-Step

Update your server: First, update your package list and upgrade existing packages:
```
sudo apt update && sudo apt upgrade -y
```
Install necessary dependencies: Mastodon requires several packages. Install them with:
```
sudo apt install -y git curl gnupg2 apt-transport-https ca-certificates
```
Install Ruby, Node.js, and PostgreSQL: Mastodon depends on Ruby, Node.js, and PostgreSQL. Use the following commands:
```
sudo apt install -y ruby-full nodejs yarn postgresql postgresql-contrib
```
Ensure Node.js is at least version 14. If not, install from NodeSource:
```
curl -fsSL https://deb.nodesource.com/setup_14.x | sudo -E bash -
sudo apt install -y nodejs
```
Create a Mastodon user: For security, create a dedicated user:
```
sudo adduser --disabled-login mastodon
```

Clone the Mastodon repository: Switch to the Mastodon user and clone the code:

sudo -u mastodon git clone https://github.com/mastodon/mastodon.git /home/mastodon/live

Install Ruby dependencies: Use Bundler to install dependencies:

cd /home/mastodon/live
sudo -u mastodon gem install bundler
sudo -u mastodon bundle install --deployment --without development test

Configure database: Switch to PostgreSQL and create a database and user:

sudo -u postgres psql
CREATE USER mastodon CREATEDB;
CREATE DATABASE mastodon_production OWNER mastodon;
\q

Create configuration files: Copy example environment file and edit:

sudo -u mastodon cp /home/mastodon/live/.env.production.example /home/mastodon/live/.env.production
sudo -u mastodon nano /home/mastodon/live/.env.production

Fill in your domain, database, and email details in this file.

Precompile assets and start Mastodon: Run the following commands:

sudo -u mastodon bundle exec rake db:migrate RAILS_ENV=production
sudo -u mastodon bundle exec rake assets:precompile RAILS_ENV=production

Set up a web server and reverse proxy: Use Nginx to serve Mastodon and handle SSL:

sudo apt install -y nginx

Create an Nginx configuration file for your domain:

sudo nano /etc/nginx/sites-available/mastodon

Example configuration:

server {
    listen 80;
    server_name mastodon.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name mastodon.example.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable the site and restart Nginx:

sudo ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Start Mastodon services: Use systemd to run Mastodon background jobs:

sudo -u mastodon bundle exec sidekiq -d -L /home/mastodon/log/sidekiq.log
sudo -u mastodon bundle exec puma -C /home/mastodon/live/config/puma.rb

Secure your site with SSL: Use Certbot to obtain a free SSL certificate:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d mastodon.example.com

Complete setup and verify: Visit https://mastodon.example.com in your browser to ensure the instance loads correctly.

Common Mistakes

Not updating dependencies before starting installation, leading to version conflicts.
Forgetting to set correct permissions on configuration files and directories.
Using incorrect database credentials in the environment file.
Failing to restart services after configuration changes, causing the server to run with outdated configs.
Not securing the server with SSL, risking data interception.

Tips

Use a dedicated subdomain (like mastodon.yourdomain.com) for your instance.
Regularly back up your database and configuration files.
Monitor server resources and logs to troubleshoot issues early.
Automate SSL renewals with Certbot to keep your site secure.
Join Mastodon community forums for support and updates.

Troubleshooting

If your Mastodon instance isn’t loading or services aren’t starting properly, follow these steps:

Check logs: Review logs in /home/mastodon/log and system journal with journalctl.
Verify database connection: Ensure PostgreSQL is running and credentials are correct.
Test services: Use systemctl status for sidekiq and puma to see if they are active.
Inspect Nginx configuration: Run nginx -t to confirm syntax correctness.
Verify SSL certificates: Ensure certbot certificates are valid and renewed.
Restart services: Use systemctl restart for affected services after making changes.

Frequently Asked Questions

1. How secure is Mastodon on Ubuntu?

When properly configured with SSL, firewalls, and regular updates, Mastodon on Ubuntu is quite secure. Always keep your system and Mastodon updated to patch vulnerabilities.

2. Can I run Mastodon on a VPS with limited resources?

Yes, but performance may be limited. For small communities, 4GB RAM and a modest CPU are sufficient, but larger instances benefit from more resources.

3. How do I upgrade Mastodon to a new version?

Pull the latest code from the repository, run bundle install, migrate the database, precompile assets, and restart services.

4. Is it possible to customize Mastodon’s appearance?

Yes, you can modify themes and CSS files within Mastodon’s codebase or use custom CSS overrides to change the look and feel.

5. How do I add custom domains or subdomains?

Configure DNS records for your domain/subdomain, update your Mastodon environment file, and adjust your Nginx configuration accordingly.

6. What should I do if I encounter deployment errors?

Check logs for details, ensure all dependencies are installed, verify database connectivity, and confirm configuration settings are correct.

Installing Mastodon CMS on Ubuntu Linux might seem complex at first, but following this step-by-step guide will help you create a robust, customizable social media platform tailored to your community’s needs. Patience and careful configuration are key to a successful deployment.

How to Install Mastodon CMS on Ubuntu Linux

How to Install Mastodon CMS on Ubuntu Linux

What You’ll Need

Step-by-Step

Common Mistakes

Tips

Troubleshooting

Frequently Asked Questions

1. How secure is Mastodon on Ubuntu?

2. Can I run Mastodon on a VPS with limited resources?

3. How do I upgrade Mastodon to a new version?

4. Is it possible to customize Mastodon’s appearance?

5. How do I add custom domains or subdomains?

6. What should I do if I encounter deployment errors?

Related