add scaling to Docker Compose setup

Author: tomkralidis

docker/compose/docker-compose.scale.yml

@@ -0,0 +1,77 @@
+# =================================================================
+#
+# Authors: Ricardo Garcia Silva <ricardo.garcia.silva@gmail.com>
+# Authors: Tom Kralidis <tomkralidis@gmail.com>
+#
+# Copyright (c) 2017 Ricardo Garcia Silva
+# Copyright (c) 2025 Tom Kralidis
+#
+# Permission is hereby granted, free of charge, to any person
+# obtaining a copy of this software and associated documentation
+# files (the "Software"), to deal in the Software without
+# restriction, including without limitation the rights to use,
+# copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the
+# Software is furnished to do so, subject to the following
+# conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+# OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+# OTHER DEALINGS IN THE SOFTWARE.
+#
+# =================================================================
+#
+#
+# This docker compose file demos how to use the pycsw docker image with a
+# PostgreSQL/PostGIS database.
+#
+# docker compose usage:
+#
+# docker compose up
+#
+# docker stack (in a docker swarm):
+#
+# PYCSW_DOCKER_IMAGE=2.1-dev docker stack deploy --compose-file docker-compose.yml pycsw
+#
+
+services:
+  db:
+    container_name: db
+    image: postgis/postgis:12-3.0-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: mypass
+      POSTGRES_DB: pycsw
+      PGDATA: /var/lib/postgresql/data/pgdata
+    volumes:
+      - db-data:/var/lib/postgresql/data/pgdata
+    ports:
+      - 5432:5432
+    networks:
+      - pycsw-net
+  pycsw:
+    image: geopython/pycsw:${PYCSW_DOCKER_IMAGE}
+    environment:
+        PYCSW_SERVER_URL: http://localhost:8000
+    # deploy 5 instances of pycsw, from ports 8000-8004
+    deploy:
+      replicas: 5
+    ports:
+      - 8000-8004:8000
+    volumes:
+      - ./pycsw.yml:/etc/pycsw/pycsw.yml
+    networks:
+      - pycsw-net
+  networks:
+  pycsw-net:
+
+volumes:
+  db-data:

docker/compose/docker-compose.yml

@@ -4,7 +4,7 @@
 # Authors: Tom Kralidis <tomkralidis@gmail.com>
 #
 # Copyright (c) 2017 Ricardo Garcia Silva
-# Copyright (c) 2020 Tom Kralidis
+# Copyright (c) 2025 Tom Kralidis
 #
 # Permission is hereby granted, free of charge, to any person
 # obtaining a copy of this software and associated documentation
@@ -33,19 +33,16 @@
 # This docker compose file demos how to use the pycsw docker image with a
 # PostgreSQL/PostGIS database.
 #
-# docker-compose usage:
+# docker compose usage:
 #
-# docker-compose up
+# docker compose up
 #
 # docker stack (in a docker swarm):
 #
 # PYCSW_DOCKER_IMAGE=2.1-dev docker stack deploy --compose-file docker-compose.yml pycsw
 #
 
-version: "3.8"
-
 services:
-
   db:
     container_name: db
     image: postgis/postgis:12-3.0-alpine
@@ -58,7 +55,8 @@ services:
       - db-data:/var/lib/postgresql/data/pgdata
     ports:
       - 5432:5432
-
+    networks:
+      - pycsw-net
   pycsw:
     container_name: pycsw
     image: geopython/pycsw:${PYCSW_DOCKER_IMAGE}
@@ -68,7 +66,11 @@ services:
       - 8000:8000
     volumes:
       - ./pycsw.yml:/etc/pycsw/pycsw.yml
+    networks:
+      - pycsw-net
 
+networks:
+  pycsw-net:
 
 volumes:
   db-data:

docs/docker.rst

@@ -114,7 +114,7 @@ PostgreSQL repositories
 Specifying a PostgreSQL repository is just a matter of configuring a custom
 pycsw.yml file with the correct specification.
 
-Check `pycsw's github repository`_ for an example of a docker-compose/stack
+Check `pycsw's GitHub repository`_ for an example of a docker compose/stack
 file that spins up a postgis database together with a pycsw instance.
 
 
@@ -175,6 +175,36 @@ example by running::
 
     firefox docs/_build/html/index.html
 
+Docker Compose
+==============
+
+For `Docker Compose`_ deployment, run the following in ``docker/compose``:
+
+.. code-block:: bash
+
+  PYCSW_DOCKER_IMAGE=latest docker compose up
+
+
+.. note::
+
+  The ``PYCSW_DOCKER_IMAGE`` setting is required to set the Docker image version/tag.
+
+
+Scaling
+-------
+
+To scale via Docker Compose, run the following in ``docker/compose``:
+
+.. code-block:: bash
+
+  PYCSW_DOCKER_IMAGE=latest docker compose -f docker-compose.scale.yml up
+
+.. note::
+
+  In ``docker/compose/docker-compose.scale.yml``, adjust the ``services.pycsw.deploy``
+  and services.pycsw.ports values to scale accordingly.  The port range specified must
+  match the number of replicas defined.
+
 Kubernetes
 ==========
 
@@ -200,6 +230,7 @@ For Kubernetes deployment via `Helm`_, run the following in ``docker/helm``:
 .. _`Docker`: https://www.docker.com
 .. _`geopython Docker Hub`: https://hub.docker.com/r/geopython/pycsw
 .. _`GitHub Container Registry`: https://github.com/geopython/pycsw/pkgs/container/pycsw
-.. _pycsw's github repository: https://github.com/geopython/pycsw/tree/master/docker
-.. _Kubernetes: https://kubernetes.io/
-.. _Helm: https://helm.sh
+.. _pycsw's GitHub repository: https://github.com/geopython/pycsw/tree/master/docker
+.. _`Docker Compose`: https://docs.docker.com/compose
+.. _`Kubernetes`: https://kubernetes.io/
+.. _`Helm`: https://helm.sh