diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
index fb5c24a8..d909b887 100644
--- a/docker/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -15,6 +15,7 @@ services:
 
   joex:
     image: eikek0/docspell:joex-LATEST
+    container_name: docspell-joex
     restart: unless-stopped
     env_file: ./.env
     ports:
diff --git a/docker/docspell.conf b/docker/docspell.conf
index 9ea246a9..d323911c 100644
--- a/docker/docspell.conf
+++ b/docker/docspell.conf
@@ -1,3 +1,19 @@
+# This is the configuration file for docspell. It contains two main
+# namespaces: docspell.server and docspell.joex. Each provide the
+# config for the respective component.
+#
+# They can be moved to different files, if necessary. For this example
+# though, both components are configured in this single file.
+#
+# Below are only some settings that differ from the default. Please
+# see https://docspell.org/docs/configure/#default-config for all
+# options and their documentation. This page provides deeper
+# information about the important config options.
+#
+# Note: this docker-compose setup is an example to get started. It
+# sets up one rest-server, one joex, a postgres database and a solr –
+# all on the same machine.
+
 docspell.server {
   base-url = "http://localhost:7880"
   bind {
@@ -26,8 +42,15 @@ docspell.server {
   }
 }
 
+# Note to joex: It is currently setup for one instance. Should you
+# want to scale joex instance up (maybe to help processing a batch of
+# files), there are two options:
+#
+# - look at https://github.com/eikek/docspell/pull/552 to elastically
+#   start and stop joex instances via docker-compose
+# - set pool-size to some higher number; this requires to restart joex
+#
 docspell.joex {
-  app-id = "joex-"${HOSTNAME}
   base-url = "http://"${HOSTNAME}":7878"
   bind {
     address = "0.0.0.0"