Docker Configuration - BD Scan Face

BD Scan Face uses Docker Compose to simplify database setup and management. This guide covers the complete Docker configuration and common operations.

Docker Compose Configuration

The project includes a docker-compose.yml file that defines a PostgreSQL database service with optimized settings for development.

Complete Configuration

docker-compose.yml

version: '3.7'
services: 
  postgres: 
    image: postgres:15
    restart: always
    environment: 
      - POSTGRES_DB=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=prisma
    ports: 
      - "5432:5432"
    networks: 
      - prisma-network 
    healthcheck: 
      test: ["CMD-SHELL", "pg_isready -U prisma -d postgres"] 
      interval: 5s
      timeout: 2s
      retries: 20
    volumes: 
      - postgres_data:/var/lib/postgresql/data
    command: postgres -c listen_addresses='*'
    logging: 
      options: 
        max-size: "10m"
        max-file: "3"
networks: 
  prisma-network: 
volumes: 
  postgres_data:

Configuration Breakdown

Service Configuration

Base Image

image: postgres:15

Uses PostgreSQL version 15, providing the latest stable features and performance improvements.

Restart Policy

restart: always

The container automatically restarts if it crashes or if Docker restarts, ensuring high availability during development.

Environment Variables

environment: 
  - POSTGRES_DB=postgres
  - POSTGRES_USER=postgres
  - POSTGRES_PASSWORD=prisma

Variable	Value	Description
`POSTGRES_DB`	`postgres`	Default database name
`POSTGRES_USER`	`postgres`	PostgreSQL superuser
`POSTGRES_PASSWORD`	`prisma`	Password for authentication

Security Notice: Change the default password in production environments. Never commit production credentials to version control.

Port Mapping

ports: 
  - "5432:5432"

Maps PostgreSQL’s default port (5432) from the container to your host machine, allowing direct database access.

If port 5432 is already in use, change the host port: "5433:5432"

Health Checks

healthcheck: 
  test: ["CMD-SHELL", "pg_isready -U prisma -d postgres"] 
  interval: 5s
  timeout: 2s
  retries: 20

Parameter	Value	Description
`test`	`pg_isready` command	Checks if PostgreSQL is ready to accept connections
`interval`	5 seconds	Time between health checks
`timeout`	2 seconds	Maximum time for check to complete
`retries`	20	Number of consecutive failures before marking unhealthy

Health checks ensure the database is fully initialized before your application connects.

Volume Management

volumes: 
  - postgres_data:/var/lib/postgresql/data

Persists database data in a named Docker volume, ensuring data survives container restarts and removals.

Network Configuration

networks: 
  - prisma-network

Creates an isolated network for database communication, enabling secure inter-container connections.

PostgreSQL Command

command: postgres -c listen_addresses='*'

Configures PostgreSQL to accept connections from all network interfaces, necessary for Docker networking.

Logging Configuration

logging: 
  options: 
    max-size: "10m"
    max-file: "3"

Limits each log file to 10MB
Keeps a maximum of 3 log files
Prevents disk space issues from excessive logging

Managing Containers

Starting the Database

Start in Detached Mode

docker-compose up -d

Starts the PostgreSQL container in the background.

Verify Container Status

docker-compose ps

Expected output:

NAME                    IMAGE         STATUS         PORTS
bd_scan_face_postgres_1 postgres:15   Up (healthy)   0.0.0.0:5432->5432/tcp

Wait for Health Check

docker-compose ps

Wait until the status shows Up (healthy) before connecting.

To view startup logs in real-time, omit the -d flag: docker-compose up

Stopping the Database

docker-compose stop

Using docker-compose down -v deletes all database data. Use this only when you want to completely reset.

Restarting the Database

docker-compose restart postgres

Accessing the Database

Using psql (Interactive Terminal)

docker exec -it bd_scan_face_postgres_1 psql -U postgres -d postgres

Replace bd_scan_face_postgres_1 with your actual container name from docker-compose ps.

Common psql Commands

Command	Description
`\l`	List all databases
`\dt`	List all tables
`\d table_name`	Describe table structure
`\du`	List users
`\q`	Quit psql

Execute Single Query

docker exec -it bd_scan_face_postgres_1 psql -U postgres -d postgres -c "SELECT * FROM users LIMIT 5;"

Using pg_dump (Database Backup)

docker exec bd_scan_face_postgres_1 pg_dump -U postgres postgres > backup.sql

Restore from Backup

docker exec -i bd_scan_face_postgres_1 psql -U postgres -d postgres < backup.sql

Viewing Logs

Real-time Logs

docker-compose logs -f postgres

Press Ctrl+C to stop following logs.

Last N Lines

docker-compose logs --tail=100 postgres

Logs with Timestamps

docker-compose logs -t postgres

Volume Management

List Volumes

docker volume ls

Look for the volume named bd_scan_face_postgres_data or similar.

Inspect Volume

docker volume inspect bd_scan_face_postgres_data

Shows mount point and other volume details.

Backup Volume Data

docker run --rm \
  -v bd_scan_face_postgres_data:/data \
  -v $(pwd):/backup \
  ubuntu tar czf /backup/postgres_backup.tar.gz /data

Restore Volume Data

docker run --rm \
  -v bd_scan_face_postgres_data:/data \
  -v $(pwd):/backup \
  ubuntu tar xzf /backup/postgres_backup.tar.gz -C /

Remove Volume (Delete All Data)

This permanently deletes all database data. Cannot be undone!

# Stop containers first
docker-compose down

# Remove volume
docker volume rm bd_scan_face_postgres_data

Network Management

Inspect Network

docker network inspect bd_scan_face_prisma-network

Shows connected containers and network configuration.

Connect Application Container

If running your application in Docker:

docker-compose.yml

services:
  app:
    # ... your app configuration
    networks:
      - prisma-network
    environment:
      DATABASE_URL: "postgresql://postgres:prisma@postgres:5432/postgres?schema=public"
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    # ... existing postgres configuration

When connecting from within Docker network, use the service name (postgres) as the hostname instead of localhost.

Environment Customization

Custom Database Name

docker-compose.yml

environment:
  - POSTGRES_DB=bd_scan_face
  - POSTGRES_USER=postgres
  - POSTGRES_PASSWORD=prisma

Update your DATABASE_URL:

.env

DATABASE_URL="postgresql://postgres:prisma@localhost:5432/bd_scan_face?schema=public"

Custom Port

docker-compose.yml

ports:
  - "5433:5432"

Update your DATABASE_URL:

.env

DATABASE_URL="postgresql://postgres:prisma@localhost:5433/postgres?schema=public"

Multiple Databases

docker-compose.yml

services:
  postgres_dev:
    image: postgres:15
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_DB=bd_scan_face_dev
    volumes:
      - postgres_dev_data:/var/lib/postgresql/data

  postgres_test:
    image: postgres:15
    ports:
      - "5433:5432"
    environment:
      - POSTGRES_DB=bd_scan_face_test
    volumes:
      - postgres_test_data:/var/lib/postgresql/data

volumes:
  postgres_dev_data:
  postgres_test_data:

Troubleshooting

Container Won’t Start

# View detailed logs
docker-compose logs postgres

# Check if port is in use
lsof -i :5432

# Remove and recreate container
docker-compose down
docker-compose up -d

Health Check Failing

Error: Container shows as unhealthy

# Check health status
docker inspect bd_scan_face_postgres_1 | grep Health -A 10

# View logs for errors
docker-compose logs postgres

# Verify health check command
docker exec bd_scan_face_postgres_1 pg_isready -U postgres -d postgres

Connection Refused

docker-compose ps

Disk Space Issues

# Check Docker disk usage
docker system df

# Clean up unused resources
docker system prune

# Remove old images
docker image prune -a

Permission Denied on Volume

# Fix volume permissions
docker-compose down
sudo chown -R $USER:$USER /var/lib/docker/volumes/bd_scan_face_postgres_data
docker-compose up -d

Performance Tuning

Increase Shared Buffers

docker-compose.yml

command: postgres -c listen_addresses='*' -c shared_buffers=256MB -c max_connections=200

Add Performance Configuration

docker-compose.yml

environment:
  - POSTGRES_INITDB_ARGS=-E UTF8 --lc-collate=C --lc-ctype=C
  - POSTGRES_HOST_AUTH_METHOD=md5
command: |
  postgres
    -c listen_addresses='*'
    -c shared_buffers=256MB
    -c effective_cache_size=1GB
    -c maintenance_work_mem=64MB
    -c checkpoint_completion_target=0.9
    -c wal_buffers=16MB
    -c default_statistics_target=100

Next Steps

Environment Setup

Complete setup guide for the application

Prisma Client

Learn how to use Prisma Client

Database Schema

Explore the database schema

Troubleshooting

Common issues and solutions

Get Started

Database

Guides

​Docker Compose Configuration

​Complete Configuration

​Configuration Breakdown

​Service Configuration

​Base Image

​Restart Policy

​Environment Variables

​Port Mapping

​Health Checks

​Volume Management

​Network Configuration

​PostgreSQL Command

​Logging Configuration

​Managing Containers

​Starting the Database

​Stopping the Database

​Restarting the Database

​Accessing the Database

​Using psql (Interactive Terminal)

​Common psql Commands

​Execute Single Query

​Using pg_dump (Database Backup)

​Restore from Backup

​Viewing Logs

​Real-time Logs

​Last N Lines

​Logs with Timestamps

​Volume Management

​List Volumes

​Inspect Volume

​Backup Volume Data

​Restore Volume Data

​Remove Volume (Delete All Data)

​Network Management

​Inspect Network

​Connect Application Container

​Environment Customization

​Custom Database Name

​Custom Port

​Multiple Databases

​Troubleshooting

​Container Won’t Start

​Health Check Failing

​Connection Refused

​Disk Space Issues

​Permission Denied on Volume

​Performance Tuning

​Increase Shared Buffers

​Add Performance Configuration

​Next Steps

Environment Setup

Prisma Client

Database Schema

Troubleshooting

Build docs developers (and LLMs) love

Docker Compose Configuration

Complete Configuration

Configuration Breakdown

Service Configuration

Base Image

Restart Policy

Environment Variables

Port Mapping

Health Checks

Volume Management

Network Configuration

PostgreSQL Command

Logging Configuration

Managing Containers

Starting the Database

Stopping the Database

Restarting the Database

Accessing the Database

Using psql (Interactive Terminal)

Common psql Commands

Execute Single Query

Using pg_dump (Database Backup)

Restore from Backup

Viewing Logs

Real-time Logs

Last N Lines

Logs with Timestamps

Volume Management

List Volumes

Inspect Volume

Backup Volume Data

Restore Volume Data

Remove Volume (Delete All Data)

Network Management

Inspect Network

Connect Application Container

Environment Customization

Custom Database Name

Custom Port

Multiple Databases

Troubleshooting

Container Won’t Start

Health Check Failing

Connection Refused

Disk Space Issues

Permission Denied on Volume

Performance Tuning

Increase Shared Buffers

Add Performance Configuration

Next Steps