Quick Start Guide

This guide gets you from zero to a running NFYio instance with your first bucket and file in about 5 minutes.

Prerequisites

Before you begin, ensure you have:

Docker 24+ and Docker Compose v2+
4GB RAM minimum (8GB recommended for AI features)
Git for cloning the repository

5-Minute Setup

Step 1: Clone the Repository

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

Step 2: Configure Environment

Copy the example environment file and edit it with your values:

cp .env.example .env

Minimum required configuration in .env:

# Security (generate with: openssl rand -hex 64)
SESSION_SECRET=your-64-char-hex-secret

# Database
POSTGRES_PASSWORD=your-postgres-password
POSTGRES_DB=nfyio
POSTGRES_USER=nfyio

# Redis
REDIS_PASSWORD=your-redis-password

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

Generate a secure session secret:

openssl rand -hex 64

Step 3: Start NFYio

docker compose up -d

Wait for all services to become healthy (about 30–60 seconds). Verify with:

docker compose ps

All services should show Up or healthy.

Step 4: Create Your First Bucket

Install the AWS CLI if you haven’t already, then configure it to use NFYio’s S3-compatible endpoint:

# Create a bucket named "my-first-bucket"
aws --endpoint-url http://localhost:7007 s3 mb s3://my-first-bucket

You should see:

make_bucket: my-first-bucket

Step 5: Upload a File

Create a test file and upload it:

echo "Hello from NFYio!" > hello.txt
aws --endpoint-url http://localhost:7007 s3 cp hello.txt s3://my-first-bucket/

List objects to confirm:

aws --endpoint-url http://localhost:7007 s3 ls s3://my-first-bucket/

Output:

2026-03-01 12:00:00         18 hello.txt

Service Endpoints

Once running, NFYio exposes:

Service	URL	Purpose
Gateway	`http://localhost:3000`	API, auth, dashboard
Storage Proxy	`http://localhost:7007`	S3-compatible object storage
Agent Service	`http://localhost:7010`	RAG, LLM, workflows

What’s Next

Installation Guide — Full deployment options, system requirements, and troubleshooting
Architecture Overview — Understand how NFYio components work together
Core Concepts — Buckets, agents, embeddings, and access control