Environment Variables

This reference lists all environment variables used by NFYio. Variables are grouped by service. Required variables must be set for the service to start; optional variables have defaults.

Core Variables

Variable	Required	Default	Description
NODE_ENV	No	development	development, production, or test
LOG_LEVEL	No	info	debug, info, warn, error
PUBLIC_URL	Yes (prod)	—	Public base URL (e.g., https://api.yourdomain.com)
PORT	No	3000	HTTP port for gateway
SESSION_SECRET	Yes	—	64+ character secret for session encryption. Generate with openssl rand -hex 64

Database

Variable	Required	Default	Description
DATABASE_URL	Yes	—	PostgreSQL connection string
POSTGRES_HOST	Yes*	—	PostgreSQL host (*if not using DATABASE_URL)
POSTGRES_PORT	No	5432	PostgreSQL port
POSTGRES_USER	Yes*	—	PostgreSQL username
POSTGRES_PASSWORD	Yes*	—	PostgreSQL password
POSTGRES_DB	Yes*	nfyio	PostgreSQL database name

Connection string format:

postgres://USER:PASSWORD@HOST:PORT/DATABASE?sslmode=disable

Redis

Variable	Required	Default	Description
REDIS_URL	Yes	—	Redis connection string
REDIS_HOST	Yes*	—	Redis host (*if not using REDIS_URL)
REDIS_PORT	No	6379	Redis port
REDIS_PASSWORD	No	—	Redis password (empty for no auth)

Connection string format:

redis://[:PASSWORD@]HOST:PORT[/DB]

Storage

Variable	Required	Default	Description
SEAWEEDFS_MASTER	Yes	—	SeaweedFS master URL (e.g., http://seaweedfs-master:9333)
STORAGE_PORT	No	7007	S3 proxy port
MAX_UPLOAD_SIZE	No	5368709120	Max upload size in bytes (default 5GB)
MULTIPART_PART_SIZE	No	67108864	Multipart part size (default 64MB)

Auth (Keycloak)

Variable	Required	Default	Description
KEYCLOAK_URL	Yes	—	Keycloak base URL (e.g., https://keycloak.yourdomain.com)
KEYCLOAK_REALM	No	nfyio	Keycloak realm
KEYCLOAK_CLIENT_ID	No	nfyio-gateway	Keycloak client ID
KEYCLOAK_CLIENT_SECRET	Yes*	—	Client secret (*for confidential clients)
KEYCLOAK_ADMIN	No	admin	Keycloak admin username
KEYCLOAK_ADMIN_PASSWORD	Yes	—	Keycloak admin password

AI / Embeddings

Variable	Required	Default	Description
EMBEDDINGS_ENABLED	No	false	Enable embedding pipeline
OPENAI_API_KEY	Yes*	—	OpenAI API key (*if using OpenAI)
OPENAI_EMBEDDING_MODEL	No	text-embedding-3-small	OpenAI embedding model
VOYAGE_API_KEY	Yes*	—	Voyage AI key (*if using Voyage)
VOYAGE_EMBEDDING_MODEL	No	voyage-2	Voyage embedding model
EMBEDDING_BATCH_SIZE	No	32	Batch size for embedding requests
CHUNK_SIZE	No	512	Default chunk size (tokens)
CHUNK_OVERLAP	No	50	Chunk overlap (tokens)

AI / Agent (LLM)

Variable	Required	Default	Description
DEFAULT_LLM_MODEL	No	gpt-4o-mini	Default LLM for agents
OPENAI_API_KEY	Yes*	—	OpenAI API key (*for GPT models)
ANTHROPIC_API_KEY	Yes*	—	Anthropic key (*for Claude)
MAX_CONTEXT_TOKENS	No	8192	Max context window size

Networking / CORS

Variable	Required	Default	Description
ALLOWED_ORIGINS	Yes (prod)	—	Comma-separated CORS origins (e.g., https://app.yourdomain.com)
CORS_MAX_AGE	No	86400	Preflight cache duration (seconds)
TRUST_PROXY	No	false	Trust X-Forwarded-* headers (set true behind reverse proxy)

Rate Limiting

Variable	Required	Default	Description
RATE_LIMIT_ENABLED	No	true	Enable rate limiting
RATE_LIMIT_PER_MIN	No	1000	Requests per minute per IP/key
RATE_LIMIT_BURST	No	100	Burst allowance

Example .env File

# ── Core ─────────────────────────────────────────────
NODE_ENV=production
LOG_LEVEL=info
PUBLIC_URL=https://api.yourdomain.com
SESSION_SECRET=your-64-char-hex-secret-from-openssl-rand-hex-64

# ── Database ──────────────────────────────────────────
DATABASE_URL=postgres://nfyio:your-password@postgres:5432/nfyio

# ── Redis ────────────────────────────────────────────
REDIS_URL=redis://:your-redis-password@redis:6379/0

# ── Storage ──────────────────────────────────────────
SEAWEEDFS_MASTER=http://seaweedfs-master:9333

# ── Auth (Keycloak) ─────────────────────────────────
KEYCLOAK_URL=https://keycloak.yourdomain.com
KEYCLOAK_REALM=nfyio
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=your-keycloak-admin-password

# ── AI (optional) ────────────────────────────────────
EMBEDDINGS_ENABLED=true
OPENAI_API_KEY=sk-...
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# ── Networking ──────────────────────────────────────
ALLOWED_ORIGINS=https://app.yourdomain.com,https://admin.yourdomain.com
TRUST_PROXY=true

Variable Precedence

1. Environment — Variables set in the shell or container
2. .env file — Loaded by Docker Compose or the application
3. Defaults — Application defaults for optional variables

Security Notes

• Never commit .env files to version control. Add .env to .gitignore.
• Use secrets management (e.g., Docker secrets, Kubernetes secrets) in production.
• Rotate SESSION_SECRET, database passwords, and API keys periodically.
• Restrict ALLOWED_ORIGINS to your actual domains.

Next Steps

• Configuration Reference — Docker Compose and Helm
• Installation Guide — Deployment setup
• CORS Configuration — CORS details
• Security Best Practices — Hardening