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:
- Install dependencies:
sudo apt update
sudo apt install -y git postgresql postgresql-contrib build-essential curl
- Clone the Pleroma repository and set it up:
git clone https://git.pleroma.social/pleroma/pleroma.git
cd pleroma
mix deps.get
- 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
- Generate the Pleroma configuration:
mix pleroma.instance gen
- 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!
