Configuration using env vars. Adding standby works.

README.md

@@ -0,0 +1,60 @@
+Postgres image with PostGIS and pg_auto_failover extensions that allows running a high-availability Postgres cluster with query load-balancing.
+
+# How to use this image
+
+The expected configuration is at least two `worker` nodes with one `monitor` node. The container is expected to have one or more peer configuration containers that implement query load balancing (activated using `AUTOCONFIG_LOCAL_PEER` and/or `AUTOCONFIG_REMOTE_PEERS`). One of such implementations is [docker-pgpool](/docker-pgpool) that implements read-only/read-write splitting and load balancing using `pgpool`. Another is [docker-pgtraefik](/docker-pgtraefik) that load balances all traffic to the primary node.
+
+The configuration peers act as servers and this image connects to them. They can run either locally communicating over a socket or remotely over HTTP.
+
+# Environmental variables
+
+## General
+
+- `AUTOCONFIG_LOG_LEVEL` Log level of the application that manages the execution (one of `trace`, `debug`, `info`, `warn`, `error`, `fatal`). Default `info`. Optional.
+- `AUTOCONFIG_MODE` Determines the role of the container. Either
+  - empty/not set to get the behaviour of plain Postgres image
+  - `monitor` this container becomes a monitor (only one container should have this set)
+  - `postgres` this container becomes a worker (usually at least two containers have this)
+
+  No default. Required
+- `AUTOCONFIG_FORMATION` Name of the pg_auto_failover formation. Default `default`. Optional
+- `AUTOCONFIG_MONITOR_HOST` Hostname of the monitor node. Default none. Required.
+- `AUTOCONFIG_MONITOR_PORT` Postgres port on the monitor node. Default `PGPORT` and if not set `5432`. Optional.
+- `AUTOCONFIG_LOCAL_PEER` True if configuration peer container is running locally and is reachable over a socket. Default `false`. Optional.
+- `AUTOCONFIG_SOCKET` Path to the socket of the locally run peer configuration container. Default `/var/run/pg_autoconfig.sock`. Optional.
+- `AUTOCONFIG_REMOTE_PEERS` Hostnames with remote configuration peers separated by comma. Each hostname has format `hostname[:port]` (default port 5420). Default none. Optional.
+
+## Security
+
+- `AUTOCONFIG_MONITOR_PASSWORD` or `AUTOCONFIG_MONITOR_PASSWORD_FILE` password (resp. path to file with the password) that is set on the monitor node for the user `autoctl_node` and worker nodes use it to report their status in pg_auto_failover. Default none. Required.
+- `AUTOCONFIG_REPLICATION_PASSWORD` or `AUTOCONFIG_REPLICATION_PASSWORD_FILE` password (resp. path to file with the password)  that is set on the worker nodes for the user `pgautofailover_replicator` that allows other nodes to fetch state from the currently primary node
+- `POSTGRES_USERNAME` Postgres admin user name
+- `POSTGRES_PASSWORD` or `POSTGRES_PASSWORD_FILE` password (resp. path to file with the password) that is set for the user Postgres admin user
+- `AUTOCONFIG_LINK_HBA_CONF` path to `pg_hba.conf` file that shall be linked to after the Postgres storage gets initialized (Postgres refuses to initialize non-empty directory with `pg_hba.conf` volume-binded from docker host). Default none. Optional.
+
+This image does not deploy nor touch the Postgres file `pg_hba.conf`. You are expected to deploy it by whatever tools you have for it into some directory outside of `PGDATA`. However following rules are required for `pg_auto_failure` to work on monitor:
+- `local all all`
+- `host pg_auto_failover autoctl_node <worker ip address> scram-sha-256` (for each worker)
+
+on worker:
+- `local all all`
+- `host all pgautofailover_monitor <monitor ip address> trust`
+- `host replication pgautofailover_replicator <worker ip address> scram-sha-256` (for each oher worker)
+
+## pg_auto_failover
+- `XDG_CONFIG_HOME` Persistent storage for pg_auto_failover configuration
+- `XDG_DATA_HOME` Persistent state of pg_auto_failover
+
+See others in the pg_auto_failover documentation.
+
+## Postgres
+- `PGDATA` path to Postgres persistent storage.
+- `PGPORT` port for Postgres to listen on. Default 5432. Optional.
+- `POSTGRES_USERNAME` (see above)
+- `POSTGRES_PASSWORD` or `POSTGRES_PASSWORD_FILE` (see above)
+
+See others in postgres docker image documentation.
+
+# Runtime status
+
+You can check the state of the cluster by executing `pg_autoctl show state --formation <formation name ie. default>` in the container.