Appearance
Full Installation Guide
This guide covers all installation options including Docker, production deployment, and advanced configuration.
Installation Options
| Method | Best For | Time |
|---|---|---|
| Quick Start | Development, testing | 5 min |
| Docker Compose | Local production-like | 10 min |
| Production Docker | On-premise with HTTPS | 15 min |
| Manual Setup | Custom environments | 20 min |
| AWS ECS | Enterprise cloud | 30 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 -dServices Started
| Service | Port | Description |
|---|---|---|
| Backend | 8000 | FastAPI application |
| Frontend | 80 | React 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 backendStop Services
bash
docker compose down
# To remove volumes (data)
docker compose down -vManual 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 settingsEnvironment 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.comSaaS 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.comSee 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 4Frontend Setup
bash
cd securechat/frontend
# Install dependencies
npm install
# Development
npm run dev
# Production build
npm run build
npm run previewAWS 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:latestCreate 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 FARGATEProduction 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/healthWhat's Included
| Service | Description |
|---|---|
| Caddy | Automatic Let's Encrypt HTTPS |
| PostgreSQL | Production database |
| Redis | Session cache |
| Backend | FastAPI application |
| Frontend | React app (Nginx) |
SSL Options
| Type | Configuration | Use Case |
|---|---|---|
| Let's Encrypt | Set DOMAIN env var | Public domains |
| Self-signed | Use tls internal in Caddyfile | Private networks |
| None | Remove Caddy | Behind load balancer |
SSL/TLS Configuration
Development (Self-Signed)
The frontend development server uses self-signed certificates. Accept the browser warning on first visit.
Production with Caddy (Recommended)
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/ghostaiSQLite (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.dbScaling 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 Enabled | Minimum RAM |
|---|---|
| Presidio only | 2GB |
| Presidio + NER | 4GB |
| All detectors | 8GB |
Performance Tuning
bash
# Increase workers for more concurrent requests
UVICORN_WORKERS=4
# Adjust detection timeout
DETECTION_TIMEOUT_MS=5000
# Enable caching
ENABLE_MODEL_CACHING=trueNext Steps
- Configure Your Vertical - Industry-specific settings
- Set Up SSO - Enterprise authentication
- API Integration - Build custom integrations