How to use the Docker images
(Note: the Docker Compose config included in Postmill is for development only. This document covers the published images, available at https://gitlab.com/postmill/Postmill/container_registry)
Postmill uses two Docker images that work in tandem with one another:
appcontains the application code, and launches a FastCGI (php-fpm) server to run it.
weblaunches a web server (nginx) that serves all the front-end assets, as well as forwarding the FastCGI server.
For these images to work together, they must run in the same Docker network with
app container aliased as
php. To store and serve images correctly, the
/app/public/submission_images directories must
be common volumes mounted in both containers.
A simple example
This performs the minimum amount of effort to get Postmill up and running:
$ docker network create postmill $ docker volume create postmill_images $ docker volume create postmill_thumbs $ docker volume create postmill_var $ docker run -d \ --name postmill_db \ --network postmill \ --network-alias db \ --restart always \ -e POSTGRES_USER=postmill \ -e POSTGRES_PASSWORD=secret \ postgres:11-alpine $ docker run -d \ --name postmill \ --network postmill \ --network-alias php \ --restart always \ -e TRUSTED_HOSTS=my.postmill.site.tld \ -v postmill_images:/app/public/submission_images \ -v postmill_thumbs:/app/public/media/cache \ -v postmill_var:/app/var \ registry.gitlab.com/postmill/postmill/app $ docker run -d \ --name postmill_web \ --network postmill \ --restart always \ -v postmill_images:/app/public/submission_images \ -v postmill_thumbs:/app/public/media/cache \ -p 80:80 \ registry.gitlab.com/postmill/postmill/web
To make themes available, run:
$ docker exec postmill bin/console app:theme:sync
Connecting to a database
Postmill needs an external PostgreSQL database to function. This must exist in
the same network as
By default, Postmill tries to connect to the database server
postmill and password
secret. You can override this
by changing the
DATABASE_URL variable in the
app instance (see
Setting up a database).
Persisting cache and sessions
Cache data and sessions are currently stored in
/app/var, with no real way of
using external services for these. Mount this directory to persist cache and
Using a message queue
Postmill sends some tasks to a message queue so they can be handled in the background. By default, the Docker images provide no such queue, and the tasks are instead handled immediately. This means heavy tasks, like downloading images or deleting user accounts, can slow down your Postmill instance quite dramatically.
To mitigate this, it is recommended to set up a RabbitMQ instance, and configure
MESSENGER_DSN to use it (see the
.env file for the syntax).
Using S3-compatible stores for images
Instead of storing and serving images from Docker volumes, you can use an
S3-compatible file store to serve images. Again, the
.env file shows
you how to accomplish this.
You have two choices for HTTPS:
webcontainer to serve on port 443 with your SSL certificate. You can dump SSL-related config in the
/etc/nginx/ssl.conf, and the web server will use this.
webcontainer behind another web server that has HTTPS configured.
If going for this option, you must set the
TRUSTED_HOSTSvariables in the
appcontainer, and your server must send the
X-Forwarded-(For|Proto|Port)headers to Postmill's
Running as another user
By default, Postmill will run as the user
www-data (UID: 82). You can override
this by setting
SU_USER to the username/UID of your choice. When the container
starts, it will grant write permissions to the appropriate files, then start the
PHP-FPM process, dropping privileges in the process.
--user command line argument will not work.
Running as an arbitrary user is quite pointless if using only named volumes.