postgres-setup

A utility for creating a customized, rootless PostgreSQL container image with the option of including extensions from custom compiled ones to contrib.

Base Image: openSUSE Leap 16.0
PostgreSQL Version: 18.1 (Compiled from source)

Pre-requisites

OS: Linux-based.

Required Tools

Package	Version	Notes
Python	3.13+	Core language the CLI tool is written in.
Poetry	2.2.1+	Project dependency manager.
Buildah	1.41.5+	Used to programmatically create OCI-compliant container images without a daemon.
Taskfile	3.46.3+	Optional. You can use the provided shell script wrapper (./taskw) which scopes the binary to the project.

Usage

List available tasks:

./taskw --list

Setup python virtual environment and install dependencies:

TASKFILE_BINARY="./taskw"

$TASKFILE_BINARY deps

View CLI tool options and build help:

TASKFILE_BINARY="./taskw"

$TASKFILE_BINARY run -- --help

Example

Build postgres binaries from source:

TASKFILE_BINARY="./taskw"

$TASKFILE_BINARY run -- containers core build

Build postgis extension:

TASKFILE_BINARY="./taskw"

$TASKFILE_BINARY run -- containers extensions postgis,pgvector,rum build

Build postgres runtime with postgis extension:

TASKFILE_BINARY="./taskw"

$TASKFILE_BINARY run -- containers runtime build --extensions postgis

Sample script to run the built postgres container using podman.

#!/bin/bash

CONTAINER="postgres18.1"
NETWORK="tumbleweed"
NETWORK_ALIAS="postgres18.1"
CONTAINER_UID=26
HOST_PORT=5432
VOLUME="postgres"
ENV_POSTGRES_PASSWORD="postgres2025"
IMAGE="localhost/postgres:18.1"

podman volume exists $VOLUME || podman volume create $VOLUME

podman unshare chown -R $CONTAINER_UID:$CONTAINER_UID $(podman volume inspect $VOLUME --format '{{.Mountpoint}}')

podman run -d \
        --name $CONTAINER \
        --network $NETWORK \
        --network-alias $NETWORK_ALIAS \
        --user $CONTAINER_UID:$CONTAINER_UID \
        -p $HOST_PORT:5432 \
        -v $VOLUME:/var/lib/pgsql/data \
        -e POSTGRES_PASSWORD="$ENV_POSTGRES_PASSWORD" \
        $IMAGEp

Application Container Image Features

Extensions

Postgres provides a comprehensive set of extensions via its contrib package which is built by default.

In addition, an additional set of extensions that have to be built/sourced elsewhere are provided by the CLI tool.

Below is a sample set of extensions grouped by use-cases.

Geospatial

Extension	Version	Description
postgis	3.6.1	Adds geospatial capabilities. Provides geometry and geography types.
postgis topology		Manage topological data (shared boundaries between shapes)
address_standardizer		Normalizes address strings into parts (street, city, zip)

Semantic & AI Search

Extension	Version	Description
pgvector	0.8.1	Adds vector search capabilities. Provides vector type, and hnsw and ivfflat indexes.
btree_gin		Manage topological data (shared boundaries between shapes)
address_standardizer	Built-in via contrib	Allows standard types (int, uuid) to be indexed in GIN. Combine vectory query with hard scalar filter.

Advanced Text Search

Extension	Version	Description
rum	1.3.15	RUM Index - Inverted index that stores weights and positions alongside terms. Good for fast ranking for search results by relevance or timestamps.
pg_trgm	Built-in via contrib	Break text into 3 character trigrams for similarity comparison. Good for fuzzy search (suggestions) and typo tolerance.
fuzzystrmatch	Built-in via contrib	Algorithms for string phonetics (soundex, metaphone, levenshtein). Good for matching names that sound similar but are spelled differently.
unaccent	Built-in via contrib	Removes accents/diacritics from text.

Performance and maintenance

Extension	Version	Description
pg_stat_statements	Built-in via contrib	Tracks execution statistics of all SQL statements.
pg_buffercache	Built-in via contrib	Inspects the contents of the shared buffer cache (RAM). Debugging why specific tables are "hot" or getting evicted from memory.
auto_explain	Built-in via contrib	Automatically logs the execution plan of slow queries.
pg_visibility	Built-in via contrib	Inspects the visibility map and page-level details.

Data Types & Utilities

Extension	Version	Description
uuid-ossp	Built-in via contrib	Generates UUIDs (v1, v4, etc.).
citext	Built-in via contrib	Case-insensitive text type. Emails/Usernames: Handles User@Example.com = user@example.com automatically.
hstore	Built-in via contrib	Key-value store within a single column.
pgcrypto	Built-in via contrib	Cryptographic functions (hashing, encryption).

Ports

Port	Purpose
5432	Default PostgreSQL Port. Map this to your host using -p 5432:5432 to access the database.

Volumes

Path	Purpose
/var/lib/pgsql/data/18	Data Directory. Stores all database files (tables, WAL, indexes). Note: Ensure you mount a volume here to persist data across restarts.

Environment variables

Name	Default	Purpose
POSTGRES_USER	postgres	Sets the superuser for the database.
POSTGRES_PASSWORD	(None)	Sets the password for the superuser. Highly Recommended for security.
PGDATA	/var/lib/pgsql/data/18	Internal pointer to the data volume. Generally should not be changed.