Mastodon Deployment & Usage Guide

1. Prerequisites

System Requirements

Operating System: Linux, macOS, or Windows (Linux recommended for production)
Ruby: Version 3.2 or higher
PostgreSQL: Version 14 or higher
Redis: Version 7.0 or higher
Node.js: Version 20 or higher
Git: For cloning the repository
ImageMagick: For media processing
FFmpeg: For video processing

Optional Dependencies

libidn: For Internationalized Domain Names (IDNA)
libicu: For Unicode support
libpq-dev: For PostgreSQL development headers
libprotobuf: For ActivityPub protocol support

Accounts & Services

Email service: SMTP server for sending notifications
Object storage: S3-compatible service for media attachments (optional but recommended for production)
Domain name: For your Mastodon instance

2. Installation

Clone the Repository

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

Install Dependencies

Ruby dependencies:

bundle install

JavaScript dependencies:

yarn install

Database setup:

# Create the database
bundle exec rails db:create

# Run migrations
bundle exec rails db:migrate

# Precompile assets
bundle exec rails assets:precompile

3. Configuration

Environment Variables

Create a .env.production file with the following essential variables:

# Database configuration
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mastodon_production
DB_USER=mastodon
DB_PASS=your_password

# Redis configuration
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_password

# Application secrets
SECRET_KEY_BASE=$(bundle exec rails secret)
OTP_SECRET=$(bundle exec rails secret)

# Instance configuration
LOCAL_DOMAIN=your-domain.com
LOCAL_HTTPS=true

# Email configuration
SMTP_SERVER=smtp.your-email-provider.com
SMTP_PORT=587
SMTP_LOGIN=your-email@example.com
SMTP_PASSWORD=your-password
SMTP_FROM_ADDRESS=notifications@your-domain.com

# File storage (optional - for S3)
S3_ENABLED=true
S3_BUCKET=your-bucket-name
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
S3_REGION=your-region
S3_HOSTNAME=s3.your-region.amazonaws.com

Additional Configuration Files

config/database.yml: PostgreSQL connection settings config/redis.yml: Redis connection settings
config/environments/production.rb: Production environment settings

Generate Configuration

Run the interactive setup wizard:

RAILS_ENV=production bundle exec rails mastodon:setup

This will guide you through:

Domain name configuration
Database setup
Redis configuration
Email server setup
Admin account creation
Storage configuration

4. Build & Run

Development Environment

# Start all services
./bin/dev

# Or start individually:
bundle exec rails server -p 3000          # Web server
bundle exec sidekiq                       # Background jobs
yarn run start                            # Streaming API (Node.js)

Production Environment

Start the services:

# Web server (Puma)
bundle exec rails server -e production -p 3000

# Sidekiq for background jobs
bundle exec sidekiq -e production

# Streaming API
NODE_ENV=production yarn run start

Using Docker Compose (Recommended)

The repository includes Docker configurations. Use the provided docker-compose.yml:

# Copy the example configuration
cp .env.production.sample .env.production
# Edit .env.production with your settings

# Build and start containers
docker-compose build
docker-compose up -d

# Run database setup
docker-compose run --rm web bundle exec rails db:migrate
docker-compose run --rm web bundle exec rails assets:precompile

5. Deployment

Recommended Platforms

For beginners:

Docker/Docker Compose: Simplest deployment method
Cloudron: One-click installation with automatic updates
YunoHost: Easy deployment with web interface

For production:

Kubernetes: Use the official Mastodon Helm chart
Docker Swarm: For container orchestration
Manual deployment: On VPS providers like DigitalOcean, Linode, or AWS EC2

Platform-as-a-Service:

Heroku: Use the provided Procfile (may require additional configuration)
Scalingo: Similar to Heroku, supports Ruby on Rails apps

Production Considerations

Reverse Proxy: Use nginx or Apache as a reverse proxy
SSL/TLS: Enable HTTPS with Let's Encrypt
Backups: Regular database and Redis backups
Monitoring: Set up monitoring for services and disk space
Updates: Regular updates for security patches

Scaling

Use multiple Sidekiq processes for background jobs
Implement database connection pooling
Consider read replicas for PostgreSQL
Use Redis clustering for high availability
Implement CDN for static assets

6. Troubleshooting

Common Issues

Database connection errors:

# Check PostgreSQL is running
sudo systemctl status postgresql

# Test database connection
bundle exec rails dbconsole -e production

Redis connection issues:

# Check Redis service
redis-cli ping
# Should return "PONG"

Asset compilation errors:

# Clear precompiled assets
bundle exec rails assets:clobber
# Recompile
bundle exec rails assets:precompile

Email delivery problems:

Check SMTP credentials in .env.production
Verify port and TLS settings
Check spam folders

Maintenance Commands

Account management:

# Create a new user account
bundle exec rails mastodon:accounts create USERNAME --email user@example.com --confirmed --role admin

# Rotate account keys (security maintenance)
bundle exec rails mastodon:accounts rotate --all

Database maintenance:

# Run database migrations
bundle exec rails db:migrate

# Rollback if needed
bundle exec rails db:rollback

# Check database consistency
bundle exec rails mastodon:maintenance check_database

Cache clearing:

# Clear Rails cache
bundle exec rails tmp:cache:clear

# Clear Redis cache
redis-cli FLUSHALL

Logs

Check logs in these locations:

Rails logs: log/production.log
Sidekiq logs: log/sidekiq.log
Nginx/Apache logs: /var/log/nginx/ or /var/log/apache2/
System logs: journalctl -u mastodon-* (if using systemd)

Getting Help

Official Documentation: https://docs.joinmastodon.org
GitHub Issues: https://github.com/mastodon/mastodon/issues
Community Forum: https://discourse.joinmastodon.org
Matrix Chat: #mastodon-dev:matrix.org

Performance Issues

High memory usage: Adjust Sidekiq concurrency, reduce cache size
Slow database queries: Add indexes, optimize queries
Media processing delays: Increase Sidekiq workers, use faster storage
Streaming API disconnects: Check WebSocket support, adjust timeout settings

How to Deploy & Use mastodon