Installation & Setup

Installation & Setup

This guide is for IT administrators and technical teams responsible for deploying Querri in your organization. It covers installation, configuration, and initial setup.

Prerequisites

Before installing Querri, ensure you have:

• Docker and Docker Compose installed on your host system
• Access to required external services:
  • OpenAI API (for AI capabilities)
  • WorkOS (for authentication and SSO)
  • MongoDB (database)
  • Fine-Grained Authorization (FGA) service (for permissions)
• Sufficient system resources (CPU, memory, storage)
• Network access for users who will access Querri

Architecture Overview

Querri is deployed as a multi-service application using Docker Compose:

Core Services

Frontend (SvelteKit):

• User interface and client-side application
• Serves the chat interface, dashboards, and all UI components
• Communicates with the backend API

Backend (FastAPI):

• REST API for all data operations
• Handles AI agent orchestration
• Manages data connectors and step execution
• Processes authentication and authorization

Supporting Services:

• MongoDB: Primary database for projects, steps, and metadata
• FGA Service: Fine-grained authorization engine for permissions
• Worker Processes: Background job processing for long-running analyses

Installation Steps

1. Clone or Download Querri

Obtain the Querri deployment package and navigate to the deployment directory:

cd /path/to/querri-stack

2. Configure Environment Variables

Create a .env file in the deployment directory with the required configuration:

# Authentication (WorkOS)
WORKOS_API_KEY=your_workos_api_key
WORKOS_CLIENT_ID=your_workos_client_id
WORKOS_REDIRECT_URI=https://your-domain.com/auth/callback

# AI Services
OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL=gpt-4  # or your preferred model

# Database
MONGODB_URI=mongodb://mongodb:27017/querri
MONGODB_DATABASE=querri

# Authorization (FGA)
FGA_STORE_ID=your_fga_store_id
FGA_API_URL=https://api.fga.dev
FGA_API_TOKEN=your_fga_api_token

# Application
APP_ENV=production
APP_SECRET_KEY=your_secure_random_secret_key
ALLOWED_ORIGINS=https://your-domain.com

# Frontend
PUBLIC_API_URL=https://your-domain.com/api

# Optional: Email/Notifications
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your_smtp_user
SMTP_PASSWORD=your_smtp_password

3. Review Docker Compose Configuration

Examine the docker-compose.yml file to understand the service architecture:

services:
  frontend:
    # SvelteKit application
    # Exposed on port 3000

  backend:
    # FastAPI application
    # Exposed on port 8000

  mongodb:
    # Database service
    # Data persisted in volumes

  fga:
    # Authorization service
    # Fine-grained access control

Customize resource limits, port mappings, or volume mounts as needed for your infrastructure.

4. Deploy with Docker Compose

Start all services:

docker-compose up -d

This will:

• Pull required Docker images
• Create and start all containers
• Initialize networks and volumes
• Begin health checks

Monitor the deployment:

docker-compose logs -f

Wait for all services to report healthy status.

5. Initialize the Database

The backend service will automatically run database migrations on first startup. Verify successful migration:

docker-compose exec backend python -m alembic current

6. Configure Fine-Grained Authorization

Initialize the FGA authorization model:

docker-compose exec backend python scripts/init_fga.py

This creates the permission model for:

• Project access control
• Resource sharing
• User roles and capabilities

7. Verify Service Health

Check that all services are running correctly:

# Check service status
docker-compose ps

# Verify backend API health
curl http://localhost:8000/health

# Verify frontend is serving
curl http://localhost:3000/

All services should return healthy status codes.

Initial Admin Account Setup

Create the First Admin User

1. Access the Querri application in your browser: https://your-domain.com
2. Log in using WorkOS authentication
3. The first user to log in will automatically be granted admin privileges

Alternatively, manually promote a user to admin:

docker-compose exec backend python scripts/promote_admin.py user@example.com

Configure Organization Settings

As an admin, configure organization-wide settings:

1. Navigate to Settings > Organization
2. Set:
   • Organization name and branding
   • Default permissions for new users
   • Data retention policies
   • Feature flags (dashboards, automations, etc.)

Post-Installation Configuration

Set Up Data Connectors

Configure available data connectors for your users:

1. Go to Settings > Data Connectors
2. Enable and configure connectors:
   • Database connectors (PostgreSQL, MySQL, etc.)
   • Cloud storage (S3, Google Cloud Storage)
   • API integrations
   • File upload settings

Configure User Authentication

Set up SSO and user provisioning:

1. In WorkOS dashboard, configure:

   • SAML/OIDC providers
   • User directory sync
   • Just-in-time provisioning

2. Test authentication flows with test users

Set Up Monitoring and Logging

Configure monitoring for production:

# View aggregated logs
docker-compose logs

# Export logs to external system
# Configure in docker-compose.yml logging drivers

Consider integrating with:

• Application performance monitoring (APM) tools
• Log aggregation services
• Uptime monitoring
• Error tracking (Sentry, etc.)

Backup and Recovery

Database Backups

Set up automated MongoDB backups:

# Manual backup
docker-compose exec mongodb mongodump --out=/backup

# Restore from backup
docker-compose exec mongodb mongorestore /backup

Configure automated backups with your backup solution or cron jobs.

Configuration Backups

Regularly backup:

• .env file (store securely)
• docker-compose.yml and any customizations
• FGA authorization model
• SSL certificates and keys

Scaling and Performance

Horizontal Scaling

To handle increased load:

1. Scale Backend Workers:

   docker-compose up -d --scale backend=3

2. Add Load Balancer: Configure a reverse proxy (nginx, Traefik) to distribute traffic

3. Database Replication: Set up MongoDB replica sets for high availability

Performance Tuning

• Monitor resource usage: docker stats
• Adjust worker processes based on CPU cores
• Configure caching layers (Redis) if needed
• Optimize database indexes for common queries

Security Considerations

Network Security

• Use HTTPS/TLS for all external connections
• Configure firewall rules to restrict service access
• Use private networks for inter-service communication
• Implement rate limiting on API endpoints

Secrets Management

• Never commit .env files to version control
• Use secrets management tools (Vault, AWS Secrets Manager)
• Rotate API keys and credentials regularly
• Use environment-specific configurations

Access Control

• Enable FGA for all resources
• Review and audit permissions regularly
• Implement least-privilege access
• Monitor authentication logs for anomalies

Troubleshooting

Common Issues

Services Won’t Start:

• Check Docker logs: docker-compose logs [service]
• Verify environment variables are set correctly
• Ensure ports aren’t already in use

Database Connection Errors:

• Verify MongoDB is running: docker-compose ps mongodb
• Check connection string in .env
• Ensure network connectivity between services

Authentication Failures:

• Verify WorkOS configuration
• Check redirect URIs match exactly
• Review WorkOS dashboard for error logs

FGA Permission Errors:

• Reinitialize FGA model: python scripts/init_fga.py
• Verify FGA service is reachable
• Check FGA store ID and credentials

Getting Help

For deployment issues:

• Review Docker Compose logs
• Check service health endpoints
• Consult the full documentation
• Contact Querri support with log files and configuration details

Next Steps

After successful installation:

• Share the Querri URL with your users
• Provide access to the Quick Start Guide
• Set up user training sessions
• Monitor usage and performance
• Plan for regular maintenance and updates

Your Querri instance is now ready for use! Users can begin analyzing data immediately.