Skip to content

Full Installation Guide ​

This guide covers all installation options including Docker, production deployment, and advanced configuration.

Installation Options ​

MethodBest ForTime
Quick StartDevelopment, testing5 min
Docker ComposeLocal production-like10 min
Production DockerOn-premise with HTTPS15 min
Manual SetupCustom environments20 min
AWS ECSEnterprise cloud30 min

Docker Compose ​

The fastest way to run GhostAI with all services.

Prerequisites ​

  • Docker 20.10+
  • Docker Compose 2.0+

Setup ​

bash
# Clone repository
git clone https://github.com/ghostai/ghostai.git
cd ghostai/securechat

# Create environment file
cp .env.example .env
# Edit .env with your API keys

# Start all services
docker compose up -d

Services Started ​

ServicePortDescription
Backend8000FastAPI application
Frontend80React application

Verify Installation ​

bash
# Check services are running
docker compose ps

# Check backend health
curl http://localhost:8000/health

# View logs
docker compose logs -f backend

Stop Services ​

bash
docker compose down

# To remove volumes (data)
docker compose down -v

Manual Setup ​

For development or custom environments.

Backend Setup ​

bash
cd securechat/backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Download NLP models
python -m spacy download en_core_web_sm

# Configure environment
cp .env.example .env
# Edit .env with your settings

Environment Variables ​

Provider API keys in the environment are automatically registered as platform defaults in the database on first startup. This makes them visible in the Platform Admin > Provider Keys UI, where they can be locked, disabled, or replaced.

bash
# LLM Providers (at least one required)
# Each configured key enables a direct route to that provider
OPENAI_API_KEY=sk-...           # OpenAI (GPT-4o, GPT-4o-mini)
OPENROUTER_API_KEY=sk-or-...    # OpenRouter (Claude, Gemini, Llama, etc.)
ANTHROPIC_API_KEY=sk-ant-...    # Anthropic (Claude)
GEMINI_API_KEY=...              # Google Gemini
MISTRAL_API_KEY=...             # Mistral AI
XAI_API_KEY=...                 # xAI (Grok)
DEEPSEEK_API_KEY=...            # DeepSeek
GROQ_API_KEY=...                # Groq
TOGETHER_API_KEY=...            # Together AI
PERPLEXITY_API_KEY=...          # Perplexity
COHERE_API_KEY=...              # Cohere
OLLAMA_BASE_URL=http://localhost:11434   # Ollama (local)
VLLM_BASE_URL=http://localhost:8000/v1   # vLLM (local GPU server)

# Search Providers (enables web search tool)
TAVILY_API_KEY=tvly-...              # Tavily search API key
BRAVE_API_KEY=BSA...                 # Brave search API key
SERPER_API_KEY=...                   # Serper search API key

# Authentication
AUTH_DISABLED=false              # Set true for development
JWT_SECRET_KEY=  # Generate with: openssl rand -hex 32

# Database (PostgreSQL — started automatically by restart.sh or docker compose)
DATABASE_URL=postgresql://ghostai:ghostai_dev_password@localhost:5432/ghostai

# Detection Settings
PII_SCORE_THRESHOLD=0.5
CODE_PROTECTION_POLICY=warn

# Email (optional)
RESEND_API_KEY=re_...
EMAIL_FROM_ADDRESS=noreply@yourdomain.com

# Billing (optional)
STRIPE_SECRET_KEY=sk_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Frontend URL
FRONTEND_URL=https://localhost:5173
CORS_ORIGINS=https://localhost:5173,https://app.ghostai.com

SaaS Connector Configuration (Optional) ​

To enable SaaS integrations for connecting third-party tools (Rippling, Merge HRIS):

bash
# Enable the SaaS connector framework
SAAS_CONNECTORS_ENABLED=true

# Rippling HRIS (get credentials from Rippling Developer Portal)
RIPPLING_CLIENT_ID=your-rippling-client-id
RIPPLING_CLIENT_SECRET=your-rippling-client-secret

# Merge.dev unified HRIS (Enterprise tier — get key from merge.dev)
MERGE_API_KEY=your-merge-api-key

# Sync configuration
CONNECTOR_SYNC_INTERVAL_MINUTES=60
CONNECTOR_HEALTH_CHECK_INTERVAL_MINUTES=15

# Webhook callback URL (must be publicly reachable for real-time sync)
CONNECTOR_WEBHOOK_BASE_URL=https://your-domain.com

See SaaS Integrations for setup instructions.

Start Backend ​

bash
# Development
uvicorn app.main:app --reload --port 8000

# Production
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Frontend Setup ​

bash
cd securechat/frontend

# Install dependencies
npm install

# Development
npm run dev

# Production build
npm run build
npm run preview

AWS Deployment ​

Deploy to AWS ECS with production configuration.

Prerequisites ​

  • AWS CLI configured
  • ECR repository
  • ECS cluster
  • RDS PostgreSQL (optional)
  • Secrets Manager secrets

Build and Push Docker Image ​

bash
# Login to ECR
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  $AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com

# Build
docker build -t ghostai:latest -f securechat/Dockerfile securechat/

# Tag and push
docker tag ghostai:latest $AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/ghostai:latest
docker push $AWS_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/ghostai:latest

Create Secrets ​

bash
aws secretsmanager create-secret \
  --name ghostai/openai-api-key \
  --secret-string "sk-..."

aws secretsmanager create-secret \
  --name ghostai/jwt-secret \
  --secret-string "$(openssl rand -hex 32)"

Deploy ECS Task ​

See securechat/deploy/ecs-task-definition.json for the complete task definition.

bash
# Register task definition
aws ecs register-task-definition \
  --cli-input-json file://deploy/ecs-task-definition.json

# Create service
aws ecs create-service \
  --cluster ghostai-cluster \
  --service-name ghostai-production \
  --task-definition ghostai-production \
  --desired-count 2 \
  --launch-type FARGATE

Production Docker Deployment (Let's Encrypt) ​

For production deployments with automatic HTTPS via Let's Encrypt.

Prerequisites ​

  • Domain with DNS A record pointing to your server
  • Ports 80 and 443 open on firewall

Quick Start ​

bash
cd infrastructure/docker

# Create .env file
cat > .env << 'EOF'
DOMAIN=ghostai.yourdomain.com
ACME_EMAIL=admin@yourdomain.com
DB_PASSWORD=$(openssl rand -base64 24)
JWT_SECRET=$(openssl rand -base64 32)
SESSION_SECRET=$(openssl rand -base64 32)
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
EOF

# Deploy
docker-compose -f docker-compose.production.yml up -d

# Verify
curl https://ghostai.yourdomain.com/health

What's Included ​

ServiceDescription
CaddyAutomatic Let's Encrypt HTTPS
PostgreSQLProduction database
RedisSession cache
BackendFastAPI application
FrontendReact app (Nginx)

SSL Options ​

TypeConfigurationUse Case
Let's EncryptSet DOMAIN env varPublic domains
Self-signedUse tls internal in CaddyfilePrivate networks
NoneRemove CaddyBehind load balancer

SSL/TLS Configuration ​

Development (Self-Signed) ​

The frontend development server uses self-signed certificates. Accept the browser warning on first visit.

Caddy automatically obtains and renews Let's Encrypt certificates:

# Caddyfile
ghostai.yourdomain.com {
    handle /api/* {
        reverse_proxy backend:8000
    }
    handle /v1/* {
        reverse_proxy backend:8000
    }
    # WebSocket — Caddy natively supports WS passthrough
    handle /ws/* {
        reverse_proxy backend:8000
    }
    handle {
        reverse_proxy frontend:8080
    }
    tls {
        protocols tls1.2 tls1.3
    }
}

Production with Nginx ​

Use nginx with manual certificate management:

nginx
server {
    listen 443 ssl http2;
    server_name app.ghostai.com;
    
    ssl_certificate /etc/ssl/certs/ghostai.crt;
    ssl_certificate_key /etc/ssl/private/ghostai.key;
    
    location / {
        proxy_pass http://localhost:80;
    }
    
    location /api/ {
        proxy_pass http://localhost:8000;
    }

    # WebSocket support for /ws/chat
    location /ws/ {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

Database Options ​

PostgreSQL (Default) ​

PostgreSQL is used in all environments — local development, Docker Compose, and production. The restart.sh script and docker-compose.yml start a local PostgreSQL container automatically.

bash
DATABASE_URL=postgresql://ghostai:ghostai_dev_password@localhost:5432/ghostai

SQLite (Opt-In Fallback) ​

If you cannot run Docker/PostgreSQL, you can fall back to SQLite by clearing DATABASE_URL and setting DATABASE_PATH. Note that SQLite uses a different SQL dialect from production, so some features may behave differently.

bash
DATABASE_URL=
DATABASE_PATH=./data/securechat.db

Scaling Considerations ​

Horizontal Scaling ​

  • Backend: Run multiple uvicorn workers or container instances
  • Frontend: Static files can be served from CDN
  • Database: Use PostgreSQL with read replicas

Memory Requirements ​

Detectors EnabledMinimum RAM
Presidio only2GB
Presidio + NER4GB
All detectors8GB

Performance Tuning ​

bash
# Increase workers for more concurrent requests
UVICORN_WORKERS=4

# Adjust detection timeout
DETECTION_TIMEOUT_MS=5000

# Enable caching
ENABLE_MODEL_CACHING=true

Next Steps ​

SOC 2 Type II Certified | BAA Available | HIPAA-Ready