Docker

\newpage

You can run [pgagroal][pgagroal] using Docker instead of compiling it manually.

Prerequisites

• [Docker][docker] or [Podman][podman] must be installed on the server where PostgreSQL is running.
• Ensure PostgreSQL is configured to allow external connections.

Update the configuration file if needed:

[pgagroal]
host = *
port = 2345
metrics = 2346
log_type = file
log_level = debug
log_path = /tmp/pgagroal.log
ev_backend = auto

max_connections = 100
idle_timeout = 600
validation = off
unix_socket_dir = /tmp/

[primary]
host = host.docker.internal
port = 5432

pgagroal_hba.conf

#
# TYPE  DATABASE USER  ADDRESS  METHOD
#
host    all      all   all      all

Step 1: Enable External PostgreSQL Access

Modify the local PostgreSQL server's postgresql.conf file to allow connections from outside:

listen_addresses = '*'

Update pg_hba.conf to allow remote connections:

host    all    all    0.0.0.0/0    scram-sha-256

Follow GETTING STARTED for further server setup

Then, restart PostgreSQL for the changes to take effect:

sudo systemctl restart postgresql

Step 2: Clone the Repository

git clone https://github.com/pgagroal/pgagroal.git
cd pgagroal

Step 3: Build the Docker Image

There are two Dockerfiles available:

• Alpine-based image

Using Docker

docker build -t pgagroal:latest -f ./contrib/docker/Dockerfile.alpine .

Using Podman

podman build -t pgagroal:latest -f ./contrib/docker/Dockerfile.alpine .

• Rocky Linux 9-based image

Using Docker

docker build -t pgagroal:latest -f ./contrib/docker/Dockerfile.rocky9 .

Using Podman

podman build -t pgagroal:latest -f ./contrib/docker/Dockerfile.rocky9 .

Step 4: Run pgagroal as a Docker Container

Once the image is built, run the container using:

• Using Docker

docker run -d --name pgagroal \
  -p 2345:2345 \
  -p 2346:2346 \
  --add-host=host.docker.internal:host-gateway \
  pgagroal:latest

• Using Podman

podman run -d --name pgagroal \
  -p 2345:2345 \
  -p 2346:2346 \
  --add-host=host.docker.internal:host-gateway \
  pgagroal:latest

Step 5: Verify the Container

Check if the container is running:

• Using Docker

docker ps | grep pgagroal -->

• Using Podman

podman ps | grep pgagroal

Check logs for any errors:

• Using Docker

docker logs pgagroal

• Using Podman

podman logs pgagroal

You can also inspect the exposed metrics at:

http://localhost:5001/metrics

You can stop the container using

• Using Docker

docker stop ppgagroal

• Using Podman

podman stop ppgagroal

---

We will assume that we have a user called test with the password test in our PostgreSQL instance. See their documentation on how to setup PostgreSQL, add a user and add a database.

We will connect to pgagroal using the psql application.

psql -h localhost -p 2345 -U test test

---

You can exec into the container and run the cli commands as

docker exec -it pgagroal /bin/bash
#or using podman
podman exec -it pgagroal /bin/bash

cd /etc/pgagroal
/usr/local/bin/pgagroal-cli -c pgagroal.conf shutdown

See this for more cli commands.

You can access the three binaries at /usr/local/bin