diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 0000000..decaff9 --- /dev/null +++ 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 new file mode 100644 index 0000000..088b6b6 --- /dev/null +++ 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 new file mode 100644 index 0000000..273776d --- /dev/null +++ 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 index 7afbe95..3c5b056 100644 --- 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\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 index 1e9f15d..811fc12 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,54 @@

Dockette / PgBouncer

- Minimal Docker image for PgBouncer, a connection pooler for PostgreSQL. This tag mirrors dhi.io/pgbouncer under the dockette/pgbouncer name on Docker Hub. + GitHub Actions + Docker Hub pulls + GitHub Sponsors + Support/Discussions

-🕹 f3l1x.io | 💻 f3l1x | 🐦 @xf3l1x + PgBouncer, the connection pooler for PostgreSQL, in a Docker image. It is a thin republish of dhi.io/pgbouncer under the dockette/pgbouncer name, for anyone who runs a connection pool in front of PostgreSQL.

- GitHub Actions - Docker Hub pulls - GitHub Sponsors - Support/Discussions +🕹 f3l1x.io | 💻 f3l1x | 🐦 @xf3l1x

----- ## 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.