f3l1x · Sep 28, 2026 · Sep 28, 2026 · Sep 28, 2026 · Sep 28, 2026 · Sep 29, 2026
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,17 @@
+# EditorConfig is awesome: http://EditorConfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[Makefile]
+indent_style = tab
+
+[*.{json,yml,yaml}]
+indent_size = 2
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,27 @@
+# Dockette / PgBouncer
+
+PgBouncer connection pooler for PostgreSQL, republished from the upstream hardened image.
+
+## Stack
+
+- Docker image built with `docker buildx`, base `dhi.io/pgbouncer`
+- PgBouncer 1.26.0
+- Published to Docker Hub as `dockette/pgbouncer` for linux/amd64 by GitHub Actions
+
+## Development
+
+```bash
+make build       # build the image
+make test        # smoke test the image
+make run         # run it locally on port 6432 (PGBOUNCER_CONFIG=pgbouncer.ini)
+```
+
+`make build DOCKER_TAG=1.26.0` builds one PgBouncer version.
+
+## Principles
+
+- KISS: one image does one job; no extra services or tools.
+- DRY: shared steps live in the base image, not copied into every Dockerfile.
+- YAGNI: add a package only when the image needs it.
+- Pin versions, keep layers small, clean package caches in the same `RUN`.
+- Every change is built and smoke tested with `make build test` before a commit.
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dockette
+
+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.
diff --git a/Makefile b/Makefile
@@ -5,17 +5,27 @@ PGBOUNCER_CONFIG?=pgbouncer.ini
 PGBOUNCER_USERLIST?=
 PGBOUNCER_USERLIST_VOLUME=$(if $(PGBOUNCER_USERLIST),-v "${PGBOUNCER_USERLIST}:/etc/pgbouncer/userlist.txt:ro")
 
+.DEFAULT_GOAL := help
+
+##@ Help
+
+.PHONY: help
+help: ## Show this help
+	@awk 'BEGIN {FS = ":.*##"; printf "Usage: make \033[36m<target>\033[0m\n"} /^[a-zA-Z0-9_.-]+:.*##/ { sub(/^ +/, "", $$2); printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) }' $(firstword $(MAKEFILE_LIST))
+
+##@ Docker
+
 .PHONY: build
-build:
+build: ## Build the image
 	docker buildx build --platform ${DOCKER_PLATFORMS} \
 		--build-arg PGBOUNCER_VERSION=${DOCKER_TAG} \
 		-t ${DOCKER_IMAGE}:${DOCKER_TAG} \
 		.
 
 .PHONY: test
-test:
+test: ## Smoke test the image
 	docker run --rm --platform ${DOCKER_PLATFORMS} ${DOCKER_IMAGE}:${DOCKER_TAG} pgbouncer --version
 
 .PHONY: run
-run:
+run: ## Run the image locally (PGBOUNCER_CONFIG=/abs/path/pgbouncer.ini)
 	docker run --rm -it --platform ${DOCKER_PLATFORMS} -p 6432:6432 -v "${PGBOUNCER_CONFIG}:/etc/pgbouncer/pgbouncer.ini:ro" ${PGBOUNCER_USERLIST_VOLUME} ${DOCKER_IMAGE}:${DOCKER_TAG}
diff --git a/README.md b/README.md
@@ -1,57 +1,54 @@
 <h1 align=center>Dockette / PgBouncer</h1>
 
 <p align=center>
-   Minimal Docker image for <a href="https://www.pgbouncer.org/">PgBouncer</a>, a connection pooler for PostgreSQL. This tag mirrors <code>dhi.io/pgbouncer</code> under the <code>dockette/pgbouncer</code> name on Docker Hub.
+   <a href="https://github.com/dockette/pgbouncer/actions"><img src="https://github.com/dockette/pgbouncer/actions/workflows/docker.yml/badge.svg" alt="GitHub Actions"></a>
+   <a href="https://hub.docker.com/r/dockette/pgbouncer"><img src="https://img.shields.io/docker/pulls/dockette/pgbouncer.svg" alt="Docker Hub pulls"></a>
+   <a href="https://github.com/sponsors/f3l1x"><img src="https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ea4aaa" alt="GitHub Sponsors"></a>
+   <a href="https://github.com/orgs/dockette/discussions"><img src="https://img.shields.io/badge/support-discussions-6f42c1" alt="Support/Discussions"></a>
 </p>
 
 <p align=center>
-🕹 <a href="https://f3l1x.io">f3l1x.io</a> | 💻 <a href="https://github.com/f3l1x">f3l1x</a> | 🐦 <a href="https://twitter.com/xf3l1x">@xf3l1x</a>
+   <a href="https://www.pgbouncer.org/">PgBouncer</a>, the connection pooler for PostgreSQL, in a Docker image. It is a thin republish of <code>dhi.io/pgbouncer</code> under the <code>dockette/pgbouncer</code> name, for anyone who runs a connection pool in front of PostgreSQL.
 </p>
 
 <p align=center>
-   <a href="https://github.com/dockette/pgbouncer/actions"><img src="https://github.com/dockette/pgbouncer/actions/workflows/docker.yml/badge.svg" alt="GitHub Actions"></a>
-   <a href="https://hub.docker.com/r/dockette/pgbouncer"><img src="https://img.shields.io/docker/pulls/dockette/pgbouncer.svg" alt="Docker Hub pulls"></a>
-   <a href="https://github.com/sponsors/f3l1x"><img src="https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ea4aaa" alt="GitHub Sponsors"></a>
-   <a href="https://github.com/orgs/dockette/discussions"><img src="https://img.shields.io/badge/support-discussions-6f42c1" alt="Support/Discussions"></a>
+🕹 <a href="https://f3l1x.io">f3l1x.io</a> | 💻 <a href="https://github.com/f3l1x">f3l1x</a> | 🐦 <a href="https://twitter.com/xf3l1x">@xf3l1x</a>
 </p>
 
 -----
 
 ## Usage
 
-Mount your `pgbouncer.ini` (and optional userlist) and expose the pool port (default **6432**):
+Mount your own `pgbouncer.ini` and run it:
 
 ```sh
-docker run --name some-pgbouncer -p 6432:6432 \
-  -v /path/to/pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini:ro \
-  dockette/pgbouncer:1.26.0
+docker run -v ./pgbouncer.ini:/etc/pgbouncer/pgbouncer.ini:ro dockette/pgbouncer
 ```
 
-Minimal `pgbouncer.ini` sketch (adjust `host`, auth, and pool names for your setup):
+The image is upstream PgBouncer with nothing added: no default config, no environment variables. Everything is
+set in `pgbouncer.ini` (plus `userlist.txt` if you use `auth_file`), see the
+[configuration reference](https://www.pgbouncer.org/config.html).
 
-```ini
-[databases]
-* = host=postgres port=5432
+## Versions
 
-[pgbouncer]
-listen_addr = 0.0.0.0
-listen_port = 6432
-auth_type = md5
-auth_file = /etc/pgbouncer/userlist.txt
-pool_mode = transaction
-max_client_conn = 100
-default_pool_size = 20
-```
+| Tag | Upstream |
+|-----|----------|
+| `dockette/pgbouncer:1.26.0` | `dhi.io/pgbouncer:1.26.0` |
+| `dockette/pgbouncer:latest` | Same as `1.26.0` |
 
-## Versions
+Older version tags stay on [Docker Hub](https://hub.docker.com/r/dockette/pgbouncer/tags) unchanged, so you can pin
+them.
+
+## Development
 
-| Image tag | Equivalent upstream | Docker Hub |
-|-----------|---------------------|------------|
-| `dockette/pgbouncer:1.26.0` | `dhi.io/pgbouncer:1.26.0` | [tags](https://hub.docker.com/r/dockette/pgbouncer/tags/) |
-| `dockette/pgbouncer:latest` | same as `1.26.0` (rolling) | [tags](https://hub.docker.com/r/dockette/pgbouncer/tags/) |
+```sh
+make build   # build the image
+make test    # smoke test it
+make run     # run it locally
+```
 
-The image is a thin republish: builds use `FROM dhi.io/pgbouncer:${PGBOUNCER_VERSION}` so runtime behavior matches that upstream tag.
+Run `make` to list every target.
 
 ## Maintenance
 
-See [how to contribute](https://github.com/dockette/.github/blob/master/CONTRIBUTING.md) to this package. Consider to [support](https://github.com/sponsors/f3l1x) **f3l1x**. Thank you for using this package.
+See [how to contribute](https://github.com/dockette/.github/blob/master/CONTRIBUTING.md) to this package. Consider [supporting](https://github.com/sponsors/f3l1x) **f3l1x**. Thank you for using this package.