All Docs

Configuration Reference

Docker Compose configuration, Helm values, service-specific config, TLS/SSL setup, and custom domains for NFYio.

This reference covers Docker Compose, Helm, service-specific configuration, and TLS/SSL setup for NFYio deployments.

Docker Compose Configuration

Basic Structure

# docker-compose.yml
services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data

  nfyio-gateway:
    image: nfyio/gateway:latest
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      REDIS_URL: redis://:${REDIS_PASSWORD}@redis:6379
      SESSION_SECRET: ${SESSION_SECRET}
    ports:
      - "3000:3000"

volumes:
  postgres_data:
  redis_data:

Override for Production

# docker-compose.override.yml
services:
  nfyio-gateway:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M
    restart: unless-stopped

Helm Values

Core Values

# values.yaml
global:
  imageRegistry: ""
  imagePullSecrets: []

gateway:
  replicaCount: 2
  image:
    repository: nfyio/gateway
    tag: latest
    pullPolicy: IfNotPresent
  service:
    type: ClusterIP
    port: 3000
  ingress:
    enabled: true
    className: nginx
    annotations:
      cert-manager.io/cluster-issuer: letsencrypt-prod
    hosts:
      - host: api.yourdomain.com
        paths:
          - path: /
            pathType: Prefix
    tls:
      - secretName: api-tls
        hosts:
          - api.yourdomain.com
  resources:
    limits:
      cpu: 2000m
      memory: 2Gi
    requests:
      cpu: 500m
      memory: 512Mi

storage:
  replicaCount: 1
  image:
    repository: nfyio/storage
    tag: latest
  service:
    port: 7007
  ingress:
    enabled: true
    hosts:
      - host: storage.yourdomain.com

postgresql:
  enabled: true
  auth:
    username: nfyio
    password: ""  # Set via --set or secrets
    database: nfyio
  primary:
    persistence:
      enabled: true
      size: 20Gi

redis:
  enabled: true
  auth:
    enabled: true
    password: ""  # Set via --set or secrets

Install with Custom Values

helm install nfyio nfyio/nfyio \
  -f values.yaml \
  --set postgresql.auth.password=$PG_PASSWORD \
  --set redis.auth.password=$REDIS_PASSWORD \
  --set gateway.ingress.hosts[0].host=api.yourdomain.com

Service-Specific Configuration

API Gateway

VariableDescriptionDefault
PORTHTTP port3000
DATABASE_URLPostgreSQL connection stringRequired
REDIS_URLRedis connection stringRequired
SESSION_SECRETSession encryption key (64+ chars)Required
KEYCLOAK_URLKeycloak base URL—
KEYCLOAK_REALMKeycloak realmnfyio
ALLOWED_ORIGINSCORS origins (comma-separated)—
RATE_LIMIT_PER_MINAPI rate limit1000
LOG_LEVELLog level (debug, info, warn, error)info

Storage Proxy

VariableDescriptionDefault
PORTS3 proxy port7007
SEAWEEDFS_MASTERSeaweedFS master URLhttp://seaweedfs-master:9333
GATEWAY_URLAPI gateway URL (for auth)—
MAX_UPLOAD_SIZEMax upload size (bytes)5GB
MULTIPART_PART_SIZEMultipart part size64MB

Embedding Service

VariableDescriptionDefault
OPENAI_API_KEYOpenAI API key—
OPENAI_EMBEDDING_MODELEmbedding modeltext-embedding-3-small
VOYAGE_API_KEYVoyage AI key (alternative)—
BATCH_SIZEEmbedding batch size32
CHUNK_SIZEDefault chunk size (tokens)512
CHUNK_OVERLAPChunk overlap50

Agent Service

VariableDescriptionDefault
PORTAgent API port7010
OPENAI_API_KEYOpenAI API key—
DEFAULT_MODELDefault LLM modelgpt-4o-mini
MAX_CONTEXT_TOKENSMax context window8192
DATABASE_URLFor RAG/embeddings—

TLS/SSL Setup

Reverse Proxy (Nginx)

# /etc/nginx/sites-available/nfyio
upstream gateway {
    server localhost:3000;
}

upstream storage {
    server localhost:7007;
}

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

    ssl_certificate /etc/letsencrypt/live/api.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.yourdomain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;

    location / {
        proxy_pass http://gateway;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

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

    ssl_certificate /etc/letsencrypt/live/storage.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/storage.yourdomain.com/privkey.pem;

    client_max_body_size 5G;

    location / {
        proxy_pass http://storage;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Caddy (Automatic HTTPS)

api.yourdomain.com {
    reverse_proxy localhost:3000
}

storage.yourdomain.com {
    reverse_proxy localhost:7007
    request_body {
        max_size 5GB
    }
}

Certbot (Let’s Encrypt)

# Install certbot
sudo apt install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d api.yourdomain.com -d storage.yourdomain.com

# Auto-renewal (cron)
0 0 1 * * certbot renew --quiet

Custom Domains

API Gateway

Set PUBLIC_URL to your custom domain:

PUBLIC_URL=https://api.yourdomain.com

Update Keycloak redirect URIs to include https://api.yourdomain.com/*.

Storage Proxy

Configure the storage endpoint in client applications:

const client = new NfyioClient({
  apiUrl: 'https://api.yourdomain.com',
  storageUrl: 'https://storage.yourdomain.com',
  apiKey: process.env.NFYIO_API_KEY,
});

CORS

Allow your frontend origins:

ALLOWED_ORIGINS=https://app.yourdomain.com,https://admin.yourdomain.com

Configuration Checklist

  • All secrets set (SESSION_SECRET, DB, Redis, Keycloak)
  • TLS/SSL configured for production
  • Custom domains and CORS configured
  • Resource limits set for containers
  • Health checks configured
  • Log level appropriate for environment

Next Steps

Edit this page on GitHub