Installation Guide

This guide walks you through deploying NFYio on your own infrastructure. Choose the method that best fits your environment.

System Requirements

Minimum (Development / Testing)

Resource	Requirement
CPU	2 cores
RAM	4 GB
Storage	20 GB SSD
OS	Linux (Ubuntu 22.04+, Debian 12+, or similar)

Recommended (Production)

Resource	Requirement
CPU	8 cores
RAM	16 GB
Storage	100 GB SSD (more for object storage)
Network	Stable connectivity for AI API calls

Installation Methods

Docker Compose (Recommended)

Docker Compose is the fastest way to get NFYio running. All services are defined in a single stack.

1. Clone the Repository

git clone https://github.com/hilaltechnologic/nfyio.git
cd nfyio

2. Configure Environment Variables

cp .env.example .env

Edit .env with your values. Key variables:

# ── Security ──────────────────────────────────────
SESSION_SECRET=generate-with-openssl-rand-hex-64

# ── Database ──────────────────────────────────────
POSTGRES_PASSWORD=strong-password-here
POSTGRES_DB=nfyio
POSTGRES_USER=nfyio

# ── Redis ─────────────────────────────────────────
REDIS_PASSWORD=redis-password-here

# ── Keycloak ──────────────────────────────────────
KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=keycloak-admin-password

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

# ── CORS ──────────────────────────────────────────
ALLOWED_ORIGINS=https://app.yourdomain.com

# ── Site ──────────────────────────────────────────
PUBLIC_URL=https://yourdomain.com

Generate a secure session secret:

openssl rand -hex 64

3. Start the Platform

docker compose up -d

This starts:

• postgres — Main database with pgvector (port 5432)
• redis — Session store and job queue (port 6379)
• seaweedfs-master — SeaweedFS master node (port 9333)
• seaweedfs-volume — SeaweedFS volume node (port 8080)
• keycloak — Authentication server (port 8443)
• nfyio-gateway — Main API gateway (port 3000)
• nfyio-storage — S3-compatible storage proxy (port 7007)
• nfyio-agent — Agentic RAG service (port 7010)

Kubernetes (Helm)

For production Kubernetes deployments, use the official Helm chart:

helm repo add nfyio https://charts.nfyio.io
helm repo update
helm install nfyio nfyio/nfyio -f values.yaml

Create a values.yaml to override defaults (secrets, resource limits, ingress, etc.). See the chart repository for full options.

Manual Installation

For bare-metal or custom orchestration:

1. Install PostgreSQL 15+ with pgvector extension
2. Install Redis 7+
3. Deploy SeaweedFS (master + volume nodes)
4. Deploy Keycloak
5. Build and run NFYio gateway, storage proxy, and agent services

Refer to the NFYio repository for Dockerfiles and startup scripts that can be adapted for manual deployment.

Configuration

Environment Variables

Variable	Description	Default
SESSION_SECRET	Secret for session encryption (64+ chars)	Required
POSTGRES_*	Database connection and credentials	—
REDIS_PASSWORD	Redis authentication	—
KEYCLOAK_*	Keycloak admin credentials	—
EMBEDDINGS_ENABLED	Enable embedding pipeline	false
OPENAI_API_KEY	OpenAI API key for embeddings/LLM	—
ALLOWED_ORIGINS	CORS allowed origins (comma-separated)	—
PUBLIC_URL	Public base URL of the platform	—

Database Setup

Migrations run automatically on first start. To run them manually:

docker compose exec nfyio-gateway deno task migrate

Storage Backend

NFYio uses SeaweedFS for object storage. Ensure the SeaweedFS master and volume nodes are reachable from the storage proxy. Replication and volume configuration can be tuned in the SeaweedFS deployment.

Post-Installation Verification

Health Checks

# All containers healthy
docker compose ps

# Gateway
curl http://localhost:3000/health
# → {"status":"ok","version":"0.9.0"}

# Storage proxy
curl http://localhost:7007/health
# → {"status":"ok","backend":"seaweedfs"}

# Agent service
curl http://localhost:7010/health
# → {"status":"ok","model":"gpt-4o"}

Create First Admin User

docker compose exec nfyio-gateway deno task seed:admin \
  --email admin@yourdomain.com \
  --password your-secure-password

Test S3 Access

aws --endpoint-url http://localhost:7007 s3 ls

Troubleshooting

Containers Not Starting

• Out of memory: Ensure at least 4GB RAM. Check docker stats.
• Port conflicts: Verify ports 3000, 5432, 6379, 7007, 7010, 8080, 8443, 9333 are free.
• Permission errors: Run Docker with appropriate user/group or use root if in dev.

Database Connection Errors

• Wait for PostgreSQL to be fully ready before starting gateway (use depends_on and healthchecks).
• Verify POSTGRES_PASSWORD, POSTGRES_DB, and POSTGRES_USER match across services.

Storage Proxy Fails

• Ensure SeaweedFS master is running and reachable on port 9333.
• Check SeaweedFS volume node logs for disk or network issues.

Keycloak Issues

• First startup can take 1–2 minutes. Retry health checks.
• Ensure KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD are set correctly.
• Check Keycloak logs: docker compose logs keycloak

AI/Embedding Pipeline Not Working

• Set EMBEDDINGS_ENABLED=true and provide a valid OPENAI_API_KEY.
• For Voyage AI, configure VOYAGE_API_KEY and VOYAGE_EMBEDDING_MODEL.
• Verify network access to the AI provider APIs.

Production Checklist

Before going to production:

• Set a strong SESSION_SECRET (64+ chars)
• Change all default passwords
• Configure a reverse proxy (nginx / Caddy) with TLS
• Set ALLOWED_ORIGINS to your actual domain
• Enable Keycloak realm export for backup
• Set up automated PostgreSQL backups
• Configure SeaweedFS replication for HA

Updating NFYio

git pull origin main
docker compose pull
docker compose up -d
docker compose exec nfyio-gateway deno task migrate

Uninstall

# Stop all containers
docker compose down

# Remove volumes (WARNING: deletes all data)
docker compose down -v