feat: read managed database passwords from secrets

README.md

@@ -7,7 +7,7 @@ PawSQL is a TLS-terminating PostgreSQL router. It accepts PostgreSQL clients on
 - Go 1.24 or later to build and run PawSQL natively.
 - Docker Engine and a usable `docker` CLI to build the PawSQL image. PawSQL also needs them in its own execution environment when it manages PostgreSQL containers.
 - Optional: a TLS certificate and private key readable by PawSQL. Omit the `tls` block to serve plaintext PostgreSQL; with TLS, the certificate must cover every hostname clients use for SNI routing.
-- Docker Engine access for each `postgres` route. Managed database images are limited to `postgres:16`, `postgres:17`, and `postgres:18`.
+- Docker Engine access for each `postgres` route. Managed database images are limited to `postgres:16`, `postgres:17`, and `postgres:18`; each route also requires a mounted Docker secret file.
 
 ## Build, configure, and run
 
@@ -38,6 +38,7 @@ docker run --rm --publish 5432:5432 \
   --volume "$PWD/Barkfile:/etc/pawsql/Barkfile:ro" \
   --volume "$PWD/tls:/etc/pawsql/tls:ro" \
   --volume /var/run/docker.sock:/var/run/docker.sock \
+  --volume "$PWD/secrets:/run/secrets:ro" \
   pawsql
 ```
 
@@ -66,7 +67,7 @@ pawsql {
         postgres {
             image postgres:17
             volume pawsql-application-data
-            password_env APPLICATION_POSTGRES_PASSWORD
+            password_secret application_postgres_password
             idle_timeout 10m
             traffic_idle_timeout 1h
         }
@@ -76,7 +77,15 @@ pawsql {
 
 `listen` is PawSQL's TCP address. `cert` and `key` identify the client-facing TLS certificate and key. `hostname` is optional; it is used only for SNI routing. `upstream` is the address of an existing PostgreSQL server.
 
-For a managed `postgres` route, `image`, `volume`, and `password_env` are required. On first use, PawSQL reads the named environment variable to create the database container and configures the database and PostgreSQL user with the route's database name. The named Docker volume preserves its data. Set the password environment variable in PawSQL's environment, not in the Barkfile.
+For a managed `postgres` route, `image`, `volume`, and `password_secret` are required. `password_secret` is a short lowercase reference; PawSQL reads it from `/run/secrets/barkstack_<reference>`. The example therefore reads `/run/secrets/barkstack_application_postgres_password`. On first use, PawSQL uses that value to configure the database and PostgreSQL user with the route's database name. The named Docker volume preserves its data.
+
+Create the Docker Swarm secret before running `barkstack init`; Barkstack verifies that every referenced secret exists and mounts it into the PawSQL service:
+
+```sh
+docker secret create barkstack_application_postgres_password /secure/path/application-postgres-password
+```
+
+For a standalone PawSQL container, mount a directory containing the equivalently named file at `/run/secrets`, as shown above. Never put the password value in the Barkfile.
 
 See [`examples/Barkfile`](examples/Barkfile) and its accompanying [`examples/docker-compose.yml`](examples/docker-compose.yml) for a two-route external PostgreSQL example with locally generated development certificates: