How to Set Up a Mastodon Server with Docker

What Is Mastodon?

Mastodon is a free and open-source social networking platform built using Ruby on Rails and modern JavaScript frameworks. It enables anyone to create and operate their own social media server while remaining connected to a larger decentralized network known as the Fediverse.

From a user’s perspective, Mastodon functions similarly to traditional microblogging platforms. Users can:

• Publish posts
• Follow other users
• Share media
• Participate in conversations
• Join communities

Unlike centralized social networks, Mastodon is distributed across thousands of independently operated servers called instances.

Each instance can define its own:

• Rules
• Moderation policies
• Community standards
• Registration requirements

Despite being hosted separately, these servers can communicate with one another through federation.

Why Run Your Own Mastodon Server?

Operating your own Mastodon instance gives you complete control over the platform and its community.

WordPress Web Hosting

Starting From $3.99/Monthly

Buy Now

Full Administrative Control

You decide:

• Who can register
• What content is allowed
• Which moderation policies apply
• How the platform is managed

There is no reliance on decisions made by third-party platform operators.

Connect with the Entire Fediverse

Running your own instance does not isolate you from the rest of the network.

Users on your server can:

• Follow users on other Mastodon instances
• Receive followers from other servers
• Interact across the Fediverse
• Exchange content seamlessly

Build a Private Community

Your instance can be configured for:

• Personal use
• Family members
• Friends
• Organizations
• Clubs
• Professional communities

You control access and registration policies.

Cheap VPS Server

Starting From $2.99/Monthly

Buy Now

Ownership of Data

You control your server and its local data. Federated posts and media can be copied by remote servers; running an instance does not make public or follower-visible content private.

Mastodon Server Requirements

Before beginning installation, ensure the necessary resources are available.

Server Requirements

You need a VPS, cloud server, or dedicated server running one of the following operating systems:

• A currently supported Ubuntu Server release
• A currently supported Debian release

Administrative access is required.

Domain Name

A domain or subdomain is required for your Mastodon instance.

Examples:

Windows VPS Hosting

Remote Access & Full Admin

Buy Now

social.example.com
mastodon.example.com
community.example.com

Other users will access your server through this domain.

Email Service

Mastodon uses email for:

• Account verification
• Notifications
• Password resets
• Administrative alerts

You will need:

• SMTP credentials
• Mail relay service
• Business email provider

Additional Storage

Media uploads consume storage space over time.

Additional storage is recommended if you expect:

• Large media uploads
• Multiple users
• Long-term operation

Planning Your Mastodon Deployment

Before installation, determine:

Single User or Community Instance

Single-user mode is suitable for individuals who want their own presence within the Fediverse.

Multi-user mode is ideal for:

• Organizations
• Communities
• Friend groups
• Public servers

Expected User Count

Resource requirements increase based on:

• Active users
• Uploaded media
• Federation traffic

Small personal servers require significantly fewer resources than public community instances.

Backup Strategy

Implement regular backups for:

• Databases
• Media uploads
• Configuration files

This protects against accidental data loss and server failures.

Prepare the Ubuntu Host

Use a supported Ubuntu release with a non-root administrative account, SSH keys and console recovery access. Keep application files in a dedicated directory and preserve the container image’s non-root execution settings. Membership in the docker group grants effective root-level control of the host.

Install Docker Engine and its Compose plugin using Docker’s official Ubuntu repository instructions. Do not use yum commands on Ubuntu and do not mix the obsolete standalone docker compose package with the current plugin. Confirm both components:

sudo docker version
sudo docker compose version

Run subsequent Docker commands with sudo unless you have deliberately granted the trusted administrator Docker access.

Downloading Mastodon

Navigate to the desired installation directory:

mkdir -p ~/services
cd ~/services

Clone the official Mastodon repository:

git clone https://github.com/mastodon/mastodon

Move into the project directory:

cd mastodon

Before continuing, check out a supported stable release tag from the official release list. Match the Compose configuration and container image tags to that release; do not deploy the development branch accidentally.

Configuring Docker Compose

Use the production Compose example belonging to the selected release. Configure persistent PostgreSQL, Redis and media storage, review health checks and pin compatible image tags. Keep database and Redis ports on the internal container network. Bind web and streaming ports to localhost when a host reverse proxy handles public traffic. Docker-published ports need Docker-compatible filtering, not just ordinary UFW rules.

Open the Docker Compose configuration:

vim docker-compose.yml

Review the configuration and adjust settings as necessary for your environment.

Save the file after making any required modifications.

Preparing the Environment File

The file must contain the configuration produced by setup, including secrets and matching database credentials. An empty file alone is insufficient. Restrict permissions, keep it out of public repositories and store an encrypted off-server copy. Choose the public account domain carefully; changing it after federation begins is not a routine rename.

Ensure the production environment file exists:

touch .env.production

This file stores important configuration values such as:

• Domain name
• SMTP settings
• Database configuration
• Secret keys

Running the Mastodon Setup Wizard

Launch the installation wizard:

docker compose run --rm web bundle exec rake mastodon:setup

The setup process will guide you through configuration options.

Domain Configuration

Provide your server domain:

social.example.com

Single User Mode

The installer will ask whether single-user mode should be enabled.

Choose:

y

for a personal instance.

Choose:

n

for community registrations.

Docker Environment

When asked whether Docker is being used:

y

Database Configuration

Match these values to your Compose database service and generated environment; do not assume defaults are universal:

Host: db
Port: 5432
Database: mastodon_production
User: the dedicated database role configured for Mastodon

Redis Configuration

Typical values include:

Host: redis
Port: 6379

Media Storage

For smaller installations:

Store uploaded files on local storage

is usually sufficient.

Larger deployments may integrate cloud storage providers later.

SMTP Configuration

Provide SMTP credentials:

SMTP_LOGIN=
SMTP_PASSWORD=

The installer can send a test message to verify configuration.

Confirm receipt of the email before continuing.

Administrator Account

The setup wizard will create the initial administrator account.

Record:

• Username
• Password

in a secure location.

Configuring NGINX as a Reverse Proxy

NGINX sits in front of Mastodon and handles incoming web traffic.

Install NGINX:

sudo apt update
sudo apt install nginx

Enable and start the service:

systemctl enable nginx
systemctl start nginx

Create a dedicated configuration file for Mastodon.

The reverse proxy configuration should include:

• Domain configuration
• SSL configuration
• Proxy settings
• Static file handling

Replace all placeholder domains with your actual domain name.

Configure HTTPS and the Reverse Proxy

Use the NGINX template for the selected Mastodon release, including WebSocket/streaming routes, upload limits and the static-file path that matches your deployment. Set the real domain and upstream ports. A generic proxy block may show a login page while federation or streaming still fails.

Point DNS at the server and make HTTP validation reachable. Start with a valid HTTP virtual host; do not reference certificate files that have not been issued. Install the Ubuntu Certbot packages and request the certificate:

sudo apt update
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d social.example.com
sudo nginx -t
sudo certbot renew --dry-run

Replace the example domain. Apply the TLS configuration only after certificate issuance succeeds, then reload NGINX. Keep PostgreSQL and Redis private, and expose only the required web and administrative ports.

Restarting Services

After completing configuration, restart NGINX:

systemctl restart nginx

If necessary, restart Mastodon containers:

docker compose up -d

This applies all configuration changes.

Accessing Your Mastodon Server

Before opening registrations, confirm that web, streaming and background-job services are healthy. Test account verification email, a media upload, a follow and a post across another instance, HTTPS renewal and a backup restore. A working homepage alone is not a complete deployment check.

Open a browser and navigate to:

https://yourdomain.com

The Mastodon login page should appear.

Sign in using the administrator account created during setup.

Accessing the Administration Panel

Administrators can access advanced settings through:

https://yourdomain.com/admin/settings/edit

From the administration interface you can:

• Manage users
• Configure registrations
• Adjust federation settings
• Review moderation actions
• Customize appearance
• Monitor server activity

Maintaining Your Mastodon Instance

Keep Mastodon Updated

Regular updates provide:

• Security fixes
• Performance improvements
• New features

Monitor official release announcements and update accordingly.

Monitor Storage Usage

Media uploads can consume storage rapidly.

Review usage periodically and expand storage when necessary.

Backup Regularly

Create backups of:

• PostgreSQL databases
• Uploaded media
• Configuration files

Store backups securely off-server whenever possible.

Monitor Federation Activity

Review:

• Connected instances
• Blocked domains
• Moderation actions

to maintain a healthy community environment.

Building Your Place in the Fediverse

Running a Mastodon server provides complete control over your social networking environment while maintaining connectivity with the broader Fediverse. Whether you’re creating a personal microblogging platform, hosting a community, or building a social space for an organization, Mastodon offers a flexible and decentralized alternative to traditional social media platforms.

With proper planning, secure configuration, regular maintenance, and reliable infrastructure, a Mastodon instance can become a stable and independent part of the global federated social network ecosystem.