development: add docs about extended docker overwrites + proper health checks

docker-compose.yml

@@ -11,6 +11,9 @@ services:
     ports:
       - "127.0.0.1:5432:5432"
     command: "-c config_file=/etc/postgresql/postgres.conf"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -U $$POSTGRES_USER -d $$POSTGRES_DB"]
+      interval: 5s
 
   web:
     build: .docker/web
@@ -22,8 +25,13 @@ services:
       - "/code/.venv"
     ports:
       - "127.0.0.1:8000:8000"
+    healthcheck:
+      # -f without -L: the login redirect on / counts as healthy
+      test: ["CMD", "curl", "-fsS", "-o", "/dev/null", "http://127.0.0.1:8000/"]
+      interval: 10s
     depends_on:
-      - db
+      db:
+        condition: service_healthy
 
 volumes:
   postgres-data:

docs/source/extending.rst

@@ -40,6 +40,21 @@ host machines and run uv sync to have all modules available for your
 IDEs auto completion etc.
 
 
+Loading additional apps (overlays)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Apps from other repositories, e.g. ``serveradmin_extras``, can ship a
+``docker-compose.override.yml`` (git-ignored here) that ``docker compose``
+merges automatically.  Symlink it into your checkout::
+
+    ln -s serveradmin_extras/docker-compose.override.yml .
+    docker compose up
+
+Relative paths in the overlay resolve against this directory.  The ``web``
+entrypoint installs ``$SERVERADMIN_EXTRA_INSTALL`` editable after the core
+``uv sync``, optionally from the package index ``$SERVERADMIN_EXTRA_INDEX``.
+
+
 Database Dump
 -------------