postgres-service/README.md

# PostgreSQL Production Setup for Proxmox LXC Container

This repository contains a production-ready PostgreSQL setup using Docker Compose, designed to run on a Proxmox LXC container.

## Overview

The configuration includes:

- PostgreSQL 15 with optimized configuration
- Persistent data storage
- Security features
- Health checks
- Resource limits
- Backup and restore capabilities

## Prerequisites

- Proxmox VE with LXC container support
- Docker and Docker Compose installed on the LXC container
- Proper network configuration in Proxmox

## Configuration Details

### docker-compose.yml Explained

```yaml
services:
  postgres:
    image: postgres:15 # Using PostgreSQL 15
    container_name: postgres
    restart: always # Ensures PostgreSQL restarts automatically
    environment:
      # Environment variables for authentication
      - POSTGRES_USER=${POSTGRES_USER:-postgres} # Default: postgres
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-password} # Default: password
      - POSTGRES_DB=${POSTGRES_DB:-postgres} # Default: postgres
      - PGDATA=/var/lib/postgresql/data/pgdata
    volumes:
      # Persistent data storage
      - postgres_data:/var/lib/postgresql/data # Database files
      - ./config/postgres.conf:/etc/postgresql/postgresql.conf # Configuration file
      - ./init:/docker-entrypoint-initdb.d # Initialization scripts
    ports:
      - "5432:5432" # Expose PostgreSQL port
    command: postgres -c config_file=/etc/postgresql/postgresql.conf
    healthcheck:
      # Regular health checks
      test:
        [
          "CMD-SHELL",
          "pg_isready -U ${POSTGRES_USER:-postgres} -d ${POSTGRES_DB:-postgres}",
        ]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    networks:
      - postgres_network
    ulimits:
      # Increase file descriptor limits for production
      nofile:
        soft: 64000
        hard: 64000
    logging:
      # Log rotation to prevent disk space issues
      driver: "json-file"
      options:
        max-size: "200m"
        max-file: "10"

volumes:
  postgres_data: # Persistent volume for database files
    driver: local

networks:
  postgres_network:
    driver: bridge
```

## Security Considerations

1. **Authentication**: PostgreSQL is configured with authentication enabled by default
2. **Environment Variables**: Sensitive information is passed via environment variables
3. **Network Isolation**: Services run on a dedicated bridge network
4. **Configuration**: Optimized PostgreSQL configuration for security and performance

## Initialization Script

The initialization scripts in the `init/` directory:

- Create default roles and permissions
- Set up sample schemas and tables
- Configure database parameters for optimal performance

## Setup and Usage

### Initial LXC Container Setup

For detailed instructions on setting up an LXC container in Proxmox specifically for this PostgreSQL service, please refer to the [Proxmox LXC Setup Guide](proxmox-lxc-setup.md).

The guide includes:
- Creating an LXC container with the right specifications
- Configuring the container for Docker
- Setting up networking
- Installing Docker and Docker Compose
- Troubleshooting common issues

### Deploy PostgreSQL Service

1. Clone this repository to your LXC container:

```bash
git clone <repository-url>
cd postgres-service
```

2. Create a `.env` file with your custom credentials:

```
POSTGRES_USER=your_postgres_username
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=your_database_name
```

3. Make the scripts executable:

```bash
chmod +x scripts/*.sh
```

4. Start the PostgreSQL service:

```bash
docker-compose up -d
```

5. Verify the service is running:

```bash
docker-compose ps
```

6. Connect to PostgreSQL:

```
psql -h your-server-ip -p 5432 -U your_postgres_username -d your_database_name
```

## Backup and Restore

### Creating a Backup

```bash
./scripts/backup.sh
```

### Restoring from Backup

```bash
./scripts/restore.sh <backup-file>
```

## Proxmox LXC Container Configuration

For optimal performance in a Proxmox LXC container:

1. Ensure the container has sufficient resources:

   - At least 2 CPU cores
   - Minimum 4GB RAM
   - At least 20GB storage

2. Enable necessary features in the LXC container:

   ```
   pct set <container-id> -features nesting=1
   ```

3. Configure container for Docker:
   ```
   echo 'kernel.unprivileged_userns_clone=1' > /etc/sysctl.d/unprivileged-userns-clone.conf
   sysctl -p /etc/sysctl.d/unprivileged-userns-clone.conf
   ```

## Maintenance

- **Backups**: PostgreSQL data is stored in named volumes. Use Docker's volume backup mechanisms:

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

- **Monitoring**: The service is configured with health checks and can be integrated with monitoring tools like Prometheus and Grafana

- **Updating**: To update PostgreSQL version, change the image tag in docker-compose.yml and restart:
  ```bash
  docker-compose down
  # Edit docker-compose.yml to update image version
  docker-compose up -d
  ```

## Troubleshooting

- **Connection Issues**: Ensure ports are not blocked by firewall
- **Performance Issues**: Check PostgreSQL logs with `docker-compose logs postgres`
- **Resource Problems**: Monitor container resource usage and adjust limits if needed

## License

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