Installation Guide
The NuFi platform is deployed into airgapped environments using Zarf. Transfer the installation bundle to the target server and run the script — everything from K3s cluster creation to platform deployment proceeds automatically.
Prerequisites
| Item | Requirement |
|---|---|
| OS | Ubuntu 22.04+ (x86_64) |
| CPU | 4 cores or more |
| RAM | 16 GB or more |
| Disk | 200 GB or more |
| GPU (optional) | NVIDIA driver 575.51.03+ / CUDA 12.9+ |
When using an NVIDIA GPU, you only need to pre-install the NVIDIA driver. The NVIDIA Container Toolkit is included in the installation bundle and will be installed automatically.
Installation Procedure
1. Transfer the Bundle
Transfer the installation bundle directory to the target server (via USB, SCP, etc.).
nufi/
├── .env # Environment configuration
├── install.sh # Installation script
├── zarf # Zarf binary
├── zarf-init-*.tar.zst # Zarf Init package (includes K3s)
├── nufi-amd64-*.tar.zst # NuFi platform package
├── realm-export.json # Keycloak configuration
├── nvidia-container-toolkit/ # NVIDIA CTK package (deb)
├── models/ # AI model cache
└── docs/
└── install-guide.md
└── dns-setup-guide.md
2. Environment Configuration
Edit the .env file:
BASE_DOMAIN=nufi.com # Service domain
PASSWORD=nufi1234 # Shared password for Keycloak and Grafana
PROTOCOL=http # http or https
NUFI_VERSION=0.1.0 # NuFi version to deploy
| Variable | Description | Example |
|---|---|---|
BASE_DOMAIN | Domain used to access services. After installation, you access subdomains such as dashboard.{domain}, grafana.{domain}. If you change the domain, you also need to update the DNS setup in docs/dns-setup-guide.md to match. | nufi.com |
PASSWORD | Shared password for the Keycloak admin and Grafana admin | nufi1234 |
PROTOCOL | Service protocol. Use https if a TLS certificate is ready, otherwise http | http |
NUFI_VERSION | NuFi platform version to deploy. Must match the version of the nufi-amd64-*.tar.zst file in the bundle directory. | 0.1.0 |
3. Run the Installer
sudo ./install.sh
Registry Configuration
NuFi uses only the Zarf built-in registry. During installation, a lightweight registry is automatically configured inside the cluster.
To use container images brought in from outside, after installation go to Admin > External Images and upload a tar file created with docker save. Uploaded images are automatically imported into the internal registry and become selectable when creating a Serving or Lab. See External Images Management for details.
Installation Stages
After running sudo ./install.sh, the following proceeds automatically:
[1/8] Install Zarf
[2/8] System configuration (+ install NVIDIA Container Toolkit)
[3/8] Deploy AI model cache
[4/8] Create K3s cluster (zarf init)
[5/8] Deploy NuFi Platform
[6/8] Add CoreDNS rewrite rules
[7/8] Keycloak Realm Import
[8/8] Final status
| Stage | Description |
|---|---|
| Install Zarf | Install the Zarf CLI binary on the system |
| System configuration | Disable swap, configure ports, install NVIDIA CTK (GPU server) |
| Deploy AI model cache | Deploy bundled models to /mnt/data/cache/huggingface/hub/ |
| Create K3s cluster | zarf init sets up K3s + Flannel CNI + the built-in registry in one step |
| Deploy NuFi Platform | Deploy the full NuFi-related stack including Prometheus, JuiceFS, etc. |
| CoreDNS rewrite | Route *.{domain} requests to the Istio Ingress Gateway |
| Keycloak Realm Import | Create the auth realm and the default user (admin) |
If an NVIDIA GPU is detected, the containerd nvidia runtime configuration and the RuntimeClass are set up automatically.
Installation Complete
When installation finishes, the connection information is printed:
Access URLs:
Dashboard: http://dashboard.nufi.com
Grafana: http://grafana.nufi.com
Keycloak: http://keycloak.nufi.com
Default account: admin / <password you configured>
The actual URLs are determined by the BASE_DOMAIN and PROTOCOL you set in .env.
To access NuFi after installation completes, you need to configure DNS on the client PC. See the DNS Setup Guide to proceed.