Pleroma is a microblogging server software that can federate (= exchange messages with) other servers that support ActivityPub. What that means is that you can host a server for yourself or your friends and stay in control of your online identity, but still exchange messages with people on larger servers. Pleroma will federate with all servers that implement ActivityPub, like Friendica, GNU Social, Hubzilla, Mastodon, Misskey, Peertube, and Pixelfed.
Pleroma is written in Elixir and uses PostgresSQL for data storage. It's efficient enough to be ran on low-power devices like Raspberry Pi (though we wouldn't recommend storing the database on the internal SD card ;) but can scale well when ran on more powerful hardware (albeit only single-node for now).
For clients it supports the [Mastodon client API](https://docs.joinmastodon.org/api/guidelines/) with Pleroma extensions (see the API section on <https://docs-develop.pleroma.social>).
- [Client Applications for Pleroma](https://docs-develop.pleroma.social/backend/clients/)
## Installation
### OTP releases (Recommended)
If you are running Linux (glibc or musl) on x86/arm, the recommended way to install Pleroma is by using OTP releases. OTP releases are as close as you can get to binary releases with Erlang/Elixir. The release is self-contained, and provides everything needed to boot it. The installation instructions are available [here](https://docs-develop.pleroma.social/backend/installation/otp_en/).
### From Source
If your platform is not supported, or you just want to be able to edit the source code easily, you may install Pleroma from source.
Currently Pleroma is packaged for [YunoHost](https://yunohost.org), [NixOS](https://nixos.org), [Gentoo through GURU](https://gentoo.org/) and [Archlinux through AUR](https://aur.archlinux.org/packages/pleroma). You may find more at <https://repology.org/project/pleroma/versions>.
If you want to package Pleroma for any OS/Distros, we can guide you through the process on our [community channels](#community-channels). If you want to change default options in your Pleroma package, please **discuss it with us first**.
### Docker
While we don’t provide docker files, other people have written very good ones. Take a look at <https://github.com/angristan/docker-pleroma> or <https://glitch.sh/sn0w/pleroma-docker>.
### Raspberry Pi
Community maintained Raspberry Pi image that you can flash and run Pleroma on your Raspberry Pi. Available here <https://github.com/guysoft/PleromaPi>.
### Compilation Troubleshooting
If you ever encounter compilation issues during the updating of Pleroma, you can try these commands and see if they fix things:
- `mix deps.clean --all`
- `mix local.rebar`
- `mix local.hex`
- `rm -r _build`
If you are not developing Pleroma, it is better to use the OTP release, which comes with everything precompiled.
## Documentation
- Latest Released revision: <https://docs.pleroma.social>
* IRC: **#pleroma** and **#pleroma-dev** on libera.chat, webchat is available at <https://irc.pleroma.social>
* Matrix: [#pleroma:libera.chat](https://matrix.to/#/#pleroma:libera.chat) and [#pleroma-dev:libera.chat](https://matrix.to/#/#pleroma-dev:libera.chat)
-This guide will assume that you have administrative rights, either as root or a user with [sudo permissions](https://wiki.archlinux.org/index.php/Sudo). If you want to run this guide with root, ignore the `sudo` at the beginning of the lines, unless it calls a user like `sudo -Hu pleroma`; in this case, use `su <username> -s $SHELL -c 'command'` instead.
-
-### Required packages
-
-* `postgresql`
-* `elixir`
-* `git`
-* `base-devel`
-* `cmake`
-* `file`
-
-#### Optional packages used in this guide
-
-* `nginx` (preferred, example configs for other reverse proxies can be found in the repo)
-* `certbot` (or any other ACME client for Let’s Encrypt certificates)
-* `ImageMagick`
-* `ffmpeg`
-* `exiftool`
-
-### Prepare the system
-
-* First update the system, if not already done:
-
-```shell
-sudo pacman -Syu
-```
-
-* Install some of the above mentioned programs:
-
-```shell
-sudo pacman -S git base-devel elixir cmake file
-```
-
-### Install PostgreSQL
-
-[Arch Wiki article](https://wiki.archlinux.org/index.php/PostgreSQL)
-### Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md))
-**Note**: To execute a single command as the Pleroma system user, use `sudo -Hu pleroma command`. You can also switch to a shell by using `sudo -Hu pleroma $SHELL`. If you don’t have and want `sudo` on your system, you can use `su` as root user (UID 0) for a single command by using `su -l pleroma -s $SHELL -c 'command'` and `su -l pleroma -s $SHELL` for starting a shell.
-
-* Git clone the PleromaBE repository and make the Pleroma user the owner of the directory:
- * Answer with `yes` if it asks you to install `rebar3`.
- * This may take some time, because parts of pleroma get compiled first.
- * After that it will ask you a few questions about your instance and generates a configuration file in `config/generated_config.exs`.
-
-* Check the configuration and if all looks right, rename it, so Pleroma will load it (`prod.secret.exs` for productive instance, `dev.secret.exs` for development instances):
-* The previous command creates also the file `config/setup_db.psql`, with which you can create the database:
-
-```shell
-sudo -Hu postgres psql -f config/setup_db.psql
-```
-
-* Now run the database migration:
-
-```shell
-sudo -Hu pleroma MIX_ENV=prod mix ecto.migrate
-```
-
-* Now you can start Pleroma already
-
-```shell
-sudo -Hu pleroma MIX_ENV=prod mix phx.server
-```
-
-### Finalize installation
-
-If you want to open your newly installed instance to the world, you should run nginx or some other webserver/proxy in front of Pleroma and you should consider to create a systemd service file for Pleroma.
-
-#### Nginx
-
-* Install nginx, if not already done:
-
-```shell
-sudo pacman -S nginx
-```
-
-* Create directories for available and enabled sites:
-If that doesn’t work, make sure, that nginx is not already running. If it still doesn’t work, try setting up nginx first (change ssl “on” to “off” and try again).
-
----
-
-* Copy the example nginx configuration and activate it:
-* Before starting nginx edit the configuration and change it to your needs (e.g. change servername, change cert paths)
-
-* (Strongly recommended) serve media on another domain
-
-Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors.
-
-* Enable and start nginx:
-
-```shell
-sudo systemctl enable --now nginx.service
-```
-
-If you need to renew the certificate in the future, uncomment the relevant location block in the nginx config and run:
-Questions about the installation or didn’t it work as it should be, ask in [#pleroma:libera.chat](https://matrix.to/#/#pleroma:libera.chat) via Matrix or **#pleroma** on **libera.chat** via IRC.
-Currently there are two options available for NetBSD: manual installation (from source) or using experimental package from [pkgsrc-wip](https://github.com/NetBSD/pkgsrc-wip/tree/master/pleroma).
-
-WIP package can be installed via pkgsrc and can be crosscompiled for easier binary distribution. Source installation most probably will be restricted to a single machine.
-
-## pkgsrc installation
-
-WIP package creates Mix.Release (similar to how Docker images are built) but doesn't bundle Erlang runtime, listing it as a dependency instead. This allows for easier and more modular installations, especially on weaker machines. Currently this method also does not support all features of `pleroma_ctl` command (like changing installation type or managing frontends) as NetBSD is not yet a supported binary flavour of Pleroma's CI.
-
-In any case, you can install it the same way as any other `pkgsrc-wip` package:
-Use `bmake package` to create a binary package. This can come especially handy if you're targeting embedded or low-power systems and are crosscompiling on a more powerful machine.
-
-> Note: Elixir has [endianness bug](https://github.com/elixir-lang/elixir/issues/2785) which requires it to be compiled on a machine with the same endianness. In other words, package crosscompiled on amd64 (little endian) won't work on powerpc or sparc machines (big endian). While _in theory™_ nothing catastrophic should happen, one can see that for example regexes won't work properly. Some distributions just strip this warning away, so it doesn't bother the users... anyway, you've been warned.
-
-## Source installation
-
-pkgin should have been installed by the NetBSD installer if you selected
-the right options. If it isn't installed, install it using `pkg_add`.
-
-Note that `postgresql11-contrib` is needed for the Postgres extensions
-Pleroma uses.
-
-> Note: you can use modern versions of PostgreSQL. In this case, just use `postgresql16-contrib` and so on.
-
-The `mksh` shell is needed to run the Elixir `mix` script.
-## Install media / graphics packages (optional, see [`docs/installation/optional/media_graphics_packages.md`](../installation/optional/media_graphics_packages.md))
-From now on, you may encounter `$PREFIX` variable in the paths. This variable indicates your current local pkgsrc prefix. Usually it's `/usr/pkg` unless you configured it otherwise. Translating to pkgsrc's lingo, it's called `LOCALBASE`, which essentially means the same this. You may want to set it up for your local shell session (this uses `mksh` which should already be installed as one of the required dependencies):
-
-```
-$ export PREFIX=$(pkg_info -Q LOCALBASE mksh)
-$ echo $PREFIX
-/usr/pkg
-```
-
-## Setting up your instance
-
-Now, you need to configure your instance. During this initial configuration, you will be asked some questions about your server. You will need a domain name at this point; it doesn't have to be deployed, but changing it later will be very cumbersome.
-
-If you've installed via pkgsrc, `pleroma_ctl` should already be in your `PATH`; if you've installed from source, it's located at `/home/pleroma/pleroma/release/bin/pleroma_ctl`.
-
-```
-$ su -l pleroma
-$ pleroma_ctl instance gen --output $PREFIX/etc/pleroma/config.exs --output-psql /tmp/setup_db.psql
-```
-
-During installation, you will be asked about static and upload directories. Don't forget to create them and update permissions:
-Postgres allows connections from all users without a password by default. To
-fix this, edit `$PREFIX/pgsql/data/pg_hba.conf`. Change every `trust` to
-`password`.
-
-Once this is done, restart Postgres with `# /etc/rc.d/pgsql restart`.
-
-Run the database migrations.
-
-### pkgsrc installation
-
-```
-pleroma_ctl migrate
-```
-
-### Source installation
-
-You will need to do this whenever you update with `git pull`:
-
-```
-$ cd /home/pleroma/pleroma
-$ MIX_ENV=prod mix ecto.migrate
-```
-
-## Configuring nginx
-
-Install the example configuration file
-(`$PREFIX/share/examples/pleroma/pleroma.nginx` or `/home/pleroma/pleroma/installation/pleroma.nginx`) to
-`$PREFIX/etc/nginx.conf`.
-
-Note that it will need to be wrapped in a `http {}` block. You should add
-settings for the nginx daemon outside of the http block, for example:
-
-```
-user nginx nginx;
-error_log /var/log/nginx/error.log;
-worker_processes 4;
-
-events {
-}
-```
-
-Edit the defaults:
-
-* Change `ssl_certificate` and `ssl_trusted_certificate` to
-`/etc/nginx/tls/fullchain`.
-* Change `ssl_certificate_key` to `/etc/nginx/tls/key`.
-* Change `example.tld` to your instance's domain name.
-
-### (Strongly recommended) serve media on another domain
-
-Refer to the [Hardening your instance](../configuration/hardening.md) document on how to serve media on another domain. We STRONGLY RECOMMEND you to do this to minimize attack vectors.
-
-## Configuring acme.sh
-
-We'll be using acme.sh in Stateless Mode for TLS certificate renewal.
-For properly functioning instance, you will need pleroma (backend service), nginx (reverse proxy) and postgresql (database) services running. There's no requirement for them to reside on the same machine, but you have to provide autostart for each of them.
-Questions about the installation or didn’t it work as it should be, ask in [#pleroma:libera.chat](https://matrix.to/#/#pleroma:libera.chat) via Matrix or **#pleroma** on **libera.chat** via IRC.