RamNode logo
    Sign UpLogin
    Social Media Guide

    Mastodon Deployment on RamNode VPS

    Deploy your own federated social network with Mastodon on a RamNode VPS. This comprehensive guide walks you through setting up a production-ready Mastodon instance with Nginx, PostgreSQL, and Redis on Ubuntu 24.04 LTS.

    Ubuntu 24.04 LTS
    ActivityPub
    ⏱️ 60-90 minutes
    1

    Introduction

    Mastodon is a free, open-source social network server based on ActivityPub. This guide walks you through deploying a production-ready Mastodon instance on a RamNode VPS running Ubuntu 24.04 LTS.

    RamNode's high-performance SSD storage and generous bandwidth allocation make it an excellent choice for hosting federated social media platforms.

    2

    VPS Requirements

    Mastodon requires adequate resources for reliable operation. The following table outlines recommended RamNode VPS plans based on your expected user count:

    Instance SizeUsersRecommended PlanSpecs
    Small1-100Premium KVM 4GB4GB RAM, 2 vCPU, 80GB SSD
    Medium100-500Premium KVM 8GB8GB RAM, 4 vCPU, 160GB SSD
    Large500+Premium KVM 16GB+16GB+ RAM, 6+ vCPU, 320GB+ SSD

    Note: Media storage grows rapidly. Consider attaching RamNode Object Storage for media files on larger instances.

    3

    Prerequisites

    • A RamNode VPS running Ubuntu 24.04 LTS
    • A registered domain name with DNS pointed to your VPS IP
    • SMTP credentials for email delivery (Mailgun, SendGrid, or similar)
    • Root or sudo access to your VPS
    4

    Initial Server Setup

    Update System Packages

    Connect to your RamNode VPS via SSH and update the system:

    Connect and update
    ssh root@your-vps-ip
apt update && apt upgrade -y

    Install Dependencies

    Install required system packages:

    Install dependencies
    apt install -y curl wget gnupg apt-transport-https lsb-release ca-certificates \
imagemagick ffmpeg libpq-dev libxml2-dev libxslt1-dev file git-core \
g++ libprotobuf-dev protobuf-compiler pkg-config gcc autoconf \
bison build-essential libssl-dev libyaml-dev libreadline6-dev \
zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev \
redis-server redis-tools postgresql postgresql-contrib \
nginx certbot python3-certbot-nginx libidn11-dev libicu-dev libjemalloc-dev

    Create Mastodon User

    Create user
    adduser --disabled-login mastodon
    5

    Install Node.js

    Mastodon requires Node.js 20.x. Install via NodeSource:

    Install Node.js 20.x
    curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
corepack enable
corepack prepare yarn@stable --activate
    6

    Install Ruby

    Install Ruby 3.3.x using rbenv as the mastodon user:

    Install Ruby with rbenv
    su - mastodon
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
exec bash
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.3.6
rbenv global 3.3.6
exit
    7

    Configure PostgreSQL

    Create the Mastodon database and user:

    Create database user
    sudo -u postgres psql
CREATE USER mastodon CREATEDB;
\q

    Performance Tuning

    For optimal performance on RamNode VPS, tune PostgreSQL by editing /etc/postgresql/16/main/postgresql.conf:

    PostgreSQL configuration
    shared_buffers = 1GB           # 25% of RAM for 4GB VPS
effective_cache_size = 3GB     # 75% of RAM
maintenance_work_mem = 256MB
work_mem = 32MB
max_connections = 100
    Restart PostgreSQL
    systemctl restart postgresql
    8

    Configure Redis

    Redis is used for caching and background job queues. For larger instances, edit /etc/redis/redis.conf:

    Redis configuration
    maxmemory 512mb
maxmemory-policy allkeys-lru
    Enable and start Redis
    systemctl enable redis-server && systemctl start redis-server
    9

    Install Mastodon

    Clone Repository

    As the mastodon user, clone the latest stable release:

    Clone Mastodon
    su - mastodon
git clone https://github.com/mastodon/mastodon.git ~/live
cd ~/live
git checkout $(git tag -l | grep '^v[0-9]' | sort -V | tail -n 1)

    Install Dependencies

    Install Ruby and JS dependencies
    bundle config deployment 'true'
bundle config without 'development test'
bundle install -j$(getconf _NPROCESSORS_ONLN)
yarn install --frozen-lockfile

    Run Setup Wizard

    The interactive setup wizard configures your instance:

    Run setup wizard
    RAILS_ENV=production bundle exec rake mastodon:setup

    The wizard will prompt for: domain name, database configuration (use defaults), Redis configuration (use defaults), cloud storage settings, SMTP settings, and admin account creation.

    10

    Configure Nginx

    Copy the Mastodon Nginx template and configure it:

    Configure Nginx
    exit # Return to root
cp /home/mastodon/live/dist/nginx.conf /etc/nginx/sites-available/mastodon
ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/
rm /etc/nginx/sites-enabled/default

    Replace example.com with your domain:

    Update domain
    sed -i 's/example.com/your-domain.com/g' /etc/nginx/sites-available/mastodon
    Test and reload
    nginx -t && systemctl reload nginx
    11

    Configure SSL with Let's Encrypt

    Obtain a free SSL certificate using Certbot:

    Get SSL certificate
    certbot --nginx -d your-domain.com

    Certbot automatically configures SSL and sets up auto-renewal. Verify with:

    Test renewal
    certbot renew --dry-run
    12

    Configure Systemd Services

    Copy and enable the systemd service files:

    Setup services
    cp /home/mastodon/live/dist/mastodon-*.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable mastodon-web mastodon-sidekiq mastodon-streaming
systemctl start mastodon-web mastodon-sidekiq mastodon-streaming

    Verify services are running:

    Check status
    systemctl status mastodon-web mastodon-sidekiq mastodon-streaming

    Service Reference

    ServiceDescription
    mastodon-webPuma web server handling HTTP requests
    mastodon-sidekiqBackground job processor for federation, emails, media
    mastodon-streamingWebSocket server for real-time updates
    13

    Post-Installation Tasks

    Create Admin Account

    If you didn't create an admin during setup:

    Create admin account
    su - mastodon
cd ~/live
RAILS_ENV=production bin/tootctl accounts create admin --email admin@your-domain.com --confirmed --role Owner

    Configure Firewall

    Secure your VPS with UFW:

    Configure UFW
    ufw allow ssh
ufw allow 'Nginx Full'
ufw enable
    14

    Maintenance & Operations

    Automated Cleanup Cron Jobs

    Add to /etc/cron.d/mastodon:

    Cron jobs
    # Media cleanup (daily at 3am)
0 3 * * * mastodon cd /home/mastodon/live && RAILS_ENV=production bin/tootctl media remove --days=7
# Preview cards cleanup (weekly)
0 4 * * 0 mastodon cd /home/mastodon/live && RAILS_ENV=production bin/tootctl preview_cards remove --days=30
# Remove orphaned files (monthly)
0 5 1 * * mastodon cd /home/mastodon/live && RAILS_ENV=production bin/tootctl media remove-orphans

    Updating Mastodon

    To update to the latest version:

    Update Mastodon
    su - mastodon
cd ~/live
git fetch --tags
git checkout $(git tag -l | grep '^v[0-9]' | sort -V | tail -n 1)
bundle install
yarn install --frozen-lockfile
RAILS_ENV=production bundle exec rails db:migrate
RAILS_ENV=production bundle exec rails assets:precompile
exit
systemctl restart mastodon-web mastodon-sidekiq mastodon-streaming
    15

    Backup Strategy

    Essential backup components:

    • PostgreSQL database: Use pg_dump daily
    • Environment config: /home/mastodon/live/.env.production
    • Media files: /home/mastodon/live/public/system/
    • Redis (optional): Only needed if you want to preserve queued jobs

    Example Backup Script

    Using RamNode Object Storage:

    Backup script
    #!/bin/bash
DATE=$(date +%Y%m%d)
pg_dump -U mastodon mastodon_production | gzip > /backup/mastodon-db-$DATE.sql.gz
tar -czf /backup/mastodon-env-$DATE.tar.gz /home/mastodon/live/.env.production
# Sync to RamNode S3
s3cmd sync /backup/ s3://your-bucket/mastodon-backups/
    16

    Troubleshooting

    502 Bad Gateway

    Check if Puma is running and review logs:

    Debug 502
    systemctl status mastodon-web
journalctl -u mastodon-web -f

    Slow Federation

    Check Sidekiq queue depth. Consider increasing Sidekiq threads in the service file:

    Check queue
    RAILS_ENV=production bin/tootctl sidekiq stats

    High Memory Usage

    Tune Puma workers in .env.production:

    Memory tuning
    WEB_CONCURRENCY=2  # for 4GB RAM
MAX_THREADS=5

    Email Delivery Issues

    Verify SMTP settings and check Sidekiq logs for email job failures:

    Test email
    RAILS_ENV=production bin/tootctl accounts email admin@your-domain.com

    Support Resources

    RamNode Support

    support.ramnode.com

    Mastodon Documentation

    docs.joinmastodon.org

    RamNode Cloud Credits: Eligible customers can receive up to $500/year in cloud credits. Contact support to learn about our developer programs and startup credits.

    ← Back to GuidesView Premium VPS Plans →