Mastodon Server on VPS: Docker Setup Guide

Updated 7 November 2026 · Standard formula, shown below

This guide walks you through deploying your own Mastodon server on a VPS using Docker, giving you full control over your social media data and community. You’ll end up with a working, federated Mastodon instance that you can customize and manage. Before starting, you’ll need a VPS with at least 2GB of RAM, a domain name pointed to your server’s IP, and basic comfort with the command line.

What You’ll Need

A VPS running Ubuntu 22.04 or Debian 12 (2GB RAM minimum, 4GB recommended)
A domain name (e.g., social.example.com) with an A record pointing to your server’s IP address
SSH access to the server (root or user with sudo privileges)
Docker and Docker Compose installed (we’ll cover this)
An email address for the admin account (for notifications)

Step-by-Step

Update your system and install prerequisites. SSH into your server and run:
```
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git
```
Install Docker and Docker Compose. Use the official convenience script for Docker:
```
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```
Then install Docker Compose plugin (or standalone binary if you prefer):
```
sudo apt install -y docker-compose-plugin
```
Verify with docker --version and docker compose version.
Clone the Mastodon repository. Create a directory and clone the official Mastodon Docker setup:
```
mkdir ~/mastodon && cd ~/mastodon
git clone https://github.com/mastodon/mastodon.git .
```
Alternatively, download the docker-compose.yml and .env.production.sample directly from the Mastodon repository.
Configure environment variables. Copy the sample environment file:
```
cp .env.production.sample .env.production
```
Edit it with your favorite text editor (e.g., nano .env.production). Set the following essential values:
- LOCAL_DOMAIN – your domain (e.g., social.example.com)
- SECRET_KEY_BASE – generate with openssl rand -hex 64
- OTP_SECRET – generate with openssl rand -hex 64
- VAPID_PRIVATE_KEY and VAPID_PUBLIC_KEY – generate with openssl ecparam -name prime256v1 -genkey -noout -out vapid_key.pem and then extract the keys using a small script (see Mastodon docs). Alternatively, run docker compose run --rm web rake mastodon:setup later to auto-generate.
- DB_HOST=db, DB_USER=mastodon, DB_NAME=mastodon, DB_PASS= (set a strong password)
- REDIS_HOST=redis
- Set SMTP_SERVER, SMTP_PORT, SMTP_LOGIN, SMTP_PASSWORD, SMTP_FROM_ADDRESS if you want email notifications (optional but recommended).
Build and start the services. Run:
```
docker compose build
```
This will take a while. Then start the database and Redis first:
```
docker compose up -d db redis
```
Wait a few seconds, then run the database migrations:
```
docker compose run --rm web rake db:migrate
```
Then create the admin user (you’ll be prompted for username, email, and password):
```
docker compose run --rm web rake mastodon:setup
```
This will also generate secrets if you didn’t set them. Finally, start all services:
```
docker compose up -d
```
Set up a reverse proxy with HTTPS (using Nginx). Install Nginx:
```
sudo apt install -y nginx
```
Create a site configuration file, e.g., /etc/nginx/sites-available/mastodon, with a server block that proxies to the Mastodon web service on port 3000. Use a config similar to the one in the Mastodon docs (or use Caddy which auto-generates SSL). Then enable the site and reload Nginx:
```
sudo ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```
Install Certbot for SSL:
```
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d social.example.com
```
Follow the prompts to obtain a certificate.
Access your instance. Visit https://social.example.com in your browser. You should see the Mastodon sign-up page. Log in with the admin credentials you created earlier to access the admin panel.

Common Mistakes

Not setting the correct LOCAL_DOMAIN. This must match the domain you use to access the instance, including subdomain. If it’s wrong, links and federation break.
Using weak database passwords. Always set a strong DB_PASS; otherwise, your instance is vulnerable.
Skipping the reverse proxy. Mastodon’s web service runs on port 3000; you need Nginx or Caddy to serve it on port 443 with HTTPS. Directly exposing port 3000 is insecure and not supported.
Not generating VAPID keys. Without them, push notifications won’t work. Use the setup rake task to generate them.
Forgetting to open firewall ports. Ensure ports 80 and 443 are open in your VPS firewall (UFW or cloud provider security group).

Tips

Use a subdomain like social.example.com so you can host other services on the same domain.
Back up your .env.production file and the database regularly. You can use docker compose exec db pg_dump to create database backups.
Monitor disk space; media files can accumulate quickly. Set up a cron job to run docker compose run --rm web rake mastodon:media:remove periodically.
Keep your instance updated by pulling the latest Mastodon images and rebuilding.
Consider using a managed PostgreSQL or Redis service if you prefer not to run them in Docker, but the default setup is fine for small instances.

Troubleshooting

Web page doesn’t load. Check that all containers are running with docker compose ps. If the web container is exiting, look at logs with docker compose logs web. Common issue: missing secrets or database connection errors.
Cannot connect to the database. Ensure the db container is up and the DB_PASS matches what’s in the database container’s environment. You can check with docker compose exec db psql -U mastodon -l.
SSL certificate not working. Verify that your domain resolves to the server’s IP. Run dig social.example.com from your local machine. Also, ensure port 80 is accessible for Certbot’s HTTP challenge.
Emails not sending. Check your SMTP settings in .env.production. Test with docker compose run --rm web rails runner 'ActionMailer::Base.mail(from: "test@example.com", to: "you@example.com", subject: "Test", body: "Test").deliver'.
Federation issues. Ensure your instance is reachable from the internet on port 443. Use an online tool to check if your domain is federating correctly.

Frequently Asked Questions

How much does it cost to run a Mastodon server?

You’ll need a VPS, which typically costs $5-$20 per month depending on resources. The software itself is free.

Can I migrate an existing Mastodon account to my new server?

Yes, you can use the account migration feature in Mastodon settings to move followers from an old account to your new one.

Do I need to be a programmer to do this?

Basic command-line skills are enough. You follow the steps, and the setup scripts handle most of the complexity.

How do I back up my Mastodon server?

Back up the .env.production file and the PostgreSQL database. You can use docker compose exec db pg_dump -U mastodon mastodon > backup.sql.

Can I use Docker Hub images instead of building from source?

Yes, the official Mastodon Docker images are available on Docker Hub. The docker-compose.yml in the repository uses them by default.

What’s the difference between a single-user and multi-user instance?

Single-user means only you have an account; multi-user allows others to sign up. You can control this with the OPEN_REGISTRATION setting in .env.production.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.