Skip to main content

​
Overview

Ansa can be self-hosted using Docker. This gives you full control over your data and infrastructure.

​
Prerequisites

  • Docker and Docker Compose
  • An LLM API key (Anthropic or OpenAI)
  • A domain with SSL (for production)

​
Quick Start

1

Clone the repository

git clone https://github.com/ansa/ansa.git
cd ansa
2

Create environment file

cp .env.example .env
Edit .env and add your API keys:
# Required: At least one LLM provider
ANTHROPIC_API_KEY=sk-ant-...
# or
OPENAI_API_KEY=sk-...

# Required: Auth secret (generate with: openssl rand -base64 32)
BETTER_AUTH_SECRET=your-secret-key

# Optional: Email (for magic links)
RESEND_API_KEY=re_...
EMAIL_FROM=[email protected]
3

Start services

docker compose up -d
This starts:
  • API on port 3001
  • Dashboard on port 3000
  • Widget on port 3002
  • PostgreSQL with pgvector
4

Run migrations

docker compose exec api pnpm --filter @ansa/db db:migrate

​
Configuration

​
Environment Variables

VariableRequiredDescription
ANTHROPIC_API_KEYOne ofAnthropic API key for Claude models
OPENAI_API_KEYtheseOpenAI API key for GPT models
BETTER_AUTH_SECRETYesSecret for session encryption
DATABASE_URLNoAuto-configured for Docker
API_URLNoPublic API URL (default: http://localhost:3001)
DASHBOARD_URLNoPublic dashboard URL (default: http://localhost:3000)
WIDGET_URLNoPublic widget URL (default: http://localhost:3002)
DOCS_URLNoDocumentation URL
RESEND_API_KEYNoFor email verification/magic links
EMAIL_FROMNoSender email address
GOOGLE_CLIENT_IDNoGoogle OAuth client ID
GOOGLE_CLIENT_SECRETNoGoogle OAuth client secret
GITHUB_CLIENT_IDNoGitHub OAuth client ID
GITHUB_CLIENT_SECRETNoGitHub OAuth client secret

​
Production Setup

For production deployments:
  1. Use a reverse proxy (nginx, Caddy, Traefik) for SSL termination
  2. Set proper URLs in your .env: 
    API_URL=https://api.yourdomain.com
DASHBOARD_URL=https://app.yourdomain.com
WIDGET_URL=https://widget.yourdomain.com
  3. Use a managed database for better reliability
  4. Enable backups for your PostgreSQL data

​
Example nginx Configuration

server {
    listen 443 ssl http2;
    server_name api.yourdomain.com;

    ssl_certificate /etc/ssl/certs/your-cert.pem;
    ssl_certificate_key /etc/ssl/private/your-key.pem;

    location / {
        proxy_pass http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

​
Updating

To update to the latest version: 
git pull
docker compose build
docker compose up -d
docker compose exec api pnpm --filter @ansa/db db:migrate

​
Troubleshooting

Make sure PostgreSQL is running and healthy:
docker compose ps
docker compose logs postgres
Check that the widget URL is accessible and CORS is configured properly. The API allows requests from DASHBOARD_URL and WIDGET_URL.
Verify your RESEND_API_KEY and EMAIL_FROM are set correctly. Check the API logs for email errors:
docker compose logs api | grep -i email