Configuration

The Postgres image is configured entirely through AUTOPG_* environment variables, alongside the standard POSTGRES_* ones from the official image. Everything below is optional. With no configuration at all, autopg detects the host and tunes for a web workload.

Tuning inputs

These steer the auto-tuning. Anything you leave unset is detected from the host.

Variable	Default	Values	Description
`AUTOPG_DB_TYPE`	`WEB`	`WEB`, `OLTP`, `DW`, `DESKTOP`, `MIXED`	Workload shape.
`AUTOPG_TOTAL_MEMORY_MB`	Detected	Integer (MB)	Memory the database should plan for.
`AUTOPG_CPU_COUNT`	Detected	Integer	CPU count for parallelism.
`AUTOPG_PRIMARY_DISK_TYPE`	Detected	`SSD`, `HDD`, `SAN`	Storage type for I/O costing.
`AUTOPG_NUM_CONNECTIONS`	Per workload	Integer	Max concurrent connections.

pg_stat_statements

Variable	Default	Description
`AUTOPG_ENABLE_PG_STAT_STATEMENTS`	`true`	Preload and create the `pg_stat_statements` extension.

When enabled, the extension is added to shared_preload_libraries, created on first boot, and set to track all statements. This is what the diagnostics dashboard reads from.

Diagnostics dashboard

Variable	Default	Description
`AUTOPG_ENABLE_WEBAPP`	`false`	Serve the diagnostics dashboard.
`AUTOPG_WEBAPP_HOST`	`127.0.0.1`	Dashboard bind address.
`AUTOPG_WEBAPP_PORT`	`8000`	Dashboard port.
`AUTOPG_DB_HOST`	`localhost`	Postgres host the dashboard reads.
`AUTOPG_DB_PORT`	`5432`	Postgres port.
`AUTOPG_DB_NAME`	`postgres`	Database to inspect.
`AUTOPG_DB_USER`	`postgres`	Dashboard database user.
`AUTOPG_DB_PASSWORD`	unset	Password for that user.

See Diagnostics for what the dashboard surfaces.

Custom postgresql.conf

When you need a setting autopg does not manage, or want to pin one of its values, mount your own config:

services:
  postgres:
    image: ghcr.io/piercefreeman/autopg:pg18-latest
    volumes:
      - ./postgresql.conf:/etc/postgresql/postgresql.conf

Your file is layered on top of the generated one, so you only need to specify the values you care about. The original generated config is preserved as postgresql.conf.base for reference.

Precedence

When the same setting could come from more than one place, autopg resolves it in this order, highest priority first:

A value in your mounted postgresql.conf.
An AUTOPG_* environment override.
A value detected from the host.
The built-in default for the workload type.