Install for evaluation
This tutorial installs Foundation4 on a single Kubernetes node for evaluation, with PostgreSQL, NATS JetStream, Valkey and Prometheus installed from the bundled charts. At the end of the tutorial, the API answers on localhost and the master key is confirmed. Operators and integrators who want a working deployment to explore Foundation4 start here. Production installations follow Install on Kubernetes.
Evaluation profile
The evaluation profile trades durability for a short installation path:
- Bundled database. PostgreSQL runs in the cluster from the bundled chart as a single pod and stores data on one 8 GiB volume claim. Deleting the volume claim deletes every pipeline and document. A new database also has a new system ID, so the license no longer matches and a new license is required.
- Single node. Every component runs on one node. The charts set no resource requests or limits.
- License. Foundation4 requires a license for every installation, including evaluation. The license is bound to the system ID of the database, which the license check of the first installation reports. The installation therefore runs the application release twice: once to obtain the system ID and once with the license.
Requirements
| Requirement | Details |
|---|---|
| Kubernetes | One node, such as a single-node k3s cluster, with Kubernetes 1.31 or later. Model and package images, which need image volume support, are not used in this tutorial. |
| Storage | A default StorageClass. The bundled charts request 46 GiB in 5 volume claims: 3 claims of 10 GiB for NATS JetStream, 8 GiB for Prometheus and 8 GiB for PostgreSQL. |
| Tools | kubectl, Helm 3, openssl, uuidgen and curl. kubectl kustomize builds the secret. |
| Installation files | The files supplied by the Foundation4 provider: the charts/foundation4ai-core and charts/foundation4ai charts, kustomization.yaml and foundation4ai.secrets.env.template. |
| Images | The registry path and release tag of the API server, gRPC service and dashboard images, and pull credentials if the registry requires them. PostgreSQL, NATS, Valkey and Prometheus images come from public registries. |
Run every command in this tutorial from the directory that holds the installation files.
Evaluation values
Both releases read one values file. Create evaluation.values.yaml with the following content, replacing each value in angle brackets:
global:
serverImageTag: "<api server image tag>"
grpcImageTag: "<grpc service image tag>"
dashboardImageTag: "<dashboard image tag>"
postgres:
enabled: true
api-server:
image:
repository: <registry>/foundation4ai-api
repositoryGrpc: <registry>/foundation4ai-grpc
replicaCount:
worker: 1
dashboard:
image:
repository: <registry>/foundation4ai-dashboard
The values file sets the following:
- Image tags. The three tags are required. The charts provide no default tag.
- Bundled PostgreSQL.
postgres.enabled: trueinstalls PostgreSQL with the extensionsvector,vchord,pg_tokenizerandvchord_bm25, with data on an 8 GiB volume claim. The default,false, expects an external database inPOSTGRES_URL, and the core release stops with an error whenPOSTGRES_URLis empty. - Workers. One worker replica instead of the default 3, to fit a small node.
- Pull credentials. When the registry requires credentials, create an image pull secret in the
foundation4ainamespace after step 1 and add the secret underglobal.imagePullSecretsas a list of secret names. This list applies to the Foundation4 pods of the application release; the core release pulls public images. Charts, images and installation bundle covers private mirrors of the core images.
Do not copy settings from the sample values file supplied with the charts. The sample file points model and package images at the provider's registry, names the provider's pull secret and leaves the bundled PostgreSQL disabled.
Installation
1. Namespace
The secret and both releases of this tutorial are in the namespace foundation4ai, and every command names the namespace.
kubectl create namespace foundation4ai
Expected result: namespace/foundation4ai created.
2. Secrets
Copy the template:
cp foundation4ai.secrets.env.template foundation4ai.secrets.env
Generate the values. openssl rand -hex 24 produces a password or secret, uuidgen produces the master key identifier and the openssl rand -base64 32 command produces the application secret:
openssl rand -hex 24
uuidgen
openssl rand -base64 32 | tr '+/' '-_'
Edit foundation4ai.secrets.env and set the following keys. Leave POSTGRES_URL, REDIS_URL and NATS_URL empty; the core release builds the three connection URLs.
| Key | Value |
|---|---|
POSTGRES_DATABASE | foundation4ai |
POSTGRES_USER | foundation4ai |
POSTGRES_SUPERUSER_PASSWORD | A new openssl rand -hex 24 value |
POSTGRES_PASSWORD | A new openssl rand -hex 24 value |
REDIS_PASSWORD | A new openssl rand -hex 24 value |
NATS_PASSWORD | A new openssl rand -hex 24 value: the password with which Foundation4 signs in to NATS JetStream |
FOUNDATION4AI_APP_SECRET | The openssl rand -base64 32 value: the application secret, which encrypts the stored API keys of LLMs |
FOUNDATION4AI_APP_MASTER_KEY | The uuidgen value: the identifier of the master key |
FOUNDATION4AI_APP_MASTER_SECRET | A new openssl rand -hex 24 value: the secret of the master key |
FOUNDATION4AI_APP_LICENSE | pending until step 5 |
The following rules apply to these values:
- Passwords. The core release percent-encodes the passwords in the connection URLs that the core release builds, so the passwords may contain any character.
- Master key. Record the master key identifier and secret, which sign in to the API and the dashboard. Secrets and keys describes a change of the master key.
- Application secret. Record the application secret. The stored API keys of LLMs cannot be decrypted without the application secret, and a new application secret requires the API key of each LLM to be set again.
Create the Kubernetes secret from the file:
kubectl kustomize . | kubectl apply -n foundation4ai -f -
Expected result: secret/foundation4ai-secrets created.
3. Core release
The core release installs PostgreSQL, NATS JetStream, Valkey and Prometheus.
helm upgrade --install foundation4ai-core ./charts/foundation4ai-core \
-n foundation4ai -f evaluation.values.yaml --wait --timeout 10m
kubectl get pods,pvc -n foundation4ai
Expected result: Helm reports STATUS: deployed. The PostgreSQL, Valkey, Prometheus server and NATS utility pods and 3 NATS pods are Running, and 5 volume claims are Bound.
4. System ID
The first application install runs the database migration, reports the system ID and then stops at the license check, because the license is still pending. The license check fails at once after the report, so Helm stops the install with an error. This failure is expected.
helm upgrade --install foundation4ai ./charts/foundation4ai \
-n foundation4ai -f evaluation.values.yaml --timeout 10m
kubectl logs -n foundation4ai job/foundation4ai-api-server-license-check
Expected result: Helm reports that the pre-install hook failed with BackoffLimitExceeded. The log of the license check Job contains the system ID:
SystemID: <system ID>
Checking for a valid license... Invalid
Error: "License check failed: Invalid"
5. License
Send the system ID to the Foundation4 provider and receive the license. Replace pending with the license in foundation4ai.secrets.env, then update the secret:
kubectl kustomize . | kubectl apply -n foundation4ai -f -
Expected result: secret/foundation4ai-secrets configured. The application release reads the license from this secret, so the core release needs no upgrade.
6. Application release
Remove the failed release and install the application release again:
helm uninstall foundation4ai -n foundation4ai
helm install foundation4ai ./charts/foundation4ai \
-n foundation4ai -f evaluation.values.yaml --wait --timeout 10m
kubectl get jobs,pods -n foundation4ai
Expected result: Helm reports STATUS: deployed, which confirms that the database migration, license check and master key Jobs completed. Helm then deletes the Jobs, so no Job is listed. The API server pod shows 2/2 containers ready, the worker pod 2/2 and the dashboard pod 1/1.
The API server pod and the worker pod each run two containers: the Foundation4 process and the gRPC service, which hosts the Python text splitters and embedding providers.
7. API access
Forward a local port to the API server service in a separate terminal:
kubectl port-forward -n foundation4ai svc/foundation4ai-api-server 8080:80
Set the shell variables that the tutorials use, with the master key identifier and secret from step 2, and call the API:
export FOUNDATION4_URL=http://localhost:8080
export FOUNDATION4_API_KEY=<master key identifier>
export FOUNDATION4_API_SECRET=<master key secret>
curl -X POST "$FOUNDATION4_URL/login" \
-H "x-api-key: $FOUNDATION4_API_KEY" \
-H "x-api-key-secret: $FOUNDATION4_API_SECRET"
Expected result: status 201 and a body whose message is OK, whose key is Master Admin Key and whose admin is true, with the permissions of the master key. The installation is complete. Authenticate creates a key for the remaining tutorials.
Dashboard access
The dashboard is optional. The dashboard calls the API on the same host name, so the dashboard is reached through an ingress rather than a port forward to the dashboard alone; API and dashboard access describes a local reverse proxy as an alternative. The chart's ingress sends /dashboard to the dashboard and every other path to the API server. k3s includes the Traefik ingress controller; on other clusters, className names the installed controller.
Add the following to evaluation.values.yaml:
ingress:
enabled: true
className: traefik
hosts:
- host: foundation4.localhost
Apply the change:
helm upgrade foundation4ai ./charts/foundation4ai \
-n foundation4ai -f evaluation.values.yaml --wait --timeout 10m
Expected result: http://foundation4.localhost/dashboard/ shows the dashboard sign-in page. The dashboard signs in with the master key identifier and secret.
Troubleshooting
Pods or volume claims in pending status
- Symptoms. After step 3, PostgreSQL, NATS or Prometheus pods remain
Pending, andkubectl get pvc -n foundation4aishows claims inPendingstatus. - Diagnosis.
kubectl get storageclasslists no class marked(default), orkubectl describe pvc -n foundation4aireports that no storage class is set. - Cause. The bundled charts request volumes without naming a storage class, so the cluster needs a default StorageClass.
- Resolution. Mark an existing StorageClass as the default, or install a local volume provisioner, then run step 3 again.
- Actions to avoid. Deleting the NATS volume claims after documents have been added, which deletes queued documents, or the PostgreSQL volume claim, which deletes the database.
Image pull errors
- Symptoms. Hook Job pods or application pods report
ErrImagePullorImagePullBackOff, and the install stops at the timeout. A missing tag stops Helm before any pod starts, with an error such asset global.serverImageTag (or api-server.image.tag) to the API server image tag. - Diagnosis.
kubectl describe pod -n foundation4ai <pod name>shows the image reference and the registry response. - Cause. An image repository or tag in
evaluation.values.yamlis missing or wrong, or the registry requires credentials that the values file does not reference. - Resolution. Correct the repository and tag values, create the image pull secret and list the secret under
global.imagePullSecrets, then repeat the failed step. - Actions to avoid. Omitting the tags in the expectation of a default. The charts provide none.
Core release stopping at the database URL
- Symptoms. Step 3 stops with
Set POSTGRES_URL in the foundation4ai-secrets Secret: postgres.enabled is false, so the API needs the URL of your PostgreSQL (or set postgres.enabled: true for the bundled one). - Diagnosis.
grep -n -A1 '^postgres:' evaluation.values.yamlshows whether the values file setsenabled: trueunderpostgres. - Cause. Without
postgres.enabled: true, the core release expects an external database inPOSTGRES_URL. - Resolution. Set
postgres.enabled: trueinevaluation.values.yaml, pass the file with-f, and run step 3 again. - Actions to avoid. Setting
POSTGRES_URLto a database that does not meet the PostgreSQL requirements.
Database migration failure
- Symptoms. Step 4 stops at the migration Job, and the log of
job/foundation4ai-api-server-db-migrationshowsFailed connecting to database:followed by the cause. - Diagnosis.
kubectl get pods -n foundation4aishows whether the PostgreSQL podfoundation4ai-core-postgres-0isRunningand ready.kubectl logs -n foundation4ai foundation4ai-core-postgres-0shows the database log. - Cause. The PostgreSQL pod is not ready, or the database rejects the user or password in the connection URL.
- Resolution. Wait until the PostgreSQL pod is ready, correct the cause that the database log names, and repeat step 4.
- Actions to avoid. Deleting the PostgreSQL volume claim to start over. The claim holds the database, so a new claim starts with an empty database and a new system ID.
API server or worker containers restarting
- Symptoms. After step 6, the
serverorworkercontainer restarts repeatedly. - Diagnosis.
kubectl logs -n foundation4ai deploy/foundation4ai-api-server -c server --previousandkubectl logs -n foundation4ai deploy/foundation4ai-api-server-worker -c worker --previousshow the error.License check failed:points to the license.Failed to initialize with the master key:in the server log, orFailed to initialize Foundation4.ai:in the worker log, points to the master key.Failed to connect to Foundation4.ai's services:points to the database, NATS JetStream or Valkey, which the process retries for about 4.5 minutes before the process stops. - Cause. The license does not match the database, the master secret in the secret differs from the master key that the master key Job created, or a core release pod is not ready.
- Resolution. Request a license for the current system ID, upgrade the application release so that the master key Job applies the master key of the secret, or wait for the core release pods of step 3.
- Actions to avoid. Deleting the PostgreSQL volume claim to start over, which deletes the database and changes the system ID.
Removal
Remove the evaluation installation and every stored object:
helm uninstall foundation4ai -n foundation4ai
helm uninstall foundation4ai-core -n foundation4ai
kubectl delete namespace foundation4ai
Expected result: both releases are uninstalled and namespace "foundation4ai" deleted. The namespace deletion also removes the volume claims, including the database, and the secrets.