How to Install Pleroma on Ubuntu VPS (5 Minute Quick-Start Guide)

This article provides a guide demonstrating how to install Pleroma on Ubuntu VPS.

What is Pleroma?

Pleroma is a free, open-source, self-hostable microblogging server that speaks the ActivityPub federation protocol—so your users can interact with people on other Fediverse platforms (e.g., Mastodon) while you keep full control over your server and policies.

It’s built in Elixir (on the Erlang/OTP “BEAM” VM) with PostgreSQL for storage, and is designed to be efficient enough for modest VPSes while still scaling on stronger hardware.

Pleroma ships as a backend plus a default web UI called Pleroma-FE (you can swap in other front-ends if you prefer). Many Mastodon-targeted mobile/desktop clients also work because Pleroma exposes endpoints compatible with the Mastodon client API.

It’s part of the broader Fediverse—a network of independently run servers that interoperate—licensed under AGPLv3.

Here’s a clean, reproducible way to deploy Pleroma on an Ubuntu VPS (22.04/24.04). We’ll use the official OTP release (prebuilt Elixir/Erlang bundle), PostgreSQL, Nginx, and Let’s Encrypt.

What you’ll set up

• Pleroma (backend + default Pleroma-FE)
• PostgreSQL database
• Nginx reverse proxy with HTTPS (Let’s Encrypt)
• Systemd service for auto-start on boot
• An admin account for first login

Prerequisites

• A fresh Ubuntu 22.04 or Ubuntu 24.04 VPS with root (or sudo) access
• A domain (or subdomain) pointed at your server’s public IP (A/AAAA records)

The Pleroma team recommends using their OTP releases on Debian/Ubuntu and outlines the exact packages we’ll install, plus optional media tools.

How to Install Pleroma on Ubuntu VPS

To install Pleroma on Ubuntu VPS, follow the steps below:

1. Update, set hostname, and basic tools

   sudo apt update && sudo apt -y full-upgrade
   sudo apt -y install curl unzip postgresql postgresql-contrib nginx certbot libmagic-dev
   

   Those are the core dependencies required by the OTP release (curl, unzip, ncurses, PostgreSQL, Nginx, certbot, libmagic).

   (Recommended) Media/graphics helpers

   sudo apt -y install imagemagick ffmpeg libimage-exiftool-perl
   

   These enable image/video processing and EXIF handling.

2. Create the Pleroma system user and data dirs

   sudo adduser --system --shell /bin/false --home /opt/pleroma pleroma
   sudo groupadd pleroma
   sudo usermod -aG pleroma pleroma
   
   # Uploads and static override directories
   sudo mkdir -p /var/lib/pleroma/{uploads,static}
   sudo chown -R pleroma:pleroma /var/lib/pleroma
   
   # Config directory
   sudo mkdir -p /etc/pleroma
   sudo chown -R pleroma:pleroma /etc/pleroma
   

   These paths match the official OTP layout.

3. Download and install the OTP release

   Determine the correct build “flavour” (architecture/libc) and fetch the ZIP:

   # Detect flavour (outputs e.g., amd64)
   arch="$(uname -m)"; if [ "$arch" = "x86_64" ]; then arch="amd64"; \
   elif [ "$arch" = "armv7l" ]; then arch="arm"; \
   elif [ "$arch" = "aarch64" ]; then arch="arm64"; \
   else echo "Unsupported arch: $arch" >&2; fi
   export FLAVOUR="$arch"
   
   # Download + unpack as the pleroma user
   sudo -Hu pleroma bash -lc "
     curl 'https://git.pleroma.social/api/v4/projects/2/jobs/artifacts/stable/download?job=$FLAVOUR' -o /tmp/pleroma.zip
     unzip /tmp/pleroma.zip -d /tmp/
     mv /tmp/release/* /opt/pleroma
     rmdir /tmp/release
     rm /tmp/pleroma.zip
   "
   

   The official instructions use this artifact endpoint and directory layout.

4. Generate configuration and initialize the database

   Use Pleroma’s CLI to generate a config and DB setup SQL—then create the DB and run migrations:

   # Create instance config + SQL (interactive prompts ask for your domain, email, etc.)
   sudo -Hu pleroma ./opt/pleroma/bin/pleroma_ctl instance gen \
     --output /etc/pleroma/config.exs \
     --output-psql /tmp/setup_db.psql
   
   # Create the PostgreSQL database and role from that SQL
   sudo -u postgres -s $SHELL -lc "psql -f /tmp/setup_db.psql"
   
   # Run database migrations
   sudo -Hu pleroma ./opt/pleroma/bin/pleroma_ctl migrate
   

   Generation via pleroma_ctl instance gen and the subsequent psql + migrate flow are the officially documented OTP steps.

   Tip: If you plan to keep most settings in the DB, answer Yes when the generator asks to store configuration in the database.

5. One-time verification (optional)

   Start Pleroma in the foreground just to confirm the instance answers locally, then stop it:

   sudo -Hu pleroma ./opt/pleroma/bin/pleroma daemon
   sleep 20 && curl -s http://localhost:4000/api/v1/instance | jq .
   sudo -Hu pleroma ./opt/pleroma/bin/pleroma stop
   

   Official docs suggest this quick check before wiring Nginx.

6. Obtain a Let’s Encrypt certificate

   Use the standalone method once (we’ll switch to webroot auto-renew later):

   sudo systemctl stop nginx
   sudo certbot certonly --standalone --preferred-challenges http -d yourinstance.tld
   sudo systemctl start nginx
   

   (Replace yourinstance.tld with your domain.)

7. Configure Nginx reverse proxy

   Copy the stock Pleroma Nginx template and enable it:

   sudo cp /opt/pleroma/installation/pleroma.nginx /etc/nginx/sites-available/pleroma.conf
   sudo ln -s /etc/nginx/sites-available/pleroma.conf /etc/nginx/sites-enabled/pleroma.conf
   sudo nginx -t && sudo systemctl reload nginx
   

   The template targets Pleroma on localhost:4000 and includes ACME challenge location you can switch to webroot for renewals later.

8. Install the systemd service and start Pleroma

   sudo cp /opt/pleroma/installation/pleroma.service /etc/systemd/system/pleroma.service
   sudo systemctl daemon-reload
   sudo systemctl start pleroma
   sudo systemctl enable pleroma
   sudo systemctl status pleroma --no-pager
   

   Service installation and enable/start steps are exactly as documented for Debian/Ubuntu.

   At this point, visiting https://yourinstance.tld should load Pleroma-FE.

9. Create your admin user

   cd /opt/pleroma
   sudo su -s $SHELL -l pleroma -c "./bin/pleroma_ctl user new   --admin"
   

   You’ll be given a one-time login link to set the password. (You can manage users later with pleroma_ctl user ... commands.)

10. Set up certificate auto-renew (webroot method)

    Create the webroot and cron job that reloads Nginx after renewals:

    sudo mkdir -p /var/lib/letsencrypt
    
    # Ensure your Nginx conf uses webroot for /.well-known/acme-challenge/ -> /var/lib/letsencrypt
    
    # Dry-run test:
    sudo certbot renew --cert-name yourinstance.tld \
      --webroot -w /var/lib/letsencrypt/ \
      --dry-run --post-hook 'systemctl reload nginx'
    
    # Daily cron
    echo '#!/bin/sh
    certbot renew --cert-name yourinstance.tld --webroot -w /var/lib/letsencrypt/ --post-hook "systemctl reload nginx"
    ' | sudo tee /etc/cron.daily/renew-pleroma-cert >/dev/null
    
    sudo chmod +x /etc/cron.daily/renew-pleroma-cert
    

    This mirrors the official post-install renewal approach.

11. (Optional) Hardening & polish

    • Serve media from a separate domain to reduce attack surface (the docs strongly recommend this). ([Fossies][1])
    • Consider a firewall (ufw allow 80,443/tcp), system monitoring, and regular database/file backups.

12. Common admin commands

    Run these as the pleroma user from /opt/pleroma:

    # Create a user (non-admin)
    ./bin/pleroma_ctl user new  
    
    # Grant / revoke admin
    ./bin/pleroma_ctl user set  --admin
    ./bin/pleroma_ctl user set  --no-admin
    
    # Reset a user's password (generates a reset link)
    ./bin/pleroma_ctl user reset_password 
    
    # Database migrations (when updating)
    ./bin/pleroma_ctl migrate
    

    Pleroma documents these user management and CLI tasks.

13. Updating Pleroma (later)

    With OTP installs you generally:

    # As pleroma user
    ./bin/pleroma_ctl update
    sudo systemctl stop pleroma
    ./bin/pleroma_ctl migrate
    sudo systemctl start pleroma
    

    (Workflows like this are covered in various step-by-steps and mirror the official tool usage.)

Conclusion

You now know how to install Pleroma on Ubuntu VPS. You now have a production-friendly Pleroma instance behind Nginx with automatic TLS renewal, a systemd service, and an admin account.