custom.d | ||
.dockerignore | ||
.env.dist | ||
.gitignore | ||
docker-compose.m4 | ||
docker-config.exs | ||
Dockerfile | ||
entrypoint.sh | ||
initdb.sql | ||
pleroma | ||
README.md |
Pleroma-Docker (Unofficial)
Note: There's a revive effort going on in #5.
Check it out and try develop
if you feel adventurous.
Pleroma is a selfhosted social network that uses OStatus/ActivityPub.
This repository dockerizes it for easier deployment.
#include <public_domain.h>
#include <std_disclaimer.h>
/*
* 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.
*/
Features
- 100% generic
- Everything is customizable
- Zero special host dependencies
- Configuration is not compile-time
- "It just works"
Alternatives
If this setup is a bit overwhelming there are a lot of other great dockerfiles or guides from the community. A few are linked below. This list is not exhaustive and not ordered.
Installing Pleroma
- Clone this repository
- Copy
.env.dist
to.env
- Edit
.env
(see "Configuring Pleroma" section below) - Run
./pleroma build
and./pleroma start
- Profit!
Updating Pleroma
Just run ./pleroma build
again and ./pleroma start
afterwards.
You don't need to shutdown pleroma while compiling the new release.
Every time you run ./pleroma build
the script will fetch all upstream changes and checkout PLEROMA_VERSION
.
This means that setting PLEROMA_VERSION
to a branch enables rolling-release updates while setting
it to a tag or commit-hash pins the version.
Maintaining Pleroma
Pleroma maintenance is usually done with premade mix tasks.
You can run these tasks using ./pleroma mix [task] [arguments...]
.
If you need to fix some bigger issues you can also spawn a shell using ./pleroma enter
.
Customizing Pleroma
Just add your customizations (and their folder structure) to custom.d
.
They will be mounted and symlinked into the right place when the container starts.
You can even replace/patch pleroma's code with this, because the project is recompiled at startup.
In general: Prepending custom.d/
to pleroma's 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
instead of priv/static/instance/thumbnail.jpeg
.
Note: Since custom.d
needs to be accessible at runtime by the pleroma process, the container will automatically chown these files to $UID:$GID
from your .env
file.
Configuring Pleroma
pleroma-docker tries to stay out of your way as much as possible while providing a good experience for both you and your users. It thus supports multiple "operation modes" and quite some config variables which you can mix and match.
This guide will explain some of the tricky .env
file parts as detailed as possible (but you should still read the comments in there).
Since this setup injects code into pleroma that moves it's configuration into the environment (ref "The Twelve-Factor App"),
the built image is 100% reusable and can be shared/replicated across multiple hosts.
To do that just run ./pleroma build
as usual and then tag your image to whatever you want.
Just make sure to start the replicated container with env_file:
or all required -e
pairs.
Storing Data
Currently all data is stored in subfolders of DOCKER_DATADIR
which will be bind-mounted into the container by docker.
We'll evaluate named volumes as an option in the future but they're currently not supported.
Database (SCRIPT_DEPLOY_POSTGRES
)
Values: true
/ false
By default pleroma-docker deploys a postgresql container and links it to pleroma's container as a zero-config data store. If you already have a postgres database or want to host postgres on a physically different machine set this value to false
. Make sure to set the POSTGRES_*
variables when doing that.
Reverse Proxy (SCRIPT_USE_PROXY
)
Values: traefik
/ nginx
/ manual
Pleroma is usually run behind a reverse-proxy. Pleroma-docker gives you multiple options here.
Traefik
In traefik-mode we will generate a pleroma container with traefik 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 [[acme.domains]]
entry.
NGINX
In nginx-mode we will generate a bare nginx container that is linked to the pleroma container. 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/
.
Again setting SCRIPT_PORT_HTTP
, SCRIPT_PORT_HTTPS
and SCRIPT_BIND_IP
is required.
The container only listens on SCRIPT_PORT_HTTPS
if SCRIPT_ENABLE_SSL
is true
.
Manual
In manual mode we do not create any reverse proxy for you. You'll have to figure something out on your own.
This mode also doesn't bind to any IP or port. You'll have to forward something to the container's IP.
SSL (SCRIPT_ENABLE_SSL
)
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"
</VirtualHost>
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.