Skip to main content
Airstore is open source. Run your own instance for full control over data and infrastructure.

Architecture

A self-hosted Airstore deployment includes:
  • Gateway: Handles queries, caching, and API translation
  • Storage: S3-compatible storage for materialized views
  • Database: SQLite or Postgres for metadata and tokens

Docker Compose

The quickest way to self-host:
# docker-compose.yaml
version: '3.8'

services:
  gateway:
    image: ghcr.io/beam-cloud/airstore:latest
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgres://postgres:postgres@db:5432/airstore
      - S3_ENDPOINT=http://minio:9000
      - S3_BUCKET=airstore
      - S3_ACCESS_KEY=minioadmin
      - S3_SECRET_KEY=minioadmin
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}
    depends_on:
      - db
      - minio

  db:
    image: postgres:15
    environment:
      - POSTGRES_DB=airstore
      - POSTGRES_PASSWORD=postgres
    volumes:
      - postgres_data:/var/lib/postgresql/data

  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    environment:
      - MINIO_ROOT_USER=minioadmin
      - MINIO_ROOT_PASSWORD=minioadmin
    volumes:
      - minio_data:/data

volumes:
  postgres_data:
  minio_data:
Start the stack:
# Generate encryption key
export ENCRYPTION_KEY=$(openssl rand -hex 32)

# Start services
docker-compose up -d

Configure CLI

Point the CLI to your self-hosted instance:
airstore config set api_url http://localhost:8080
Or set via environment:
export AIRSTORE_API_URL=http://localhost:8080

Production deployment

For production, consider:

Use managed services

# docker-compose.prod.yaml
services:
  gateway:
    image: ghcr.io/beam-cloud/airstore:latest
    environment:
      - DATABASE_URL=postgres://user:pass@your-rds-instance:5432/airstore
      - S3_ENDPOINT=https://s3.amazonaws.com
      - S3_BUCKET=your-airstore-bucket
      - S3_ACCESS_KEY=${AWS_ACCESS_KEY}
      - S3_SECRET_KEY=${AWS_SECRET_KEY}
      - ENCRYPTION_KEY=${ENCRYPTION_KEY}

Kubernetes

# airstore.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: airstore-gateway
spec:
  replicas: 3
  selector:
    matchLabels:
      app: airstore
  template:
    metadata:
      labels:
        app: airstore
    spec:
      containers:
        - name: gateway
          image: ghcr.io/beam-cloud/airstore:latest
          ports:
            - containerPort: 8080
          envFrom:
            - secretRef:
                name: airstore-secrets
---
apiVersion: v1
kind: Service
metadata:
  name: airstore
spec:
  selector:
    app: airstore
  ports:
    - port: 80
      targetPort: 8080

Configuration

Full configuration options in config.yaml:
# /etc/airstore/config.yaml
server:
  port: 8080
  host: 0.0.0.0

database:
  url: postgres://user:pass@localhost:5432/airstore
  # Or SQLite for simpler deployments
  # url: sqlite:///var/lib/airstore/db.sqlite

storage:
  type: s3
  endpoint: https://s3.amazonaws.com
  bucket: airstore-data
  access_key: ${S3_ACCESS_KEY}
  secret_key: ${S3_SECRET_KEY}

security:
  encryption_key: ${ENCRYPTION_KEY}
  
audit:
  retention_days: 90

sync:
  interval_seconds: 15

OAuth configuration

Configure OAuth apps for each source:
oauth:
  gmail:
    client_id: ${GMAIL_CLIENT_ID}
    client_secret: ${GMAIL_CLIENT_SECRET}
    redirect_uri: https://your-domain.com/oauth/gmail/callback
  
  github:
    client_id: ${GITHUB_CLIENT_ID}
    client_secret: ${GITHUB_CLIENT_SECRET}
    redirect_uri: https://your-domain.com/oauth/github/callback
Create OAuth apps in each provider’s developer console and set the redirect URIs.

Backup and recovery

Database backup

# Postgres
pg_dump airstore > backup.sql

# Restore
psql airstore < backup.sql

S3 backup

Use S3 versioning or cross-region replication for storage durability.

Monitoring

Airstore exposes Prometheus metrics:
curl http://localhost:8080/metrics
Key metrics:
  • airstore_requests_total: Total API requests
  • airstore_sync_duration_seconds: Sync operation duration
  • airstore_cache_hits_total: Cache hit rate

Next steps