From 6ea9a21906b4fc35ca4d5918d173e3407c05e944 Mon Sep 17 00:00:00 2001 From: bronze Date: Fri, 29 May 2026 01:48:11 -0400 Subject: [PATCH] readme.md rework --- README.md | 110 ++++++++++++++++++++++++------------------------------ 1 file changed, 49 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 2f2b02e..02e15c4 100644 --- a/README.md +++ b/README.md @@ -1,82 +1,70 @@ -# Pleroma +## ๐Ÿš€ Overview -[Pleroma](https://pleroma.social/) is a federated social networking platform, compatible with GNU social and other OStatus implementations. It is free software licensed under the AGPLv3. +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. -It actually consists of two components: a backend, named simply Pleroma, and a user-facing frontend, named Pleroma-FE. +**Note:** This setup is designed to run behind a **reverse proxy** (like Nginx or Caddy) to handle SSL/TLS termination. -Its main advantages are its lightness and speed. +Pleroma is compatible with **ActivityPub** and other federated social networking protocols, allowing it to interoperate with Misskey, Mastodon, PeerTube, Pixelfed, and other decentralized platforms. -## Why Docker? +## ๐Ÿ“‹ Prerequisites -Boxing up Pleroma in a docker container allows it to be portable, and keeps your host system clean. The software and its dependencies will all be under the `pleroma_web` container (created with the lightweight elixir:alpine base image) while its postgres database will live under `pleroma_db` image. Only port 4000 will be exposed under localhost. +Before starting, ensure your host system has the following installed: +- [Git](https://git-scm.com/) +- [Docker](https://docs.docker.com/get-docker/) +- [Docker Compose](https://docs.docker.com/compose/) -## Build-time variables +## ๐Ÿงช Port Configuration -- **`PLEROMA_VER`** : Pleroma version (latest commit of the [`develop` branch](https://git.pleroma.social/pleroma/pleroma) by default) -- **`GID`**: group id (default: `911`) -- **`UID`**: user id (default: `911`) +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. -## Usage +## ๐Ÿ›  Installation -### 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](https://git.pleroma.social/pleroma/pleroma/src/branch/develop/installation/pleroma.nginx). +- There is also a configuration template in the `extras/` folder. -This container is meant to run behind a reverse proxy. Please set up letsencrypt and a Nginx reverse proxy in a container or on your host by using the [example Nginx config](https://git.pleroma.social/pleroma/pleroma/blob/develop/installation/pleroma.nginx). There's also a config file in the `extras` folder you could take a look at. +### 2. Deployment +Clone this repository and run the setup script: -Log into your server and clone this repository with: +```bash +git clone https://kitsunemimi.club/git/bronze/docker-pleroma +cd docker-pleroma +sh ./scripts/setup.sh +``` -`git clone https://kitsunemimi.club/git/bronze/docker-pleroma` +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. -Go into the new docker-pleroma folder and run: +> [!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. -`sh ./scripts/setup.sh` +## โšฝ Security Considerations -This first time setup script will ask you a few questions, generate a random password for your postgres database, put the results into your docker compose and create an admin account. +Regularly update Pleroma to ensure you have the latest security patches. You can update the backend using the provided scripts. -Remember that password reset link at the end will only work if your reverse proxy is configured and running (duh!). +## ๐Ÿ›  Maintenance -Any further configuration can be done as soon as you log into your admin account, over admin-fe. It will be the speedometer icon right next to the cog on the top right of the webpage. +To simplify management, add this alias to your `.bashrc` or `.zshrc`: +```bash +alias pleroma-ctl='docker exec -it pleroma_web sh ./bin/pleroma_ctl' +``` +This allows you to run Pleroma CLI commands directly. -### Maintenance +### Important: Backups -A very helpful [bash alias](https://www.digitalocean.com/community/tutorials/an-introduction-to-useful-bash-aliases-and-functions) for managing your pleroma instance: +**โš ๏ธ 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. -`alias pleroma-ctl='docker exec -it pleroma_web sh ./bin/pleroma_ctl'` +### Common Tasks -Now you can easily run any of the CLI commands cited in the [documentation](https://docs-develop.pleroma.social/backend/administration/CLI_tasks/user/). - -#### Common tasks - -Update to the latest pleroma-fe frontend using: - -`sh ./scripts/update-plfe.sh` - -Update/rebuild the pleroma backend using: - -`sh ./scripts/rebuild.sh` - -Vacuum your database with this script: - -`sh ./scripts/vacuum.sh` - -Emojis are under `./static/emoji` so drag and drop your folders there. - -#### Backups - -Backups can be done by copying the whole docker-pleroma folder. How you make this copy I'll leave up to you. - -For my own instance, I take a btrfs snapshot of this folder and make a tarball / squashfs archive of that snapshot. Should SHTF I have the snapshots and tarballs to fall back on! - -However you choose to do it, make sure to `docker compose down` before making the backup, you dont want anything modified as you're making the copy. - -#### Upgrading database version - -Please see `UPDATE-DB.md` - -## Other Docker images - -- [angristan/docker-pleroma](https://github.com/angristan/docker-pleroma) (the one this is based off of!) -- [verita84/pleroma](https://git.poster.place/verita84/pleroma) -- [verita84/akkoma](https://git.poster.place/verita84/akkoma) -- [potproject/docker-pleroma](https://github.com/potproject/docker-pleroma) -- [rysiek/docker-pleroma](https://git.pleroma.social/rysiek/docker-pleroma) -- [RX14/iscute.moe](https://github.com/RX14/kurisu.rx14.co.uk/blob/master/services/iscute.moe/pleroma/Dockerfile) +| 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` |