Mastodon is a decentralized, open-source microblogging platform designed to empower communities with full control over their data and customization. Its federated architecture makes it an ideal choice for those who value privacy, scalability, and independence from traditional social media platforms. This guide walks you through deploying, configuring, managing, and optimizing a self-hosted Mastodon instance.
Installing Mastodon
📦 Docker/Docker Compose Setup
Docker is the preferred method for quickly deploying Mastodon. Below is a docker-compose.yml file tailored for Mastodon. It configures the necessary services, such as the Mastodon web app, streaming service, and background worker, along with PostgreSQL and Redis.
version: '3.7'
services:
db:
image: postgres:15
container_name: mastodon_db
environment:
POSTGRES_USER: mastodon
POSTGRES_PASSWORD: changeme
POSTGRES_DB: mastodon_production
volumes:
- db_data:/var/lib/postgresql/data
restart: always
redis:
image: redis:7
container_name: mastodon_redis
command: redis-server --save 60 1 --loglevel warning
volumes:
- redis_data:/data
restart: always
web:
image: tootsuite/mastodon:latest
container_name: mastodon_web
env_file: .env.production
ports:
- "3000:3000"
depends_on:
- db
- redis
command: bundle exec rails s
restart: always
streaming:
image: tootsuite/mastodon:latest
container_name: mastodon_streaming
env_file: .env.production
ports:
- "4000:4000"
depends_on:
- web
command: node ./streaming
restart: always
sidekiq:
image: tootsuite/mastodon:latest
container_name: mastodon_sidekiq
env_file: .env.production
depends_on:
- web
command: bundle exec sidekiq
restart: always
volumes:
db_data:
redis_data:
Deploy the stack using the following command:
docker-compose up -d
This will initialize Mastodon and its dependencies. Ensure you create the .env.production file with your configurations before starting the containers.
🚀 Manual Installation
For those deploying Mastodon manually, follow these steps:
- Clone the Mastodon repository:
git clone https://github.com/mastodon/mastodon.git
cd mastodon
git checkout $(git tag | tail -n 1)
- Install required dependencies:
sudo apt update
sudo apt install -y git curl libxml2-dev libxslt1-dev file imagemagick \
libprotobuf-dev protobuf-compiler pkg-config build-essential \
libssl-dev libyaml-dev libreadline-dev libidn11-dev libicu-dev zlib1g-dev \
libpq-dev postgresql postgresql-contrib redis
-
Configure the database and environment settings. Refer to Mastodon’s official documentation.
-
Start the application:
bundle exec rails s
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
To serve Mastodon via Nginx, create the following configuration file at /etc/nginx/sites-available/mastodon:
server {
listen 80;
server_name example.com;
root /path/to/mastodon/public;
location ~ ^/(assets|packs) {
add_header Cache-Control "public, max-age=31536000, immutable";
}
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
}
location /api/v1/streaming {
proxy_pass http://127.0.0.1:4000;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
proxy_buffering off;
}
}
Enable the configuration and restart Nginx:
sudo ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/
sudo systemctl restart nginx
🔒 SSL/TLS Setup
Use Let's Encrypt to secure Mastodon with HTTPS:
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d example.com
Automate SSL renewals:
sudo systemctl enable certbot.timer
sudo systemctl start certbot.timer
🛠️ Testing and Reloading Nginx
Verify the configuration and reload Nginx:
sudo nginx -t
sudo systemctl reload nginx
Logging and Debugging Mastodon
🗃️ Enabling Debug Logs
To enable debug logs, update your .env.production file:
RAILS_LOG_LEVEL=debug
Restart Mastodon services to apply changes:
docker-compose restart
📄 Viewing Logs
For Docker installations, view logs with:
docker logs mastodon_web
docker logs mastodon_streaming
docker logs mastodon_sidekiq
For manual setups, logs are located in log/production.log.
🛠️ Troubleshooting Common Issues
-
Database Errors: Check PostgreSQL logs at
/var/log/postgresql/. -
Redis Connection Issues: Ensure Redis is running:
sudo systemctl restart redis
📤 Exporting Logs
Forward logs to an ELK Stack by configuring Filebeat or Logstash to watch Mastodon's log files.
Backup and Restore
🗂️ File-Based Backups
Backup Mastodon's configuration and media files:
tar -czvf mastodon_backup.tar.gz /path/to/mastodon
🔄 Database Backups
Export the PostgreSQL database:
pg_dump -U mastodon mastodon_production > mastodon_db_backup.sql
Restore the database:
psql -U mastodon mastodon_production < mastodon_db_backup.sql
📅 Automated Backup Scripts
Set up a cron job to automate backups:
crontab -e
Add the following line for daily backups:
0 2 * * * /usr/bin/pg_dump -U mastodon mastodon_production > /backups/mastodon_db_backup.sql
Updating and Upgrading Mastodon
⬆️ Updating Docker Images
Update Mastodon Docker images:
docker-compose pull
docker-compose down
docker-compose up -d
🛠️ Manual Updates
For manual installations, pull the latest code and run migrations:
git pull
bundle install
RAILS_ENV=production bundle exec rails db:migrate
🔍 Checking for Updates
Monitor Mastodon’s GitHub repository for new releases:
git fetch --tags
Leveraging Mastodon’s Unique Features
🔧 Enabling APIs
Enable Mastodon APIs in .env.production and restart the app:
LOCAL_DOMAIN=example.com
Access the API using curl:
curl -X GET https://example.com/api/v1/statuses \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
🌟 Advanced Configurations
Customize features like federation by modifying config/settings.yml:
federation:
reject_media: false
Wrapping Up
By following this guide, you can successfully deploy and manage a self-hosted Mastodon server, leveraging the platform's flexibility and customization. Dive into the provided examples to fully unlock its capabilities and enjoy the freedom of owning your microblogging platform.
