How to Setup Your Own Mastodon Instance

Mastodon Logo
Mastodon Logo

If you want to setup and run an instance of Mastodon for your own personal use, this guide will help you do that for relatively cheap. Once your instance grows you’ll need to look at other options, like cloud hosting, but this will get you up and running on your own hardware.

There are a number of things you need to have in place before you can run and access the Mastodon Web UI.

  • Docker
  • Domain Name
  • CloudFlare (optional)
  • Nginx
  • Mastodon Docker Compose File

Docker

This guide assumes you know what Docker is and have it up and running on a PC of your own. Using Docker makes setting up all of the resources needed extremely easy to run. Once you have a running environment, you can analyze what was created and customize as you feel fit. Docker also makes it extremely easy to migrate to another server or to cloud hosting.

Domain Name

First, you need to purchase a domain name from somewhere like hover.com. The domain name cannot be changed once you setup Mastodon so carefully decide what it will be before you run the setup script.

Cloudflare

This step is optional, but, highly recommended. Running a social media server could invite unexpected attention from people that may not view things the same way your instance does and could open you to risks. Use Cloudflare to proxy your site. This helps with a few things:

  • Your real servers IP address is hidden by Cloudflare and this gives you much better security. This also allows you to easily point to another server IP address if needed.
  • All traffic is proxied through Cloudflare so you can enable a WAF (Web Application Firewall) to help keep bad guys from doing nefarious things.
  • DDOS protection. If your instance becomes the destination of a DDOS attack, Cloudflare has options to help.
  • TLS Certificates. In combination with Nginx, you can have Cloudflare manage your TLS certificates for your domain.

Here is a how-to for getting started with Cloudflare: https://developers.cloudflare.com/dns/zone-setups/full-setup/setup/

Nginx

You need a service that can take requests from the internet and route it to your Mastodon server. Nginx works great for this. Even better, there is a group of developers that maintain an application called Nginx Proxy Manager that runs a web UI in a Docker container, making it dead simple to setup and configure.

Here is a how-to for getting started with Nginx Proxy Manager: https://nginxproxymanager.com/guide/#project-goal

Mastodon Docker Compose File

Once you have your domain name figured out and an Nginx proxy ready to direct traffic with, you can run the initial setup of the Mastodon services.

First download the docker-compose file from the official source code to a folder on the server that will run your resources. https://github.com/mastodon/mastodon/blob/main/docker-compose.yml

Then, to start the initial setup, run this command from a terminal:

docker-compose run --rm -v $(pwd)/.env.production:/opt/mastodon/.env.production web bundle exec rake mastodon:setup

This will walk you through a number of questions that you need to answer. Once completed, you’ll have a .env.production file saved to the same folder as your docker-compose.yml file that has all of the properties set from the questions you answered.

When setup is complete, shut down the docker stack and rerun with the following commands:

docker compose down
docker compose up -d

If everything starts successfully, you should have a Docker Stack with 5 containers running:

Wrapping It Up

Lastly, now that your container stack is up and running, you need to point your domain names DNS, or Cloudflare, to the external IP address that Nginx Proxy Manager is listening on and Nginx Proxy Manager to the internal IP address of the server that the containers are running on. If successful, you can now go to your browser, type in your domain name, and you should see the home page for your Mastodon instance. From there, you can complete the setup and start sharing with the world.