Docker Compose

This section describes how to setup Papermerge and related services using docker compose.

There are many different setups possible, for example you may want to run only REST API backend with PostgreSQL database. Another, possibility would be to start a REST API backend, workers, frontend, websockets server with PostgreSQL database.

In following sections most common setups are described. Each setup consists of two files - one yml file (compose file) and one environment file usually named .env.

Make sure you have both docker and docker compose installed.

This guide was tested with docker version 20.10.6 and docker-compose version 1.29.2.

Complete Stack

This setup installs complete Papermerge stack with all required services. It uses traefik as edge router.

Save this docker-compose.yml file on your local computer.

Warning

Currently docker tag latest points to latest 2.1.0-alphaXYZ version which is not yet production ready.

Note

See all available docker tags in GitHub packages

Next, create .env file with following content:

APP_IMAGE=ghcr.io/papermerge/papermerge
APP_TAG=latest
PAPERMERGE_JS_IMAGE=ghcr.io/papermerge/papermerge.js
PAPERMERGE_JS_TAG=latest

DB_USER=postgres
DB_NAME=postgres
DB_PASSWORD=postgres
DB_HOST=db
DB_PORT=5432

USE_HOSTNAME=papermerge.local

REDIS_HOST=redis
REDIS_PORT=6379

ES_HOSTS=es
ES_PORT=9200

SECRET_KEY=12345abcdxyz

SUPERUSER_USERNAME=admin
SUPERUSER_EMAIL=admin@example.com
SUPERUSER_PASSWORD=admin

Add to your /etc/hosts following content:

127.0.0.1       papermerge.local

Note

You can add whatever hostname you want e.g. papermerge.myhost just keep in mind that whatever you add in /etc/hosts should match USE_HOSTNAME value from .env file

Note

Variable name to pass hostname is USE_HOSTNAME. This variable used to be named “HOSTNAME” - which caused some problems when accessing Papermerge from remote host. See this comment in github for detailed explanation.

Start Papermerge using following docker compose command:

docker-compose -f docker-compose.yml --env-file .env up

In case you use more recent version for docker:

docker compose -f docker-compose.yml --env-file .env up

You can access Papermerge user interface using a web browser like Firefox. Open your web browser and point it to http://papermerge.local address:

../_images/papermerge-login.png — Sign in screen available at http://papermerge.local

Sign in using credentials configured with SUPERUSER_USERNAME and SUPERUSER_PASSWORD options in .env file.

../_images/papermerge-example.png — Papermerge frontend example

Docker compose started following services:

REST API backend (available at http://papermege.local/api/)
Worker
Redis
PostgreSQL database
Elastic search
Frontend (available at http://papermege.local/)
Websocket server
Traefik (available at http://localhost:8080)

Backend Only

This stack installs only Papermerge REST API backend (without fancy user interface). This setup is suitable mostly to play, experiment and explore Papermerge REST API.

Save following docker-compose.yml file on your local computer.

Next, create .env file with following content:

APP_IMAGE=ghcr.io/papermerge/papermerge
APP_TAG=latest

DB_USER=postgres
DB_NAME=postgres
DB_PASSWORD=postgres
DB_HOST=db
DB_PORT=5432

REDIS_HOST=redis
REDIS_PORT=6379

ES_HOSTS=es
ES_PORT=9200

SECRET_KEY=12345abcdxyz

SUPERUSER_USERNAME=admin
SUPERUSER_EMAIL=admin@example.com
SUPERUSER_PASSWORD=password

Start Papermerge using following docker compose command:

docker-compose -f docker-compose.yml --env-file .env up

The above command will start following services:

REST API backend
Worker
Redis
PostgreSQL database
Elastic search

For REST API backend and the worker docker-compose will use ghcr.io/papermerge/papermerge:2.1.0-alpha-latest docker image.

Now base url for REST API is http://localhost:8000/api/.

External Services

Papermerge requires three external services:

database
redis
elasticsearch

If you want to play with Papermerge outside of docker compose and you don’t want bother about database/redis/elasticsearch services - you can use following compose file to quickly setup these external services:

version: '3.7'
services:
  db:
    image: postgres:13
    volumes:
      - postgres_data2:/var/lib/postgresql/data/
    environment:
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_DB=${DB_NAME}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    ports:
      - 5432:5432
  redis:
    image: redis:6
    ports:
      - 6379:6379
    volumes:
      - redisdata:/data
  es:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.16.2
    environment:
      - discovery.type=single-node
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    ports:
      - 9200:9200
      - 9300:9300
volumes:
  postgres_data2:
  redisdata:

networks:
  my_local:
    driver: host

Note networks uses driver: host, this will start services in same host as you local computer.

.env file content:

DB_USER=postgres
DB_NAME=postgres
DB_PASSWORD=postgres

Following command will start docker services in same network as host:

docker-compose -f services.yml --env-file .env up

Docker compose file will start following services in same host as you computer:

PostgreSQL
Redis
Elasticsearch

At this point if you start let’s say a development version of Papermerge, you can use localhost:6379 to connect to redis or localhost:9300 use elasticsearch.