Self-Hosted Deployment

Quick Start

curl -sSL https://get.airaproof.com/install.sh | bash

The installer prompts for your license key, registry token, domain, and AI provider keys. It generates all secrets, configures HTTPS, and starts everything automatically.

What gets installed

https://governance.acme.com
        |
     [Traefik] — automatic HTTPS (Let's Encrypt)
        |
   -----+-----
   |         |
 /api/*     /*
   |         |
 [API]   [Frontend]
   |
[Worker]  [PostgreSQL 17]  [Redis 7]

All services run as Docker containers on a single domain. Traefik routes /api/* to the backend and everything else to the dashboard.

Prerequisites

Server

Software

• Docker 24+ with Docker Compose v2
• openssl (for key generation)

Network

• Domain name (e.g., governance.acme.com) with a DNS A record pointing to the server IP
• Ports 80 and 443 open in your firewall
• No other web server running on the same ports

Credentials

Contact support@airaproof.com to receive:

• License key — Ed25519-signed, validates at startup and per-request. Encodes your org name, tier, expiry, and domain.
• Registry token — grants access to pull Docker images from ghcr.io/aira-proof/*

Installation

The installer handles everything:

1. Authenticates with the container registry
2. Generates all cryptographic keys (JWT secret, Ed25519 signing keys, database password)
3. Writes docker-compose.yml, .env, and docker-compose.yml
4. Pulls Docker images
5. Runs database migrations
6. Starts all services with health checks
7. Obtains a TLS certificate from Let's Encrypt

curl -sSL https://get.airaproof.com/install.sh | bash

The script prompts for:

All config files are written to /opt/aira.

After installation

Open https://your-domain.com and register your admin account. Email verification is skipped in self-hosted mode — you can log in immediately.

Interactive API docs

Your instance includes Swagger UI and ReDoc:

• Swagger: https://your-domain.com/docs
• ReDoc: https://your-domain.com/redoc

SDK configuration

Point your SDKs to your self-hosted domain:

from aira import Aira

aira = Aira(
    api_key="aira_live_...",
    base_url="https://governance.acme.com",
)

import { Aira } from "aira-sdk";

const aira = new Aira({
    apiKey: "aira_live_...",
    baseUrl: "https://governance.acme.com",
});

Note: the base_url is your domain root (not /api/v1). The SDK adds the API prefix automatically.

Manage

cd /opt/aira

# View API logs
docker compose logs -f api

# Upgrade to latest version
./upgrade.sh

# Backup database
./backup.sh

# Stop all services
docker compose down

# Restart
docker compose up -d

# Uninstall
./uninstall.sh

Upgrade

cd /opt/aira && ./upgrade.sh

This backs up the database, pulls latest images, runs migrations, and rolls out services with zero downtime using docker-rollout. New containers start and pass health checks before old ones are removed — no request is dropped.

Backup

cd /opt/aira && ./backup.sh

Creates a compressed PostgreSQL dump in backups/. Keeps the 14 most recent backups automatically.

Configuration

All configuration is in /opt/aira/.env. After editing, restart affected services:

docker compose up -d --force-recreate api worker frontend

Adding AI providers later

Edit .env:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AIza...
DEEPSEEK_API_KEY=sk-...
XAI_API_KEY=xai-...

Then restart with zero downtime: docker rollout api && docker compose restart worker

You can also configure provider keys from the dashboard under Models > Providers using the BYOK API.

Environment variables

Required (generated by installer)

Optional

Custom TLS certificates

If you can't use Let's Encrypt (internal network, air-gapped, custom CA):

1. The installer will ask during setup, or
2. Place your files manually:

cp your-cert.pem /opt/aira/certs/cert.pem
cp your-key.pem /opt/aira/certs/key.pem

Create /opt/aira/dynamic/certs.yml:

tls:
  certificates:
    - certFile: /certs/cert.pem
      keyFile: /certs/key.pem

Restart Traefik: docker compose restart traefik

SSO / Social Login

Self-hosted deployments support the same SSO options as cloud:

• SAML 2.0 — Okta, Azure AD, Google Workspace, OneLogin
• OpenID Connect — any OIDC-compliant provider
• Social logins — Google, GitHub, GitLab (optional)

For social login, create OAuth apps in your provider's console with this redirect URI:

https://governance.acme.com/api/auth/callback/{provider}

Where {provider} is google, github, or gitlab.

For SAML/OIDC enterprise SSO, configure from Dashboard > Settings > Single Sign-On.

Self-hosted vs Cloud

Troubleshooting

License errors

"FATAL: Self-hosted deployment requires AIRA_LICENSE_KEY" — set AIRA_LICENSE_KEY in .env. Contact support@airaproof.com if you don't have one.

"FATAL: Invalid AIRA_LICENSE_KEY" — the key is malformed, expired, or tampered with. Check the full key was copied (long base64url string with two dots).

API returns 403 "License invalid" — the license expired at runtime. Renew and restart: docker rollout api

API won't start

docker compose logs api --tail 30

Common causes:

• Missing/expired license key
• Database not ready — wait or docker rollout api
• Port conflict — ensure nothing else is on port 8000 internally

TLS certificate issues

docker compose logs traefik --tail 20

• NXDOMAIN — DNS A record not set for your domain
• Rate limited — Let's Encrypt allows 5 duplicate certs per week. Wait or use custom certs.
• Port 80 blocked — Traefik needs port 80 for ACME HTTP-01 challenges

Can't pull images

docker pull ghcr.io/aira-proof/backend:latest

If this fails, re-authenticate: echo $TOKEN | docker login ghcr.io -u aira-customer --password-stdin

Database password mismatch

If you changed DB_PASS after initial setup:

docker compose exec db psql -U aira -c "ALTER USER aira PASSWORD 'new-password';"

Or reset completely: docker compose down -v && docker compose up -d

Support

support@airaproof.com