Nov 14, 2024 3 min read

Pleroma: A Complete Checklist for Self-Hosting Success

Pleroma: A Complete Checklist for Self-Hosting Success
Table of Contents

Pleroma is a lightweight, open-source social media platform designed for self-hosting, offering users unparalleled control over their data, privacy, and customization. It’s a compelling choice for developers and administrators seeking a decentralized, federated solution with low resource requirements. In this guide, we’ll cover the full lifecycle of deploying, configuring, and managing Pleroma, providing hands-on examples to help you get started.

Installing Pleroma

πŸ“¦ Docker/Docker Compose Setup

Docker is an efficient way to deploy Pleroma with minimal setup. Below is a docker-compose.yml file tailored for Pleroma:


version: '3.3'

services:

db:

image: postgres:13

container_name: pleroma_db

restart: always

volumes:

- pleroma_db_data:/var/lib/postgresql/data

environment:

POSTGRES_USER: pleroma

POSTGRES_PASSWORD: securepassword

POSTGRES_DB: pleroma

web:

image: pleroma/pleroma:latest

container_name: pleroma_web

restart: always

depends_on:

- db

ports:

- "4000:4000"

environment:

DB_HOST: db

DB_USER: pleroma

DB_PASS: securepassword

DB_NAME: pleroma

INSTANCE_NAME: "My Pleroma Instance"

volumes:

- pleroma_uploads:/var/lib/pleroma/uploads

- pleroma_static:/var/lib/pleroma/static

- ./config:/etc/pleroma

volumes:

pleroma_db_data:

pleroma_uploads:

pleroma_static:

Run the following commands to deploy Pleroma:


docker-compose up -d

## Check the status of the containers

docker-compose ps

πŸš€ Manual Installation

For a manual installation, you’ll need a Linux server with access to the terminal and root privileges. Follow these steps:

  1. Install dependencies:

sudo apt update

sudo apt install -y git postgresql postgresql-contrib build-essential curl

  1. Clone the Pleroma repository and set it up:

git clone https://git.pleroma.social/pleroma/pleroma.git

cd pleroma

mix deps.get

  1. Configure the database:

sudo -u postgres createuser --createdb pleroma

sudo -u postgres psql -c "ALTER USER pleroma PASSWORD 'securepassword';"

sudo -u postgres createdb -O pleroma pleroma

  1. Generate the Pleroma configuration:

mix pleroma.instance gen

  1. Start the application:

MIX_ENV=prod mix phx.server

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

Set up Nginx as a reverse proxy to make Pleroma accessible through a domain name and improve security. Create a server block file for Pleroma:


server {

server_name yourdomain.com;

location / {

proxy_pass http://localhost:4000;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

}

listen 80;

}

Reload Nginx to apply the configuration:


sudo nginx -t

sudo systemctl reload nginx

πŸ”’ SSL/TLS Setup

Secure your instance with a Let’s Encrypt SSL certificate:


sudo apt install -y certbot python3-certbot-nginx

sudo certbot --nginx -d yourdomain.com

Automate certificate renewal:


sudo systemctl enable certbot.timer

sudo systemctl start certbot.timer

πŸ› οΈ Testing and Reloading Nginx

Verify that Pleroma is accessible via HTTPS:


curl -I https://yourdomain.com

Logging and Debugging Pleroma

πŸ—ƒοΈ Enabling Debug Logs

Edit the Pleroma configuration file to enable debug logging:


config :logger, level: :debug

Restart the application for the changes to take effect:


docker-compose restart

## or for manual installs

pkill -f pleroma && MIX_ENV=prod mix phx.server

πŸ“„ Viewing Logs

Access logs using the following commands:

  • For Docker:

docker logs -f pleroma_web

  • For manual installations:

tail -f /path/to/pleroma.log

πŸ› οΈ Troubleshooting Common Issues

Look for errors such as database connection issues or missing configurations in logs. If issues persist, verify the following:

  • Database credentials match the configuration.

  • The reverse proxy is correctly routing traffic.

πŸ“€ Exporting Logs

To send logs to an external system like ELK, use a centralized log collector or output logs to a file that can be shipped externally.

Backup and Restore

πŸ—‚οΈ File-Based Backups

Backup the configuration and uploaded files:


tar -czvf pleroma_backup.tar.gz /etc/pleroma /var/lib/pleroma/uploads

πŸ”„ Database Backups

Dump the database contents:


sudo -u postgres pg_dump pleroma > pleroma_db_backup.sql

Restore from a backup:


sudo -u postgres psql pleroma < pleroma_db_backup.sql

πŸ“… Automated Backup Scripts

Set up a cron job to automate backups:


echo "0 2 * * * tar -czvf /backup/pleroma_$(date +\%F).tar.gz /etc/pleroma /var/lib/pleroma/uploads" | crontab -

Updating and Upgrading Pleroma

⬆️ Updating Docker Images

Pull the latest image and restart:


docker-compose pull

docker-compose up -d

πŸ› οΈ Manual Updates

For manual installations, pull the latest code and recompile:


git pull origin main

MIX_ENV=prod mix deps.get

MIX_ENV=prod mix compile

πŸ” Checking for Updates

Monitor Pleroma’s Git repository for new releases:


git fetch origin

git log HEAD..origin/main

Leveraging Pleroma’s Unique Features

πŸ”§ Enabling APIs

Update the Pleroma configuration file to enable API endpoints:


config :pleroma, :instance,

enable_api: true

🌟 Advanced Configurations

Customize features such as federated timelines or user limits by modifying config/prod.secret.exs. For example:


config :pleroma, :instance,

max_toot_chars: 5000

Restart the server for changes to take effect.

Wrapping Up

This guide covered everything from deploying Pleroma to configuring Nginx, managing logs, and leveraging advanced features. With full control over your instance, you can tailor Pleroma to meet your needs while benefiting from its powerful federation capabilities. Start implementing these steps today to unlock the full potential of your self-hosted social platform!

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.