> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usevela.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-Hosting

> Deploy Ansa on your own infrastructure

## 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

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/ansa/ansa.git
    cd ansa
    ```
  </Step>

  <Step title="Create environment file">
    ```bash theme={null}
    cp .env.example .env
    ```

    Edit `.env` and add your API keys:

    ```bash theme={null}
    # 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
    ```
  </Step>

  <Step title="Start services">
    ```bash theme={null}
    docker compose up -d
    ```

    This starts:

    * **API** on port 3001
    * **Dashboard** on port 3000
    * **Widget** on port 3002
    * **PostgreSQL** with pgvector
  </Step>

  <Step title="Run migrations">
    ```bash theme={null}
    docker compose exec api pnpm --filter @ansa/db db:migrate
    ```
  </Step>
</Steps>

## 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](http://localhost:3001))       |
| `DASHBOARD_URL`        | No       | Public dashboard URL (default: [http://localhost:3000](http://localhost:3000)) |
| `WIDGET_URL`           | No       | Public widget URL (default: [http://localhost:3002](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:

1. **Use a reverse proxy** (nginx, Caddy, Traefik) for SSL termination
2. **Set proper URLs** in your `.env`:
   ```bash theme={null}
   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

```nginx theme={null}
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:

```bash theme={null}
git pull
docker compose build
docker compose up -d
docker compose exec api pnpm --filter @ansa/db db:migrate
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Database connection errors">
    Make sure PostgreSQL is running and healthy:

    ```bash theme={null}
    docker compose ps
    docker compose logs postgres
    ```
  </Accordion>

  <Accordion title="Widget not loading">
    Check that the widget URL is accessible and CORS is configured properly.
    The API allows requests from `DASHBOARD_URL` and `WIDGET_URL`.
  </Accordion>

  <Accordion title="Email not sending">
    Verify your `RESEND_API_KEY` and `EMAIL_FROM` are set correctly.
    Check the API logs for email errors:

    ```bash theme={null}
    docker compose logs api | grep -i email
    ```
  </Accordion>
</AccordionGroup>