tstangenberg1/postgres-base repository overview

⁠PostgreSQL Base Image

A PostgreSQL Docker image built from Alpine Linux with embedded data capability. This base image contains no volumes, allowing schema and data to be baked directly into derived images.

⁠Quick Start

# Pull from Docker Hub (automatically selects the right architecture)
docker pull tstangenberg1/postgres-base:latest

# Run the container
docker run -d --name postgres -p 5432:5432 tstangenberg1/postgres-base:latest

# Connect to PostgreSQL
docker exec -it postgres psql -U postgres

⁠Multi-Architecture Support

This image supports multiple architectures:

• linux/amd64 - Intel/AMD 64-bit (x86_64)
• linux/arm64 - ARM 64-bit (Apple Silicon M1/M2, AWS Graviton, Raspberry Pi 4)

Docker automatically pulls the correct image for your platform.

⁠Features

• PostgreSQL with contrib extensions
• Alpine Linux base for minimal size
• No volume declarations - enables embedded data approach
• Pre-initialized database cluster ready for use
• Common extensions included via postgresql17-contrib
• Health checks built-in
• Non-root execution runs as postgres user

⁠Available Tags

Images are automatically built and published to Docker Hub:

• tstangenberg1/postgres-base:latest - Latest build from main branch
• tstangenberg1/postgres-base:17-alpine - PostgreSQL 17 on Alpine
• tstangenberg1/postgres-base:1.0.0 - Specific version releases (when tagged)
• tstangenberg1/postgres-base:1.0 - Minor version
• tstangenberg1/postgres-base:1 - Major version

All tags support both linux/amd64 and linux/arm64 architectures.

⁠Building Locally

If you want to build the image locally:

# Single platform build
docker build -t postgres-base:17-alpine .

# Multi-platform build (requires buildx)
docker buildx build --platform linux/amd64,linux/arm64 -t postgres-base:17-alpine .

⁠Usage Examples

# Pull and run from Docker Hub
docker run -d --name postgres -p 5432:5432 tstangenberg1/postgres-base:latest

# Connect to the database
docker exec -it postgres psql -U postgres

# Check PostgreSQL version
docker exec postgres psql -U postgres -c "SELECT version();"

⁠Available Extensions

The image includes postgresql-contrib which provides extensions such as:

• pg_stat_statements - Track planning and execution statistics
• pgcrypto - Cryptographic functions
• hstore - Key-value store
• uuid-ossp - UUID generation
• btree_gist - GiST index support for btree
• And many more...

To enable an extension:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

⁠Environment Variables

• POSTGRES_USER - Default: postgres
• POSTGRES_DB - Default: postgres
• PGDATA - Default: /var/lib/postgresql/data

⁠Replication Support

This image is pre-configured for PostgreSQL replication with the following settings:

• WAL Level: logical - Supports both physical and logical replication
• Max WAL Senders: 10 - Up to 10 concurrent replication connections
• Max Replication Slots: 10 - Supports replication slots for reliable streaming
• Hot Standby: on - Standby servers can accept read-only queries

⁠Replication Authentication

The image is configured to accept replication connections from any host using MD5 authentication:

host replication all 0.0.0.0/0 md5

This makes it easy to set up streaming replication or logical replication between containers.

⁠Using as a Base for Embedded Data Images

This image is designed to be used as a base for creating images with embedded schema and data:

⁠Example: Create Image with Embedded Data

1. Create a new Dockerfile:

FROM tstangenberg1/postgres-base:latest

# Copy your SQL initialization scripts
COPY init-scripts/01-schema.sql /tmp/
COPY init-scripts/02-data.sql /tmp/

# Run scripts to populate the database
USER root
RUN chown postgres:postgres /tmp/*.sql
USER postgres

RUN pg_ctl -D "$PGDATA" -o "-c listen_addresses=''" -w start && \
    psql -U postgres -d postgres -f /tmp/01-schema.sql && \
    psql -U postgres -d postgres -f /tmp/02-data.sql && \
    pg_ctl -D "$PGDATA" -m fast -w stop && \
    rm /tmp/*.sql

1. Build your custom image:

docker build -t my-app-db:v1.0 .

1. Run your image (data is embedded, no volumes needed):

docker run -d --name my-app-db -p 5432:5432 my-app-db:v1.0

⁠Image Size

Expected size: ~50-80 MB (depending on Alpine package versions)

⁠Health Check

The image includes a health check that runs every 30 seconds:

pg_isready -U postgres

Check health status:

docker inspect --format='{{json .State.Health}}' <container-name>

⁠Security Notes

• Runs as non-root postgres user (UID 70)
• Configured to accept connections from all hosts (0.0.0.0/0)
• Default authentication method: md5

⁠Limitations

• No persistent volumes - Data changes at runtime are lost when container is removed
• Immutable data - Best for testing, demos, or read-only databases
• Not for production with changing data - Use volume-based approach for production

⁠Use Cases

✅ Good for:

• Testing environments with fixed datasets
• Development databases with seed data
• Demo applications
• Distributable database snapshots
• CI/CD pipelines

❌ Not suitable for:

• Production databases with user-generated data
• Applications requiring data persistence across container restarts
• Databases that need regular backups

⁠Troubleshooting

⁠Container won't start

# Check logs
docker logs <container-name>

# Verify PostgreSQL is running
docker exec <container-name> pg_isready -U postgres

⁠Can't connect to database

# Check if port is exposed
docker port <container-name>

# Test connection from host
psql -h localhost -U postgres -d postgres

⁠Check available extensions

docker exec <container-name> psql -U postgres -c "SELECT * FROM pg_available_extensions;"

⁠License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

This image uses PostgreSQL and Alpine Linux, both under their respective open-source licenses.