How to Self-Host a Mastodon Instance on a VPS

Self-hosting a Mastodon instance gives you full control over your social media data, moderation policies, and federation settings. Instead of relying on a public instance run by someone else, you own the server and the content it hosts. This article explains how to deploy a Mastodon instance on a Virtual Private Server (VPS) running Ubuntu 22.04. You will learn the exact steps to install, configure, and secure your own Mastodon server.

What You Need Before Starting the Installation

Self-hosting Mastodon requires a VPS with at least 4 GB of RAM and 2 CPU cores. The recommended operating system is Ubuntu 22.04 LTS. You also need a domain name pointed to the VPS IP address. This guide uses Docker Compose to manage Mastodon and its dependencies. Docker Compose simplifies updates and reduces configuration errors. You must have root or sudo access to the VPS.

Steps to Deploy Mastodon on a VPS

Follow these steps in order. Do not skip any step. Each step builds on the previous one.

1. Update the server and install prerequisites
   Log in to your VPS via SSH. Run sudo apt update && sudo apt upgrade -y to update all packages. Then install curl, git, and Docker using sudo apt install curl git docker.io docker-compose-plugin -y. Enable Docker to start on boot with sudo systemctl enable docker.
2. Clone the Mastodon repository
   Navigate to your home directory with cd ~. Clone the official Mastodon repository by running git clone https://github.com/mastodon/mastodon.git. Change into the Mastodon directory with cd mastodon.
3. Copy and edit the environment configuration file
   Run cp .env.production.sample .env.production to create the environment file. Open the file with a text editor like nano: nano .env.production. Set the following values:
   – LOCAL_DOMAIN to your domain name (example: social.yourdomain.com)
   – DB_HOST to db
   – DB_USER to mastodon
   – DB_NAME to mastodon_production
   – DB_PASS to a strong random password
   – SECRET_KEY_BASE, OTP_SECRET, and VAPID_PRIVATE_KEY and VAPID_PUBLIC_KEY can be generated later.
4. Generate secret keys
   Run docker compose run --rm web rake secret three times to generate SECRET_KEY_BASE, OTP_SECRET, and the VAPID keys. For VAPID keys, run docker compose run --rm web rake mastodon:webpush:generate_vapid_key. Copy each output into the .env.production file under the matching variable names.
5. Start the Mastodon services
   Run docker compose up -d to start the database, web, sidekiq, and streaming services in the background. Wait two minutes for the database to initialize.
6. Run the database migration
   Execute docker compose run --rm web rails db:migrate to create the database tables. Then run docker compose run --rm web rails assets:precompile to compile static assets.
7. Configure Nginx as a reverse proxy
   Install Nginx with sudo apt install nginx -y. Copy the sample Nginx configuration from the Mastodon directory: sudo cp ~/mastodon/dist/nginx.conf /etc/nginx/sites-available/mastodon. Edit the file with sudo nano /etc/nginx/sites-available/mastodon. Replace example.com with your domain name. Enable the site by running sudo ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/. Then test the configuration with sudo nginx -t and restart Nginx with sudo systemctl restart nginx.
8. Set up SSL with Let’s Encrypt
   Install Certbot with sudo apt install certbot python3-certbot-nginx -y. Run sudo certbot --nginx -d yourdomain.com and follow the prompts to obtain and install a free SSL certificate. Automatic renewal is enabled by default.
9. Create the admin account
   After the services are running, create your admin user by running docker compose run --rm web rails mastodon:users:create. Provide an email, username, and password. Confirm the account when prompted.
10. Verify the instance is live
    Open a web browser and navigate to https://yourdomain.com. You should see the Mastodon login screen. Log in with the admin credentials you created.

Common Mistakes and How to Avoid Them

Docker Compose Fails with Permission Denied

This error occurs when the current user is not added to the Docker group. Run sudo usermod -aG docker $USER and log out and back in. Then retry the Docker commands.

Mastodon Web Interface Shows a 502 Bad Gateway

The web service may not have started correctly. Check the logs with docker compose logs web. Common causes include missing secret keys in .env.production or a database that has not fully migrated. Re-run the migration step and restart the services with docker compose restart.

Emails Are Not Sent from the Instance

Mastodon requires an SMTP server to send confirmation and notification emails. Add SMTP settings to your .env.production file. For example, if using Mailgun: set SMTP_SERVER=smtp.mailgun.org, SMTP_PORT=587, SMTP_LOGIN=your_login, SMTP_PASSWORD=your_password, and SMTP_AUTH_METHOD=plain. Then restart the services.

Self-Hosted Mastodon vs Managed Mastodon Hosting

Item	Self-Hosted on VPS	Managed Hosting
Cost	VPS monthly fee ($10–$50) plus domain	Monthly subscription ($20–$100)
Control	Full root access, custom moderation	Limited to provider settings
Maintenance	You handle updates, backups, and security	Provider handles maintenance
Scalability	Manual upgrade of VPS resources	Automatic scaling options
Technical skill required	Linux command line, Docker, Nginx	Minimal technical knowledge

Self-hosting gives you complete data ownership and the ability to customize your instance. Managed hosting is easier to start with but limits your control. Choose based on your comfort with server administration.

You can now run your own Mastodon instance with full administrative control. After the instance is live, configure your moderation policies and customize the site title and description in Administration > Site Settings. For ongoing maintenance, set up automatic backups of the PostgreSQL database using docker compose exec db pg_dump -U mastodon mastodon_production > backup.sql and schedule it with a cron job.