5.4 KiB
Raw Blame History

Pleroma-Docker (Unofficial)

Pleroma is a selfhosted social network that uses OStatus/ActivityPub.

This repository dockerizes it for easier deployment.

#include <LICENSE>

 * This repository comes with ABSOLUTELY NO WARRANTY
 * I am not responsible for burning servers, angry users, fedi drama,
 * thermonuclear war, or you getting fired because your boss saw your NSFW posts.
 * Please do some research if you have any concerns about included
 * features or the software used by this script ***before*** using it.

In the Wild

My own instance is managed by this script.
Take a look at hosted/pleroma if you get stuck or need some inspiration.

Does your instance use pleroma-docker?
Let me know and I'll add you to this list.


These docs assume that you have at least a basic understanding of the pleroma installation process and common docker commands.

If you have questions about Pleroma head over to
For help with docker check out

For other problems related to this script, contact me or open an issue :)


  • ~500mb of free HDD space
  • git if you want smart build caches
  • curl, jq, and dialog if you want to use ./ mod
  • Bash 4+
  • Docker 18.06+ and docker-compose 1.22+


  • Clone this repository
  • Create a config.exs and .env file
  • Run ./ build and ./ up
  • Configure a reverse-proxy
  • Profit!

You can also use normal docker-compose commands to maintain your setup.
The only command that you cannot use is docker-compose build due to build caching.


Run ./ build again and start the updated image with ./ up.

You don't need to stop your pleroma server for either of those commands.


Pleroma maintenance is usually done with mix tasks. You can run these tasks in your running pleroma server using ./ mix [task] [arguments...]. If you need to fix some bigger issues you can also spawn a shell with ./ enter.

For example: / mix pleroma.user new sn0w ...

My instance is up, how do I reach it?

Older versions of this script contained a huge amount of scripting to support all kinds of reverse-proxy setups.
This newer version tries to focus only on providing good setup tooling.

You will have to configure your own reverse-proxy.
You can use Caddy, Traefik, Apache, nginx, or whatever else you could come up with.
Just modify your docker-compose.yml accordingly.

One example would be to add an nginx server to your docker-compose.yml:

  # ...

    image: nginx
    init: true
    restart: unless-stopped
      - server
      - ./my-nginx-config.conf:/etc/nginx/nginx.conf:ro
      - "80:80"
      - "443:443"

Then take a look at the pleroma nginx example for hints about what to put into my-nginx-config.conf.

Using apache would work in a very similar way (see Apache Docker Docs and the pleroma apache example).

The target that you proxy to is called http://server:4000/.
This will work automagically when the proxy also lives inside of docker.

Something that uses is simple port-forwarding of the server container to the host's From there on, the natively installed nginx server acts as a proxy to the open internet. You can take a look at this file if that setup sounds interesting.

If you need help with this, or if you think that this needs more documentation, please let me know.


Add your customizations (and their folder structure) to custom.d/.
They will be copied into the right place when the container starts.
You can even replace/patch pleromas code with this, because the project is recompiled at startup if needed.

In general: Prepending custom.d/ to pleromas customization guides should work all the time.
Check them out in the official pleroma wiki.

For example: A custom thumbnail now goes into custom.d/ + priv/static/instance/thumbnail.jpeg.


Works exactly like customization, but we have a neat little helper here.

Use ./ mod [regex] to mod any file that ships with pleroma, without having to type the complete path.


All the pleroma options that you usually put into your *.secret.exs now go into config.exs.

.env stores config values that need to be known at orchestration/build time.
Documentation for the possible values is inside of that file.


Thanks to Angristan and RX14 for their dockerfiles, which served as an inspiration for the early versions of this script.

The current version is based on the official wiki guides.
Thanks to all people who contributed to those.