The docker images are at
always points to the latest release. The releases are also tagged
with their respective version number. Additionally, there are images
nightly which are built from the
nightly packages should be used with care, because
things might break in between. But they are useful for trying out
There are images for all components that are available from the github release page. The images contain all the necessary prerequisites.
docspell/restserverthis images contains the http server
docspell/joexthis image contains the job executor and all required software (ocrmypdf, unoconv etc) mentioned in prerequisites.
docspell/dscthis is an image containing a cli for docspell that can be used to watch directories for new files. It doesn't specify a
ENTRYPOINT, so you must specify the exact command to run. Here, it is used to watch a directory for uploading files. This runs the
These examples use
docker run to start the restserver and
jobexecutor. Both must be connected to the same database. For this
example, a shared directory is used and the in-process database H2.
For a real setup, using PostgreSQL is recommended.
This requires to change the default config. This example creates a new config file. Please refer to the configuration page for more details.
This sets the db url to the same value for both components; thus we
can use the same file for both components. It also sets the bind
address to bind the server socket on all interfaces. Another thing to
note is the
base-url setting for joex. This publishes joex by this
ip, such that the server component can notify the job executor for new
integration-endpoint setting is explained later.
After creating a common network, we start the rest server and joex:
$ docker network create --subnet 10.4.3.0/24 dsnet $ docker run -d --name ds-restserver \ --network dsnet --ip 10.4.3.3 \ -p 127.0.0.1:7880:7880 \ -v /tmp/testdb:/var/docspell \ -v /tmp/docspell.conf:/opt/docspell.conf \ docspell/restserver:latest /opt/docspell.conf $ docker run -d --name ds-joex \ --network dsnet --ip 10.4.3.2 \ -v /tmp/testdb:/var/docspell \ -v /tmp/docspell.conf:/opt/docspell.conf \ docspell/joex:latest /opt/docspell.conf
docker ps should show these two containers. Go to
http://localhost:7880 and sign up/login and start playing around.
When signing up, use the same name for collective and user and then
login with this name.
For the last part, we use the
docspell/dsc image to create another
container that watches a directory and pushes files to docspell.
This starts the dsc tool that watches a
directory and uploads arriving files to the docspell server. This
requires the value from the
integration-endpoint setting to be
allowed to upload files. It also requires you to explicitely enable
this: go to Collective Profile → Settings and enable the
Integration Endpoint. Then create a subdirectory in
with the name of the collective that you registered and place a file
/tmp/inbox/[collective] directory. The file is pushed to
docspell and processed shortly after.
To see all available options, run
dsc with the
Or just download the binary, no docker required.
Note that this is just an example and is only to demonstrate how to
use the docker images. For instance, this setup does not provide
fulltext search. For a more sophisticated docker setup, use
appropriate tools, for example
docker-compose which is explained
There is a docker-compose setup
available in the
/docker/docker-compose folder. This setup is
similiar to the example above, but adding fulltext search and a
PostgreSQL database by using just one command. It's only a few steps
to get started.
1. Get the docker-compose files🔗
There are two options. You can clone the whole repository:
This downloads all sources. What you actually need is only 3 files. So if you don't have git or don't want to clone the whole repo, use these steps instead:
You can choose any directory instead of
docspell/docker/docker-compose, of course. It's only this folder to
make the rest of the guide work for both ways of obtaining the
Change into the new
docker-compose directory, for example:
If you look at
docker-compose.yml, there are several environment
variables defined. A few that you should change, i.e. all "secrets":
Then, the value for
must be duplicated in the consumedir command (both values must match).
It is the header defined for the integration
endpoint. You can use
whatever you like, best something random. Please see the help to the
dsc tool docs for additional info.
http://localhost:7880, signup and login. When signing up,
choose the same name for collective and user. Then login with this
name and the password.
(Optional) Create a folder
./docs/<collective-name> (the name you
chose for the collective at registration) and place files in there for
Docspell can be configured via environment variables or a config file. Please see the configuration for more details and possible values/variables. You can create a config file and mount it into the container. Then specify the config file as the an argument to the command, i.e. add a
command: - /path/to/config.conf
to the service definition (or add it to an existing
Override this setup🔗
If you want to change this setup, you can simply use your own compose
file or add a
docker-compose.override.yml that allows to amend
certain configs. Look here
to find more about it.
As an example, here is a
version: '3.7' services: consumedir: volumes: - importdocs:/opt/docs volumes: docspell-postgres_data: driver: local driver_opts: type: nfs4 o: addr=192.168.x.y,rw,noatime,rsize=8192,wsize=8192,tcp,timeo=14 device: ":/mnt/FreeNas/docker_vol1/docspell/postgres_data" docspell-solr_data: driver: local driver_opts: type: nfs4 o: addr=192.168.x.y,rw,noatime,rsize=8192,wsize=8192,tcp,timeo=14 device: ":/mnt/FreeNas/docker_vol1/docspell/solr_data" importdocs: driver: local driver_opts: type: nfs4 o: addr=192.168.x.y,rw,noatime,rsize=8192,wsize=8192,tcp,timeo=14 device: ":/mnt/FreeNas/archiv/gescannt/output"
Since downgrading is not supported, it is recommended to backup your database before upgrading. Should something not work as expected, restore the database backup and go back to the previous version.
The latest release is always tagged with
latest. Should you use this
tag, then run these commands to upgrade to newer images:
When running the docker compose setup, you can use the following to backup the database.
(Optionally) Stop docspell, for example with
docker-compose down. It is preferred to stop, i.e. should you upgrade versions.
Add a new file
docker-compose.override.yml(next to your
docker-compose.yml) with this content:
version: '3.8' services: db: volumes: - /some/backupdir:/opt/backup
/some/backupdiris the directory where the backup should be stored on the host.
If you stopped the containers in step 1, start now only the db service via
docker-compose up -d -- db
Run the dump command:
docker exec -it postgres_db pg_dump -d dbname -U dbuser -Fc -f /opt/backup/docspell.sqlc
docker-compose.override.yml file is only to mount a local
directory into the db container. You can also add these lines directly
docker-compose.yml. Now you have the dump in your local
This dump can be restored almost the same way. Mount your backup directory into the db container as before in steps 1-3. Then run this command in step 4 instead:
docker exec -it postgres_db pg_restore -d dbname -U dbuser -Fc /opt/backup/docspell.sqlc
So, before the upgrade run steps 1 to 4. Then you have a dump of your current database (everything, files and all other data). When creating and restoring a dump, do not start the docspell containers - make sure to start the db container only.