truly persistent volumes

docs/Deployment.md

@@ -19,6 +19,22 @@ This will generate six named volumes to make sure that all relevant data will pe
 !!! warning
     The above will make the API available on port 80 of the host machine **without SSL/TLS protection**. You can use this for local testing, but do not expose this directly to the internet, it is completely insecure!
 
+!!! warning
+    The six named volumes generated from the above example may be removed when issuing `docker compose down`. In order to have truly persistent volumes that will not be removed by docker compose, first create the volumes like this:
+
+    ```
+    docker volume create gramps_users
+    docker volume create gramps_index
+    docker volume create gramps_thumb_cache
+    docker volume create gramps_cache
+    docker volume create gramps_secret
+    docker volume create gramps_db
+    docker volume create gramps_media
+    docker volume create gramps_tmp
+    ```
+
+    Then insert the following contents in your `docker-compose.yml`: [docker-compose.yml](https://raw.githubusercontent.com/gramps-project/gramps-web-docs/main/examples/docker-compose-external-volumes/docker-compose.yml).
+
 ## Step 2: Secure access with SSL/TLS
 
 The web API **must** be served to the public internet over HTTPS. There are several options, e.g.
@@ -50,4 +66,4 @@ There are several options for uploading media files.
 
 - When using files stored on the same server as Gramps Web, you can mount a directory into the Docker container instead of using a named volume, i.e. `/home/server_user/gramps_media/:/app/media`instead of `gramps_media:/app/media`, and upload your media files there.
 - When using media files [hosted on S3](s3.md), you can use he S3 Media Uploader Addon
-- The arguably most convenient option is to use [Gramps Web Sync](user-guide/sync.md).
+- The arguably most convenient option is to use [Gramps Web Sync](user-guide/sync.md).

examples/docker-compose-external-volumes/docker-compose.yml

@@ -0,0 +1,61 @@
+services:
+  grampsweb: &grampsweb
+    image: ghcr.io/gramps-project/grampsweb:latest
+    restart: always
+    ports:
+      - "80:5000"  # host:docker
+    environment:
+      GRAMPSWEB_TREE: "Gramps Web"  # will create a new tree if not exists
+      GRAMPSWEB_CELERY_CONFIG__broker_url: "redis://grampsweb_redis:6379/0"
+      GRAMPSWEB_CELERY_CONFIG__result_backend: "redis://grampsweb_redis:6379/0"
+      GRAMPSWEB_RATELIMIT_STORAGE_URI: redis://grampsweb_redis:6379/1
+    depends_on:
+      - grampsweb_redis
+    volumes:
+      - gramps_users:/app/users  # persist user database
+      - gramps_index:/app/indexdir  # persist search index
+      - gramps_thumb_cache:/app/thumbnail_cache  # persist thumbnails
+      - gramps_cache:/app/cache  # persist export and report caches
+      - gramps_secret:/app/secret  # persist flask secret
+      - gramps_db:/root/.gramps/grampsdb  # persist Gramps database
+      - gramps_media:/app/media  # persist media files
+      - gramps_tmp:/tmp
+
+  grampsweb_celery:
+    <<: *grampsweb  # YAML merge key copying the entire grampsweb service config
+    ports: []
+    container_name: grampsweb_celery
+    depends_on:
+      - grampsweb_redis
+    command: celery -A gramps_webapi.celery worker --loglevel=INFO
+
+  grampsweb_redis:
+    image: docker.io/library/redis:7.2.4-alpine
+    container_name: grampsweb_redis
+    restart: always
+
+volumes:
+  gramps_users:
+    external: true
+    name: gramps_users
+  gramps_index:
+    external: true
+    name: gramps_index
+  gramps_thumb_cache:
+    external: true
+    name: gramps_thumb_cache
+  gramps_cache:
+    external: true
+    name: gramps_cache
+  gramps_secret:
+    external: true
+    name: gramps_secret
+  gramps_db:
+    external: true
+    name: gramps_db
+  gramps_media:
+    external: true
+    name: gramps_media
+  gramps_tmp:
+    external: true
+    name: gramps_tmp