Docker Compose Installation

Complete guide to deploying GoPie with Docker Compose for development and production

This guide provides detailed instructions for deploying GoPie using Docker Compose, suitable for both development and production environments.

Best For: Single-server deployments, development environments, and small to medium-scale production use.

Prerequisites

Before starting, ensure you have:

Docker 20.10+ installed (Install Docker)
Docker Compose 2.0+ installed (Install Docker Compose)
Git for cloning the repository
Minimum 8GB RAM (16GB recommended for production)
20GB free disk space (more for large datasets)

Verify your installation:

docker --version
docker-compose --version

Installation Options

GoPie provides three Docker Compose configurations:

File: docker-compose.yml

Full authentication with Zitadel
Production-ready security settings
Monitoring and logging enabled
Suitable for real deployments

File: docker-compose.dev.yml

Authentication enabled
Hot-reload for development
Debug ports exposed
Volume mounts for code changes

File: docker-compose-noauth.yaml

No authentication required
Fastest setup for testing
All security disabled
Never use in production!

Production Installation

Clone and Configure

Clone the repository and set up your environment:

# Clone the repository
git clone https://github.com/factly/gopie.git
cd gopie

# Copy environment template
cp .env.example .env

# Generate secure keys
openssl rand -hex 32 > jwt_secret.key
openssl rand -hex 16 > encryption_key.key

Configure Environment Variables

Edit the .env file with your production settings:

# Core Configuration
NODE_ENV=production
GOPIE_BASE_URL=https://your-domain.com

# Database Configuration
POSTGRES_HOST=gopie-postgres
POSTGRES_PORT=5432
POSTGRES_DB=gopie
POSTGRES_USER=gopie
POSTGRES_PASSWORD=<secure-password>

# Authentication (Zitadel)
ZITADEL_URL=http://gopie-zitadel:8080
ZITADEL_CLIENT_ID=<your-client-id>
ZITADEL_CLIENT_SECRET=<your-client-secret>

# AI Configuration
OPENAI_API_KEY=<your-openai-key>
# Or use Anthropic
ANTHROPIC_API_KEY=<your-anthropic-key>

# Storage (MinIO)
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=<secure-password>
MINIO_ENDPOINT=gopie-minio:9000
MINIO_ACCESS_KEY=<access-key>
MINIO_SECRET_KEY=<secret-key>

# Security Keys
JWT_SECRET=<contents-of-jwt_secret.key>
ENCRYPTION_KEY=<contents-of-encryption_key.key>

Security Note: Never commit .env files with real credentials. Use environment-specific files and secret management systems in production.

Configure Zitadel Authentication

If using authentication, set up Zitadel:

Create the Zitadel configuration directory:

mkdir -p zitadel

Add your service account key:

# Copy your Zitadel service account JSON key
cp /path/to/your/key.json zitadel/key.json

Update Zitadel environment in .env:

ZITADEL_KEY_PATH=./zitadel/key.json
ZITADEL_DOMAIN=your-zitadel-domain.com

Launch Services

Start all services in production mode:

# Start in detached mode
docker-compose up -d

# Or start with logs visible
docker-compose up

Monitor the startup process:

# View all logs
docker-compose logs -f

# View specific service logs
docker-compose logs -f gopie-server

Verify Installation

Check all services are healthy:

# Check service status
docker-compose ps

# Test API endpoint
curl http://localhost:8000/health

# Test web interface
curl http://localhost:3000

Expected output:

NAME                STATUS    PORTS
gopie-web           running   0.0.0.0:3000->3000/tcp
gopie-server        running   0.0.0.0:8000->8000/tcp
gopie-chat          running   0.0.0.0:8001->8001/tcp
gopie-postgres      running   5432/tcp
gopie-qdrant        running   6333/tcp
gopie-minio         running   9000/tcp

Directory Structure

After installation, your GoPie directory should look like:

docker-compose.yml

docker-compose-noauth.yaml

.env

.env.example

Service Configuration

Core Services

Service	Purpose	Default Port	Configuration
`gopie-web`	Next.js frontend	3000	Environment variables
`gopie-server`	Go backend API	8000	`config.yaml` + env
`gopie-chat`	Python AI service	8001	Environment variables

Data Services

Service	Purpose	Default Port	Persistence
`gopie-postgres`	Metadata storage	5432	`./data/postgres`
`gopie-qdrant`	Vector search	6333	`./data/qdrant`
`gopie-minio`	Object storage	9000	`./data/minio`

Optional Services

Service	Purpose	When to Enable
`gopie-zitadel`	Authentication	Production deployments
`gopie-companion`	Cloud uploads	Google Drive/OneDrive support
`gopie-redis`	Caching	High-traffic deployments

Advanced Configuration

Resource Limits

Configure resource limits in docker-compose.yml:

services:
  gopie-server:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

Custom Networks

For advanced networking setups:

networks:
  gopie-frontend:
    driver: bridge
  gopie-backend:
    driver: bridge
    internal: true

Volume Management

Customize data persistence:

volumes:
  postgres-data:
    driver: local
    driver_opts:
      type: none
      device: /mnt/data/postgres
      o: bind

Health Checks

All services include health checks:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

SSL/TLS Configuration

For HTTPS in production:

Using Nginx Reverse Proxy

Create nginx.conf:

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    location / {
        proxy_pass http://gopie-web:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /api {
        proxy_pass http://gopie-server:8000;
        proxy_set_header Host $host;
    }
}

Using Traefik

Add to docker-compose.yml:

services:
  traefik:
    image: traefik:v2.10
    command:
      - "--providers.docker=true"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.myresolver.acme.tlschallenge=true"
      - "--certificatesresolvers.myresolver.acme.email=your-email@example.com"
    ports:
      - "443:443"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      - "./letsencrypt:/letsencrypt"

  gopie-web:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.gopie.rule=Host(`your-domain.com`)"
      - "traefik.http.routers.gopie.entrypoints=websecure"
      - "traefik.http.routers.gopie.tls.certresolver=myresolver"

Monitoring and Logging

Enable Monitoring Stack

Add monitoring services to your deployment:

services:
  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"

  grafana:
    image: grafana/grafana:latest
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    ports:
      - "3001:3000"

Log Aggregation

Configure centralized logging:

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"
    labels: "service"

Backup and Recovery

Automated Backups

Create a backup script backup.sh:

#!/bin/bash
BACKUP_DIR="/backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p $BACKUP_DIR

# Backup PostgreSQL
docker exec gopie-postgres pg_dump -U gopie gopie > $BACKUP_DIR/postgres.sql

# Backup MinIO data
docker run --rm -v gopie_minio-data:/data -v $BACKUP_DIR:/backup \
  alpine tar czf /backup/minio.tar.gz -C /data .

# Backup Qdrant
docker exec gopie-qdrant qdrant-backup create /qdrant/backup
docker cp gopie-qdrant:/qdrant/backup $BACKUP_DIR/qdrant

echo "Backup completed to $BACKUP_DIR"

Restore Process

# Restore PostgreSQL
docker exec -i gopie-postgres psql -U gopie gopie < /backups/postgres.sql

# Restore MinIO
docker run --rm -v gopie_minio-data:/data -v /backups:/backup \
  alpine tar xzf /backup/minio.tar.gz -C /data

# Restart services
docker-compose restart

Troubleshooting

Common Issues

Container keeps restarting

Check logs for the specific service:

docker-compose logs -f [service-name]

Common causes:

Incorrect environment variables
Port conflicts
Insufficient resources
Missing dependencies

Database connection errors

Verify PostgreSQL is running:

docker-compose exec gopie-postgres pg_isready

Check connection settings:

docker-compose exec gopie-server env | grep POSTGRES

Test direct connection:

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

Performance issues

Check resource usage:

docker stats

Increase Docker resources:
- Docker Desktop: Preferences → Resources
- Linux: Update daemon.json
Enable swap accounting:

echo "GRUB_CMDLINE_LINUX=\"cgroup_enable=memory swapaccount=1\"" >> /etc/default/grub
update-grub

Maintenance

Regular Updates

Keep GoPie updated:

# Pull latest changes
git pull origin main

# Update containers
docker-compose pull
docker-compose up -d

Clean Up

Remove unused resources:

# Remove stopped containers
docker-compose rm -f

# Clean up volumes (WARNING: deletes data)
docker-compose down -v

# Remove unused images
docker image prune -a

Next Steps

Kubernetes Deployment - For larger scale deployments
Local Development Setup - For contributing to GoPie
First Dataset Tutorial - Start using GoPie
Security Best Practices - Harden your installation

Production Ready! Your GoPie installation is now ready for production use. Remember to regularly backup your data and monitor system health.

Docker Compose Installation

On this page