homelab-optimized/docs/services/mastodon/README.md

Mastodon Production Scripts

Production-ready Mastodon deployment scripts for self-hosting.

Installation Options

Option 1: Docker (Multi-Platform)

curl -fsSL https://git.vish.gg/Vish/mastodon-production/raw/branch/main/install.sh | sudo bash -s -- --domain mastodon.example.com --email admin@example.com

Supports: Ubuntu, Debian, Fedora, Rocky/Alma/RHEL 8+, Arch, openSUSE

Option 2: Bare-Metal (Rocky Linux 10)

# Set your configuration
export DOMAIN="mastodon.example.com"
export ADMIN_USER="admin"
export ADMIN_EMAIL="admin@example.com"
export SMTP_SERVER="smtp.gmail.com"
export SMTP_PORT="587"
export SMTP_USER="your@gmail.com"
export SMTP_PASS="REDACTED_PASSWORD"
export SMTP_FROM="notifications@example.com"

# Run installer
curl -sSL https://git.vish.gg/Vish/mastodon-production/raw/branch/main/install-baremetal.sh | bash

Scripts

Script	Description
install.sh	Docker-based installer (multi-platform)
install-baremetal.sh	Bare-metal installer for Rocky Linux 10
verify-mastodon.sh	Health check / verification script
fix-mastodon.sh	Diagnose and auto-fix common issues
backup-mastodon.sh	Backup script for migration
update-mastodon.sh	Update to latest Mastodon version

Verify Installation

./verify-mastodon.sh

Checks:

• All services (postgresql, valkey, nginx, mastodon-*)
• API endpoints (instance, streaming)
• Database connectivity and stats
• Federation endpoints (webfinger, nodeinfo)
• Configuration files

Fix Common Issues

./fix-mastodon.sh

Automatically fixes:

• Stopped services
• File permissions
• SELinux contexts
• Service startup issues

Bare-Metal Architecture (Rocky Linux 10)

Internet → Cloudflare → Reverse Proxy (443) → Rocky VM (3000)
                                                    ↓
                                                  nginx
                                                    ↓
                                  ┌─────────────────┼─────────────────┐
                                  ↓                 ↓                 ↓
                             Puma (3001)    Streaming (4000)      Sidekiq
                                  ↓                 ↓                 ↓
                                  └─────────────────┼─────────────────┘
                                                    ↓
                                          PostgreSQL + Valkey

Services (Bare-Metal)

Service	Port	Description
nginx	3000	External reverse proxy
mastodon-web	3001	Puma web server
mastodon-streaming	4000	WebSocket streaming
mastodon-sidekiq	-	Background jobs
postgresql	5432	Database
valkey	6379	Redis cache

Backup & Restore

Create Backup

/home/mastodon/scripts/backup-mastodon.sh

Creates a complete backup including:

• PostgreSQL database dump
• .env.production (secrets)
• User uploads (avatars, headers, media)
• Restore instructions

Restore

See RESTORE.md included in backup archive.

Update Mastodon

# Update to latest version
/home/mastodon/scripts/update-mastodon.sh

# Update to specific version
/home/mastodon/scripts/update-mastodon.sh v4.6.0

Maintenance Commands

# Service status
systemctl status mastodon-web mastodon-sidekiq mastodon-streaming

# Restart all services
systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming

# View logs
journalctl -u mastodon-web -f
journalctl -u mastodon-sidekiq -f

# Access tootctl
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl --help'

# Create new user
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts create USERNAME --email=EMAIL --confirmed'

# Make user admin/owner
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl accounts modify USERNAME --role Owner'

# Clear media cache
sudo -u mastodon bash -lc 'cd ~/live && RAILS_ENV=production bin/tootctl media remove --days=7'

Requirements

Bare-Metal

• Rocky Linux 10 (fresh install)
• 4GB+ RAM recommended
• 20GB+ disk space
• Domain with DNS configured
• SMTP credentials for email

Docker

• Any supported Linux distribution
• Docker and Docker Compose
• Domain with DNS configured

License

MIT