Installation Guide

Prerequisites

Before installing GeoFlow, ensure your system meets these requirements:

System Requirements

Operating System: Linux (Ubuntu 20.04+, CentOS 8+, or similar)
CPU: 4+ cores recommended (8+ cores for production)
RAM: 8GB minimum (16GB+ recommended for production)
Storage: 50GB+ available disk space
Network: Stable internet connection for downloads

Software Dependencies

Docker: Version 24.0+ with Docker Compose V2
Git: Version 2.25+
curl/wget: For downloading files
openssl: For SSL certificate generation (optional)

Network Requirements

Inbound Ports: 80/443 (HTTP/HTTPS), 22 (SSH)
Outbound: Access to Docker Hub, GitHub, package registries
Internal: Services communicate on internal Docker network

Quick Start (Development)

For development and testing, use the Docker Compose setup:

# Clone repository
git clone https://github.com/qs-geoflow/geoflow.git
cd geoflow

# Start all services
docker compose up -d

# Check service status
docker compose ps

# View logs
docker compose logs -f

Production Installation

1. Server Preparation

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install required packages
sudo apt install -y curl wget git openssl

# Install Docker
curl -fsSL https://get.docker.com | sh
sudo systemctl enable docker
sudo systemctl start docker

# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

# Add user to docker group (optional)
sudo usermod -aG docker $USER

2. Clone and Configure

# Clone repository
git clone https://github.com/qs-geoflow/geoflow.git
cd geoflow

# Create environment file
cp .env.example .env

3. Environment Configuration

Edit .env file with your production settings:

# Database
POSTGRES_PASSWORD=your-secure-db-password
INSTANCE_SECRET=your-convex-instance-secret

# External URLs
GEOFLOW_DOMAIN=your-domain.com
[email protected]

# Storage
GEOFLOW_HOST_DATA_PATH=/opt/geoflow/data
GEOFLOW_HOST_TEMP_PATH=/opt/geoflow/temp

# Security
JWT_SECRET=your-jwt-secret-key
ENCRYPTION_KEY=your-encryption-key

# Email (optional)
SMTP_HOST=smtp.gmail.com
[email protected]
SMTP_PASS=your-app-password

4. SSL Certificate Setup (Optional)

For HTTPS support, obtain SSL certificates:

# Using Let's Encrypt (Certbot)
sudo apt install -y certbot
sudo certbot certonly --standalone -d your-domain.com

# Or using self-signed certificates
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

5. Storage Setup

# Create data directories
sudo mkdir -p /opt/geoflow/data
sudo mkdir -p /opt/geoflow/temp
sudo mkdir -p /opt/geoflow/ssl

# Set permissions
sudo chown -R 1000:1000 /opt/geoflow/data
sudo chown -R 1000:1000 /opt/geoflow/temp

# Copy SSL certificates (if using custom)
sudo cp cert.pem /opt/geoflow/ssl/
sudo cp key.pem /opt/geoflow/ssl/

6. Docker Compose Configuration

Update docker-compose.yml for production:

version: '3.8'

services:
  # ... existing services ...

  # Add reverse proxy for production
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - /opt/geoflow/ssl:/etc/ssl/certs:ro
    depends_on:
      - geoflow-app
      - geoflow-convex-backend
    restart: unless-stopped

  # Add monitoring (optional)
  prometheus:
    image: prom/prometheus
    volumes:
      - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml:ro
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
    restart: unless-stopped

7. Nginx Configuration

Create nginx.conf for reverse proxy:

events {
    worker_connections 1024;
}

http {
    upstream geoflow_app {
        server geoflow-app:3000;
    }

    upstream convex_backend {
        server geoflow-convex-backend:3210;
    }

    server {
        listen 80;
        server_name your-domain.com;

        # Redirect to HTTPS
        return 301 https://$server_name$request_uri;
    }

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

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

        # Security headers
        add_header X-Frame-Options DENY;
        add_header X-Content-Type-Options nosniff;
        add_header X-XSS-Protection "1; mode=block";

        # GeoFlow App
        location / {
            proxy_pass http://geoflow_app;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        # Convex API
        location /api/ {
            proxy_pass http://convex_backend;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        # Convex Dashboard
        location /dashboard/ {
            proxy_pass http://geoflow-convex-dashboard:6791;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
        }
    }
}

8. Start Services

# Start all services
docker compose up -d

# Wait for services to be healthy
docker compose ps

# Check logs for any issues
docker compose logs

9. Database Initialization

# Run database migrations
docker compose exec geoflow-convex-backend convex deploy

10. Verification

# Check service health
curl -f https://your-domain.com/health

# Test application access
curl -f https://your-domain.com

# Verify database connection
docker compose exec postgres pg_isready -U geoflow -d geoflow

Cloud Deployment

AWS EC2

# Launch EC2 instance
aws ec2 run-instances \
  --image-id ami-0abcdef1234567890 \
  --instance-type t3.large \
  --key-name your-key-pair \
  --security-groups geoflow-sg

# Configure security group to allow ports 80, 443, 22

# Use same installation steps as above

DigitalOcean Droplet

# Create droplet with Docker marketplace image
# Use same installation steps as above

Google Cloud Platform

# Create VM instance
gcloud compute instances create geoflow \
  --machine-type e2-standard-4 \
  --image-family ubuntu-2004-lts \
  --image-project ubuntu-os-cloud

# Use same installation steps as above

High Availability Setup

Load Balancing

# docker-compose.prod.yml
version: '3.8'

services:
  # Multiple app instances
  geoflow-app-1:
    # ... app config ...
    deploy:
      replicas: 2

  geoflow-app-2:
    # ... app config ...
    deploy:
      replicas: 2

  # Load balancer
  nginx-lb:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx-lb.conf:/etc/nginx/nginx.conf:ro

Database Replication

# PostgreSQL primary
postgres-primary:
  # ... primary config ...

# PostgreSQL replica
postgres-replica:
  image: postgis/postgis:15-3.3
  environment:
    POSTGRES_MASTER_HOST: postgres-primary
    POSTGRES_MASTER_PORT: 5432
  depends_on:
    - postgres-primary

Backup Strategy

Automated Backups

# Create backup script
cat > /opt/geoflow/backup.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/opt/geoflow/backups"
DATE=$(date +%Y%m%d_%H%M%S)

# Database backup
docker compose exec -T postgres pg_dump -U geoflow geoflow > $BACKUP_DIR/db_$DATE.sql

# Data directory backup
tar -czf $BACKUP_DIR/data_$DATE.tar.gz /opt/geoflow/data

# Clean old backups (keep last 7 days)
find $BACKUP_DIR -name "*.sql" -mtime +7 -delete
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete
EOF

chmod +x /opt/geoflow/backup.sh

# Add to cron for daily backups
echo "0 2 * * * /opt/geoflow/backup.sh" | crontab -

Backup Verification

# Test backup restoration
docker compose exec postgres createdb -U geoflow geoflow_test
docker compose exec -T postgres psql -U geoflow geoflow_test < backup.sql

Monitoring Setup

Prometheus & Grafana

# docker-compose.monitoring.yml
version: '3.8'

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

  grafana:
    image: grafana/grafana
    environment:
      GF_SECURITY_ADMIN_PASSWORD: admin
    volumes:
      - grafana_data:/var/lib/grafana
    ports:
      - "3001:3000"

Log Aggregation

# Install Loki for log aggregation
docker run -d \
  --name loki \
  -p 3100:3100 \
  grafana/loki:latest

# Configure Promtail for log shipping
# ... promtail configuration ...

Security Hardening

Firewall Configuration

# UFW setup
sudo ufw enable
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw --force reload

SSL/TLS Configuration

# Strong SSL configuration
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512:ECDHE-RSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;

Container Security

# Security options in docker-compose
services:
  geoflow-app:
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp
    user: "1000:1000"

Troubleshooting

Service Startup Issues

# Check service status
docker compose ps

# View detailed logs
docker compose logs --tail=100 service-name

# Restart specific service
docker compose restart service-name

# Rebuild and restart
docker compose up --build -d service-name

Performance Issues

# Monitor resource usage
docker stats

# Check disk space
df -h

# Monitor network connections
netstat -tlnp

# Database performance
docker compose exec postgres pg_stat_activity

Common Problems

Port conflicts: Change host ports in docker-compose.yml Memory issues: Increase Docker memory limits or add swap space Database connection failures: Check POSTGRES_PASSWORD and network connectivity SSL certificate errors: Verify certificate paths and permissions

Updates and Maintenance

Rolling Updates

# Update images
docker compose pull

# Rolling restart
docker compose up -d --no-deps service-name

# Zero-downtime updates
docker compose up -d --scale service-name=2 --no-deps service-name
docker compose up -d --scale service-name=1 --no-deps service-name

Maintenance Windows

# Scheduled maintenance script
#!/bin/bash
echo "Starting maintenance..."

# Enable maintenance mode
docker compose exec geoflow-app touch /app/maintenance

# Perform maintenance tasks
docker compose exec postgres vacuumdb -U geoflow -d geoflow --analyze

# Disable maintenance mode
docker compose exec geoflow-app rm /app/maintenance

echo "Maintenance completed"

Support

For installation issues:

Check the troubleshooting section
Review service logs: docker compose logs
Verify configuration files
Check system resources: docker system df
Contact support with detailed error logs

Get Started

Architecture

Development

​Prerequisites

​System Requirements

​Software Dependencies

​Network Requirements

​Quick Start (Development)

​Production Installation

​1. Server Preparation

​2. Clone and Configure

​3. Environment Configuration

​4. SSL Certificate Setup (Optional)

​5. Storage Setup

​6. Docker Compose Configuration

​7. Nginx Configuration

​8. Start Services

​9. Database Initialization

​10. Verification

​Cloud Deployment

​AWS EC2

​DigitalOcean Droplet

​Google Cloud Platform

​High Availability Setup

​Load Balancing

​Database Replication

​Backup Strategy

​Automated Backups

​Backup Verification

​Monitoring Setup

​Prometheus & Grafana

​Log Aggregation

​Security Hardening

​Firewall Configuration

​SSL/TLS Configuration

​Container Security

​Troubleshooting

​Service Startup Issues

​Performance Issues

​Common Problems

​Updates and Maintenance

​Rolling Updates

​Maintenance Windows

​Support