docker-pleroma/README.md

🚀 Overview

This repository provides a Dockerized deployment for Pleroma. Using Docker ensures portability and keeps your host system clean. The setup includes:

• pleroma_web: The Pleroma backend (running on elixir:alpine).
• pleroma_db: A PostgreSQL database.

Note: This setup is designed to run behind a reverse proxy (like Nginx or Caddy) to handle SSL/TLS termination.

Pleroma is compatible with ActivityPub and other federated social networking protocols, allowing it to interoperate with Misskey, Mastodon, PeerTube, Pixelfed, and other decentralized platforms.

📋 Prerequisites

Before starting, ensure your host system has the following installed:

• Git
• Docker
• Docker Compose

🧪 Port Configuration

The Pleroma web service runs on port 4000 inside the container. When using a reverse proxy, ensure it forwards traffic to this port. The external port (typically 80/443) should be handled by your proxy with SSL/TLS termination.

🛠 Installation

1. Setup Reverse Proxy

This container is intended to run behind a reverse proxy. You must configure Nginx (or your preferred proxy) to forward traffic to port 4000 of the container.

• See example Nginx config.
• There is also a configuration template in the extras/ folder.

2. Deployment

Clone this repository and run the setup script:

git clone https://kitsunemimi.club/git/bronze/docker-pleroma
cd docker-pleroma
sh ./scripts/setup.sh

The setup.sh script will:

• Ask for necessary configuration details.
• Generate a random password for your PostgreSQL database.
• Update your docker-compose.yml.
• Create an initial admin account.

Important

The admin password reset link generated at the end of the setup will only work if your reverse proxy is correctly configured and accessible via your domain.

⚽ Security Considerations

Regularly update Pleroma to ensure you have the latest security patches. You can update the backend using the provided scripts.

🛠 Maintenance

To simplify management, add this alias to your .bashrc or .zshrc:

alias pleroma-ctl='docker exec -it pleroma_web sh ./bin/pleroma_ctl'

This allows you to run Pleroma CLI commands directly.

Important: Backups

⚠️ IMPORTANT: Always run docker compose down before performing a backup to ensure data consistency and prevent modifying files during the copy process. The simplest way to back up your instance is to back up the entire docker-pleroma folder.

Common Tasks

Task	Command	Description
Update Backend	sh ./scripts/rebuild.sh	Rebuilds the Pleroma image with the latest version
Update Frontend	sh ./scripts/update-plfe.sh	Updates the Pleroma-FE component
Database Cleanup	sh ./scripts/db-vacuum.sh	Performs a VACUUM on the PostgreSQL database
Add Emojis	N/A	Drop emoji folders into ./static/emoji