Skip to content
Foyre Foyre

Installation

Install Foyre with Helm

Deploy Foyre into a Kubernetes cluster using Helm with SQLite, bundled Postgres, or external Postgres.

Difficulty
Beginner
Time
10-20 minutes
Category
Installation
Tags
Kubernetes, Helm, Postgres

Foyre can be installed into a Kubernetes cluster using Helm. This guide walks through the available installation paths, including the default SQLite-backed install, a bundled Postgres install, and external Postgres configurations for more production-style environments.

The default installation is useful for demos and evaluation. For shared team environments or production-style deployments, use Postgres.

Note

SQLite is useful for quick demos and evaluation. Postgres is recommended for shared, long-running, or production-style deployments.

Prerequisites

Before installing Foyre, you need:

  • A running Kubernetes cluster
  • kubectl configured to access the cluster
  • Helm installed
  • Permission to create namespaces, deployments, services, secrets, jobs, and persistent volume claims
  • A default StorageClass if using SQLite persistence or bundled Postgres persistence

If you do not already have a Kubernetes cluster, you can create a simple single-node K3s cluster for testing:

shell 
curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=<VERSION> sh -s - server --cluster-init

Replace <VERSION> with the K3s version you want to install.

Verify the cluster:

shell 
kubectl get nodes

Expected result: at least one node should be listed with status Ready.

Add the Foyre Helm repository

Add the Foyre Helm repository:

shell 
helm repo add foyre https://foyre.github.io/foyre/
helm repo update

This adds the Foyre Helm chart repository to your local Helm client and refreshes the chart index.

Installation options

Foyre supports several database-backed installation modes:

  1. SQLite, the default lightweight backend
  2. Bundled Postgres, deployed with the Helm chart
  3. External Postgres, configured directly through Helm values
  4. External Postgres, configured through an existing Kubernetes Secret containing DATABASE_URL

Warning

When using SQLite, run only one Foyre replica. Multiple replicas writing to the same SQLite database file can corrupt the database. Use Postgres before scaling beyond one replica.

Option 1: Install Foyre with SQLite

The SQLite install is the fastest way to try Foyre on a Kubernetes cluster. The chart creates a persistent volume claim and stores the SQLite database at /data/foyre.db inside the Foyre pod.

shell 
helm install foyre foyre/foyre \
  --namespace foyre \
  --create-namespace \
  --set seed.admin.password='change-me' \
  --set postgresql.enabled=false \
  --wait

This installs Foyre into the foyre namespace and creates the initial admin user.

Username: admin

Password: change-me

Warning

Change the initial admin password after logging in. For any shared environment, set a stronger password before installation.

Note

Use SQLite only for demos, local testing, or lightweight evaluation environments.

Option 2: Install Foyre with bundled Postgres

For a more production-like evaluation, Foyre can deploy Postgres alongside the application using the bundled Postgres chart dependency.

shell 
helm install foyre foyre/foyre \
  --namespace foyre \
  --create-namespace \
  --set seed.admin.password='change-me' \
  --set postgresql.enabled=true \
  --set postgresql.auth.password='replace-with-strong-postgres-password' \
  --wait

When postgresql.enabled=true, the chart deploys Postgres and automatically configures Foyre to use it. No additional database.* settings are required for this mode.

Warning

Do not use weak database passwords in shared or production environments.

Note

Bundled Postgres is useful when you want to test Foyre with Postgres but do not have an external database available.

Option 3: Install Foyre with an external Postgres database

Use this option when your organization already provides Postgres, such as a managed cloud database, internal platform database, or separately operated Postgres cluster.

shell 
helm install foyre foyre/foyre \
  --namespace foyre \
  --create-namespace \
  --set seed.admin.password='change-me' \
  --set postgresql.enabled=false \
  --set database.postgres.host='postgres.example.com' \
  --set database.postgres.port=5432 \
  --set database.postgres.database='foyre' \
  --set database.postgres.user='foyre' \
  --set database.postgres.password='replace-with-strong-database-password' \
  --set database.postgres.sslmode='require' \
  --wait

Setting database.postgres.host tells the chart to use an external Postgres database. When this value is set, the chart does not deploy bundled Postgres.

The external database must:

  • Already exist
  • Be reachable from the Foyre pod
  • Allow connections from the Kubernetes cluster
  • Have a user with permission to connect to the configured database
  • Match the SSL mode configured in Helm values

Example database URL format:

postgresql+psycopg://foyre:<password>@postgres.example.com:5432/foyre

If SSL is required:

postgresql+psycopg://foyre:<password>@postgres.example.com:5432/foyre?sslmode=require

Option 4: Install Foyre with an existing DATABASE_URL Secret

For production-style deployments, the recommended approach is to provide the database connection string through an existing Kubernetes Secret. This keeps database credentials out of Helm command history and allows the Secret to be managed by tools such as External Secrets, Sealed Secrets, Vault, or your platform team.

First create the namespace:

shell 
kubectl create namespace foyre

Create the database Secret:

shell 
kubectl create secret generic foyre-database-url \
  --namespace foyre \
  --from-literal=DATABASE_URL='postgresql+psycopg://foyre:replace-with-password@postgres.example.com:5432/foyre?sslmode=require'

Then install Foyre:

shell 
helm install foyre foyre/foyre \
  --namespace foyre \
  --set seed.admin.password='change-me' \
  --set postgresql.enabled=false \
  --set database.existingSecret='foyre-database-url' \
  --set database.existingSecretKey='DATABASE_URL' \
  --wait

When database.existingSecret is set, Foyre reads the database connection string from the Secret key specified by database.existingSecretKey. The chart does not create a SQLite PVC and does not deploy bundled Postgres.

Recommended

Use an existing DATABASE_URL Secret for managed Postgres and enterprise environments where credentials should not be passed directly through Helm values.

Database selection behavior

The Foyre Helm chart selects the database backend based on the values you provide. If more than one option is set, the chart uses the first matching option in the precedence order below.

Precedence Configuration Backend used
1 database.existingSecret is set Existing Secret containing DATABASE_URL
2 database.url is set Explicit database URL
3 postgresql.enabled=true Bundled Postgres
4 database.postgres.host is set External Postgres
5 None of the above SQLite

Note

For most users, use SQLite for quick demos, bundled Postgres for team evaluation, and external Postgres or an existing DATABASE_URL Secret for production-style deployments.

Access the Foyre UI

Check the pods:

shell 
kubectl get pods -n foyre

Check the service:

shell 
kubectl get svc -n foyre

For local access, use port forwarding:

shell 
kubectl port-forward svc/foyre 8080:80 -n foyre

Then open:

http://localhost:8080

Login using:

Username: admin

Password: change-me

Note

If you used a different value for seed.admin.password, use that password instead.

Change the initial admin password

After logging in for the first time, change the initial admin password. For any shared environment, do not leave the admin password set to change-me.

Use the account settings or admin user management screen to update the initial admin password after installation.

Verify the installation

shell 
kubectl get pods -n foyre
kubectl get pvc -n foyre
kubectl logs -n foyre deploy/foyre

Expected results:

  • The Foyre pod should be running.
  • If SQLite is used, a persistent volume claim should exist for the application data.
  • If bundled Postgres is used, Postgres pods and persistent volume claims should also be present.
  • Foyre logs should not show database connection errors.

If the deployment name in the chart is not exactly foyre, adjust the logs command to match the actual deployment name.

Upgrade Foyre

To upgrade Foyre after a new chart or application version is released:

shell 
helm repo update

helm upgrade foyre foyre/foyre \
  --namespace foyre \
  --reuse-values \
  --wait

Warning

Before upgrading production or long-running environments, back up the database.

Uninstall Foyre

To uninstall Foyre:

shell 
helm uninstall foyre -n foyre

Depending on your storage class and Helm values, persistent volume claims may remain after uninstalling. Review PVCs before deleting data:

shell 
kubectl get pvc -n foyre

If you intentionally want to remove all Foyre resources and data in the namespace:

shell 
kubectl delete namespace foyre

Danger

Deleting the namespace can permanently remove Foyre data if the persistent volumes are deleted by the storage backend.

Troubleshooting

Pods are stuck Pending

Check whether your cluster has a default StorageClass:

shell 
kubectl get storageclass
kubectl describe pod -n foyre

Common causes:

  • No default StorageClass
  • PVC cannot be bound
  • Not enough cluster resources
  • Image pull issues

Cannot log in

Confirm the admin password you set during installation:

shell 
helm get values foyre -n foyre

If the chart uses a seed job, also check the seed job logs. Use the actual job name from the cluster:

shell 
kubectl get jobs -n foyre
kubectl logs -n foyre job/<seed-job-name>

Database connection errors

Check the Foyre logs:

shell 
kubectl logs -n foyre deploy/foyre

For external Postgres, confirm:

  • The hostname is reachable from inside the cluster
  • The database exists
  • The username and password are correct
  • The SSL mode matches the database requirement
  • Network policies, firewalls, or security groups are not blocking access

SQLite warning

If using SQLite, keep:

replicaCount=1

Do not increase replicas unless Foyre is configured to use Postgres.

Next steps

Submit your first AI workload request

Continue the core tutorial path from installation into intake.

Create a validation sandbox

Provision an isolated vcluster for hands-on review.

Review and approve an AI request

Move from submitted request to review decision.

Troubleshoot validation environments

Return to the tutorial roadmap for upcoming validation guides.