Self-Hosting

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

Clone the repository

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

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=noreply@yourdomain.com

Start services

docker compose up -d

This starts:

API on port 3001
Dashboard on port 3000
Widget on port 3002
PostgreSQL with pgvector

Run migrations

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

Configuration

Environment Variables

Variable	Required	Description
`ANTHROPIC_API_KEY`	One of	Anthropic API key for Claude models
`OPENAI_API_KEY`	these	OpenAI API key for GPT models
`BETTER_AUTH_SECRET`	Yes	Secret for session encryption
`DATABASE_URL`	No	Auto-configured for Docker
`API_URL`	No	Public API URL (default: http://localhost:3001)
`DASHBOARD_URL`	No	Public dashboard URL (default: http://localhost:3000)
`WIDGET_URL`	No	Public widget URL (default: http://localhost:3002)
`DOCS_URL`	No	Documentation URL
`RESEND_API_KEY`	No	For email verification/magic links
`EMAIL_FROM`	No	Sender email address
`GOOGLE_CLIENT_ID`	No	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	No	Google OAuth client secret
`GITHUB_CLIENT_ID`	No	GitHub OAuth client ID
`GITHUB_CLIENT_SECRET`	No	GitHub OAuth client secret

Production Setup

For production deployments:

Use a reverse proxy (nginx, Caddy, Traefik) for SSL termination

Set proper URLs in your .env:

API_URL=https://api.yourdomain.com
DASHBOARD_URL=https://app.yourdomain.com
WIDGET_URL=https://widget.yourdomain.com

Use a managed database for better reliability
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

Database connection errors

Make sure PostgreSQL is running and healthy:

docker compose ps
docker compose logs postgres

Widget not loading

Email not sending

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

Getting Started

User Guides

Use Cases

Developer Guides

Tools & Forms

Integrations

API Reference

Support

Self-Hosting

Overview

Prerequisites

Quick Start

Configuration

Environment Variables

Production Setup

Example nginx Configuration

Updating

Troubleshooting

​Overview

​Prerequisites

​Quick Start

​Configuration

​Environment Variables

​Production Setup

​Example nginx Configuration

​Updating

​Troubleshooting

Overview

Prerequisites

Quick Start

Configuration

Environment Variables

Production Setup

Example nginx Configuration

Updating

Troubleshooting