You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
sn0w 544321510b
Update readme
4 years ago
custom.d Update structure 5 years ago
.dockerignore Update structure 5 years ago
.env.dist Fix new config format 5 years ago
.gitignore Add config.exs to ignore 4 years ago
Dockerfile Fix missing mogrify 4 years ago
LICENSE Add license and reset README for rewrite 5 years ago Update readme 4 years ago
config.dist.exs Add cp command 4 years ago
docker-compose.m4 ok this is emberassing 4 years ago Make custom.d work again 4 years ago
initdb.sql Add pg_trgm extension 5 years ago
pleroma Add cache tag warnings 4 years ago

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.
 * You are choosing to use this setup, and if you point the finger at me for
 * messing up your instance, I will laugh at you.

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


  • ~500mb of free HDD space
  • m4 and awk in remotely recent versions
  • git if you want smart build caches
  • curl, jq, and dialog if you want to use ./pleroma mod
  • Bash 4.0+ (fancy scripting stuff)
  • Docker 18.06+ and docker-compose 1.22+


  • Clone this repository
  • Create a config.exs and .env file
  • Run ./pleroma build and ./pleroma up
  • Profit!


Run ./pleroma build again and start the updated image with ./pleroma 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 ./pleroma mix [task] [arguments...]. If you need to fix some bigger issues you can also spawn a shell with ./pleroma enter.

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


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 ./pleroma 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 time.
They should be self-explaining but here's some bonus info on important ones:


A folder that will be bind-mounted into the container.
This is where pleroma and postgres will store their data.


Values: true / false

By default pleroma-docker deploys a postgresql container and links it to pleromas container as a zero-config data store. If you already have a postgres database or want to host it on a physically different machine, set this value to false. Make sure to edit the config :pleroma, Pleroma.Repo variables in config.exs when doing that.

Reverse Proxy (SCRIPT_USE_PROXY)

Values: traefik / nginx / apache / manual

Pleroma is usually run behind a reverse-proxy.
Pleroma-docker gives you multiple options here.


In manual mode we do not create any reverse proxy for you.
You'll have to figure something out on your own.

If SCRIPT_BIND_IN_MANUAL is true we will forward pleroma:4000 to ${SCRIPT_BIND_IP}:${SCRIPT_PORT_HTTP}.


In traefik-mode we will generate a pleroma container with traefik-compatible labels. These will be picked up at runtime to dynamically create a reverse-proxy configuration. This should 'just work' if watch=true and exposedByDefault=false are set in the [docker] section of your traefik.conf. SSL will also 'just work' once you add a matching [[]] entry in there.


In nginx-mode we will generate a bare nginx container that is linked to pleroma. The nginx container is absolutely unmodified and expects to be configured by you. The nginx file in Pleroma's Repository is a good starting point.

We will mount your configs like this:

custom.d/server.nginx -> /etc/nginx/nginx.conf
custom.d/vhost.nginx -> /etc/nginx/conf.d/pleroma.conf

To reach your pleroma container from inside nginx use proxy_pass http://pleroma:4000;.

Set SCRIPT_PORT_HTTP and SCRIPT_PORT_HTTPS to the ports you want to listen on.
Specify the ip to bind to in SCRIPT_BIND_IP. These values are required.

The container only listens on SCRIPT_PORT_HTTPS if SCRIPT_ENABLE_SSL is true.

Apache / httpd

Just like nginx-mode this starts an unmodified apache server that expects to be configured by you.
Again Pleroma's Config is a good starting point.

We will mount your configs like this:

custom.d/server.httpd -> /usr/local/apache2/conf/httpd.conf
custom.d/vhost.httpd -> /usr/local/apache2/conf/extra/httpd-vhosts.conf

To reach your pleroma container from inside apache use ProxyPass [loc] http://pleroma:4000/.


The container only listens on SCRIPT_PORT_HTTPS if SCRIPT_ENABLE_SSL is true.


Values: true / false

If you want to use SSL with your Apache or NGINX containers you'll need a certificate. Certificates need to be placed into custom.d and will be bind-mounted into the server's container at runtime.

We will mount your certs like this:

custom.d/ssl.crt -> /ssl/ssl.crt
custom.d/ssl.key -> /ssl/ssl.key

You can reference them in Apache like this:

<VirtualHost *:443>
    SSLEngine on
    SSLCertificateFile "/ssl/ssl.crt"
    SSLCertificateKeyFile "/ssl/ssl.key"

And in NGINX like this:

listen 443 ssl;
ssl_certificate     /ssl/ssl.crt;
ssl_certificate_key /ssl/ssl.key;

In traefik-mode and manual-mode these files and the SCRIPT_ENABLE_SSL value are ignored.


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.