PostgreSQL 18 Docker Setup

A production-ready Docker Compose configuration for running PostgreSQL 18 (Alpine variant) with persistent storage and fully configurable environment variables.

Features

• 🐘 PostgreSQL 18 Alpine - Lightweight and secure Alpine-based image
• 🔧 Fully Configurable - All settings via environment variables
• 💾 Persistent Storage - Docker volume for data persistence
• 🏥 Health Checks - Built-in health monitoring
• 🔒 Secure - Environment-based credential management
• 🚀 Production Ready - Restart policies and network isolation

Prerequisites

• Docker Engine 20.10+ or Docker Desktop
• Docker Compose 2.0+ (or docker compose plugin)

Quick Start

1. Clone the repository

   git clone https://github.com/talitm555/postgres-18-docker.git
   cd postgres-18-docker

2. Create your environment file

   cp env.sample .env

3. Configure your settings

   Edit .env file with your desired configuration:

   nano .env  # or use your preferred editor

   Update at minimum:

   • POSTGRES_DB - Your database name
   • POSTGRES_USER - Database user
   • POSTGRES_PASSWORD - Strong password (change from default!)

4. Start PostgreSQL

   docker-compose up -d

5. Verify it's running

   docker-compose ps
   docker-compose logs postgres

Configuration

All configuration is done through environment variables in the .env file. See env.sample for all available options:

Essential Settings

Variable	Description	Default
POSTGRES_DB	Database name	myapp
POSTGRES_USER	Database user	postgres
POSTGRES_PASSWORD	Database password	changeme
POSTGRES_PORT	Host port mapping	5432

Advanced Settings

• POSTGRES_CONTAINER_NAME - Custom container name
• POSTGRES_DATA_PATH - Volume mount path in container
• POSTGRES_VOLUME_NAME - Docker volume name
• POSTGRES_NETWORK_NAME - Docker network name
• POSTGRES_INITDB_ARGS - Additional initdb arguments

Usage

Start the database

docker-compose up -d

Stop the database

docker-compose down

Stop and remove volumes (⚠️ deletes all data)

docker-compose down -v

View logs

docker-compose logs -f postgres

Connect to PostgreSQL

Using psql:

docker-compose exec postgres psql -U postgres -d myapp

Or from your host machine:

psql -h localhost -p 5432 -U postgres -d myapp

Backup database

docker-compose exec postgres pg_dump -U postgres myapp > backup.sql

Restore database

docker-compose exec -T postgres psql -U postgres myapp < backup.sql

Data Persistence

Data is stored in a Docker volume named postgres_data (configurable via POSTGRES_VOLUME_NAME). This ensures your data persists across container restarts and updates.

Volume Management

List volumes:

docker volume ls

Inspect volume:

docker volume inspect postgres_data

Backup volume data:

docker run --rm -v postgres_data:/data -v $(pwd):/backup alpine tar czf /backup/postgres_backup.tar.gz /data

Health Check

The container includes a health check that verifies PostgreSQL is ready to accept connections. Check status:

docker-compose ps

Network

The PostgreSQL container runs on an isolated Docker network (postgres_network by default). To connect other containers to the same network:

networks:
  - postgres_network

Security Best Practices

1. Change default credentials - Always update POSTGRES_PASSWORD in .env
2. Use strong passwords - Generate secure passwords for production
3. Restrict port access - Only expose port 5432 if necessary
4. Keep .env private - Never commit .env to version control (already in .gitignore)
5. Regular updates - Keep the PostgreSQL image updated

Troubleshooting

Permission denied errors

If you encounter permission errors, remove the existing volume and start fresh:

docker-compose down -v
docker-compose up -d

Port already in use

If port 5432 is already in use, change POSTGRES_PORT in your .env file:

POSTGRES_PORT=5433

Container won't start

Check the logs for errors:

docker-compose logs postgres

Reset everything

To completely reset (⚠️ deletes all data):

docker-compose down -v
rm .env
cp env.sample .env
# Edit .env with your settings
docker-compose up -d

Upgrading

To upgrade PostgreSQL to a newer version:

1. Backup your data
2. Update the image tag in docker-compose.yml
3. Run:

   docker-compose pull
   docker-compose up -d

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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

Support

• 🐛 Report Issues
• 💡 Request Features
• 📖 PostgreSQL Documentation

Acknowledgments

• PostgreSQL Official Docker Image
• PostgreSQL 18 Release Notes