Installation & Deployment

Installation & Deployment

This guide covers the complete installation and deployment process for Querri in production environments.

System Requirements

Minimum Hardware Requirements

• CPU: 4 cores (8+ cores recommended for production)
• RAM: 16GB minimum (32GB+ recommended for production)
• Storage: 100GB minimum (SSD recommended)
• Network: 1Gbps network interface

Software Requirements

• Docker: 20.10 or later
• Docker Compose: 2.0 or later
• Operating System: Linux (Ubuntu 20.04+ or RHEL 8+), macOS (for development)
• SSL/TLS: Valid SSL certificate for HTTPS (production)

Network Ports

The following ports must be available:

Port	Service	Description
8080	Traefik (HTTP)	Main application entry point
8888	Traefik (Internal)	Internal service communication
27017	MongoDB	Database (can be restricted to localhost)
6379	Redis	Cache and queue (can be restricted to localhost)
8181	OPA	Policy engine (internal)
8180	Healthz	Health check service

Service Architecture

Querri consists of the following microservices:

Core Services

reverse-proxy (Traefik)

• Routes traffic to appropriate services
• Handles JWT authentication
• Provides SSL/TLS termination
• Ports: 8080 (HTTP), 8888 (internal)

web-app (SvelteKit)

• Frontend application
• Server-side rendering
• Communicates with server-api via Traefik

server-api (FastAPI)

• Python backend API
• Business logic and data processing
• Scalable with replicas (default: 4-6 replicas)
• Volume mounts: /app (application code), /app/files (file storage)

hub (Python)

• Authentication service
• Organization management
• WorkOS integration for SSO
• Health check endpoint: /hub/healthz

researcher

• Data scraping and research operations
• Background processing
• Single replica deployment

healthz

• System health monitoring
• External health check endpoint
• Port: 8180

Infrastructure Services

mongo (MongoDB)

• Primary database
• Persistent volume: mongodb_data
• Authentication required

redis

• Caching layer
• Background task queue
• No persistence configured by default

opa (Open Policy Agent)

• Policy-based authorization
• Loads policies from /policies/authz.rego and /policies/adminz.rego

Installation Steps

1. Install Docker and Docker Compose

Ubuntu/Debian:

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# 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

# Enable Docker service
sudo systemctl enable docker
sudo systemctl start docker

RHEL/CentOS:

# Install Docker
sudo yum install -y 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

# Enable Docker service
sudo systemctl enable docker
sudo systemctl start docker

2. Clone Querri Repository

# Clone the repository
git clone https://github.com/querri/querri-stack.git
cd querri-stack/Querri

3. Configure Environment

Create .env-prod file with required configuration (see Environment Configuration for details):

# Copy example environment file
cp .env.example .env-prod

# Edit configuration
nano .env-prod

Minimum required variables:

• MongoDB credentials (MONGO_INITDB_ROOT_USERNAME, MONGO_INITDB_ROOT_PASSWORD)
• WorkOS credentials (WORKOS_API_KEY, WORKOS_CLIENT_ID)
• OpenAI or Azure OpenAI credentials
• JWT private key
• Redis configuration

4. Configure Traefik

Create or verify the Traefik configuration directory:

# Ensure traefik directory exists
mkdir -p traefik

# Verify traefik configuration files
ls traefik/

5. Pull Docker Images

# Pull all required images
docker compose pull

The following images will be pulled:

• daveatquerri/querri-web-app:latest
• daveatquerri/querri-server-api:latest
• daveatquerri/querri-hub:latest
• daveatquerri/querri-researcher:latest
• daveatquerri/querri-healthz:latest
• traefik:v2.11
• mongo:latest
• redis:latest
• openpolicyagent/opa:0.70.0

6. Initialize MongoDB Volumes

# Create MongoDB data volume
docker volume create mongodb_data

7. Start Services

# Start all services
docker compose up -d

# Verify services are running
docker compose ps

Expected output:

NAME                STATUS              PORTS
reverse-proxy       Up                  0.0.0.0:8080->80/tcp, 0.0.0.0:8888->8888/tcp
web-app             Up
server-api          Up (replicas: 4)
hub                 Up (healthy)
researcher          Up
healthz             Up                  0.0.0.0:8180->8000/tcp
mongo               Up                  0.0.0.0:27017->27017/tcp
redis               Up                  0.0.0.0:6379->6379/tcp
opa                 Up                  0.0.0.0:8181->8181/tcp

8. Verify Health Checks

# Check hub service health
curl http://localhost:8888/hub/healthz

# Check external health endpoint
curl http://localhost:8180/healthz

# Check main application
curl http://localhost:8080/

9. Configure DNS (Production)

Point your domain to the server IP address:

A Record: app.yourcompany.com -> YOUR_SERVER_IP

10. Configure SSL/TLS (Production)

Update Traefik configuration to enable HTTPS:

traefik/traefik.yml:

entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  websecure:
    address: ":443"

certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@yourcompany.com
      storage: /letsencrypt/acme.json
      httpChallenge:
        entryPoint: web

Service Scaling

Scaling server-api Replicas

Adjust the number of API replicas in .env-prod:

SERVER_API_REPLICAS=6

Then restart services:

docker compose up -d --scale server-api=6

Resource Limits

Add resource constraints to docker-compose.yml:

server-api:
  deploy:
    replicas: ${SERVER_API_REPLICAS:-4}
    resources:
      limits:
        cpus: '2.0'
        memory: 4G
      reservations:
        cpus: '0.5'
        memory: 1G

Health Checks

Service Health Status

All services include health checks:

# View service health
docker compose ps

# Check specific service logs
docker compose logs hub
docker compose logs server-api
docker compose logs web-app

Hub Service Health Check

The hub service includes a comprehensive health check:

healthcheck:
  test: ["CMD", "python", "-c", "import urllib.request, os; urllib.request.urlopen('http://localhost:8000/hub/healthz').close()"]
  interval: 15s
  timeout: 3s
  retries: 10
  start_period: 15s

External Monitoring

The healthz service (port 8180) provides an external health check endpoint for monitoring systems:

# Health check endpoint
curl http://localhost:8180/healthz

Troubleshooting Installation

Services Failing to Start

# Check service logs
docker compose logs <service-name>

# Restart specific service
docker compose restart <service-name>

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

Port Conflicts

If ports are already in use, modify port mappings in docker-compose.yml:

ports:
  - "8081:80"  # Changed from 8080 to 8081

Permission Issues

# Fix Docker socket permissions
sudo chmod 666 /var/run/docker.sock

# Or add user to docker group
sudo usermod -aG docker $USER
newgrp docker

Database Connection Issues

# Check MongoDB is running
docker compose ps mongo

# Test MongoDB connection
docker compose exec mongo mongosh -u querri -p

# View MongoDB logs
docker compose logs mongo

Post-Installation

After successful installation:

1. Create Admin User: Set up initial admin account via WorkOS or set is_admin flag
2. Configure Organization: Set up organization settings at /settings
3. Configure Integrations: Set up marketplace integrations (admin only)
4. Invite Users: Invite team members via /settings/people
5. Configure Backups: Set up automated backup procedures (see Backup & Maintenance)
6. Set Up Monitoring: Configure monitoring and alerting (see Monitoring & Usage)

Updating Querri

To update to the latest version:

# Pull latest images
docker compose pull

# Restart services with new images
docker compose up -d

# Verify update
docker compose ps
curl http://localhost:8180/healthz

See Backup & Maintenance for detailed update procedures and rollback strategies.

Next Steps

• Environment Configuration - Configure environment variables
• Security & Permissions - Set up authentication and authorization
• User Management - Add and manage users