Apheris Hub Kubernetes Deployment🔗
This guide covers deploying and configuring Apheris Hub on Kubernetes using Helm.
Prerequisites🔗
- A Kubernetes cluster in a recent version (>= 1.30)
- Helm CLI (>= v3)
- A PostgreSQL database
- A Storage Provisioner that supports
ReadWriteManyandReadWriteOnceaccessModes - An Ingress or Gateway Controller that enables network access to the Kubernetes cluster
- NVIDIA GPU support for GPU workloads on the Kubernetes cluster (required to run OpenFold3 and Boltz-2)
1. Create a Namespace for the Apheris Hub🔗
kubectl create namespace apheris-hub
2. Request the Apheris Hub API Key🔗
You need the Apheris Hub API Key to pull model images from the Apheris image registry and to authenticate with the Apheris-hosted Foldify MSA server.
You can skip this step if you host the Apheris model images in private repositories and do not use the Apheris hosted MSA server.
Request your Apheris Hub API Key from https://www.apheris.com/apherisfold or contact support@apheris.com and set it to your Helm values file:
apherisApiKey: "your-apheris-api-key"
hub:
msa:
enabled: true
3. Add a secret with a PostgreSQL DSN🔗
You can add a DSN for an existing PostgreSQL database with:
kubectl create secret generic hub-db-dsn --from-literal=dsn=<existing_dsn> \
--namespace=apheris-hub
We recommend using the managed database offering of your cloud provider in its PostgreSQL flavor, for instance Amazon RDS for PostgreSQL (AWS), Google Cloud SQL for PostgreSQL (GCP) or Azure Database for PostgreSQL (Microsoft Azure).
4. Create apheris-hub-values.yaml with values for the helm release🔗
Find the complete values reference at Helm Chart Values Reference.
The following are lightly annotated values with placeholders:
# refer to section `2.` for the apherisApiKey
apherisApiKey: "your-apheris-api-key"
hub:
postgresDsnSecretName: hub-db-dsn
ingress:
className: <ingress_class_name>
hostname: <ingress_hostname>
# TLS Termination at the ingress controller level.
tls:
enabled: <true|false>
# Name of a secret that contains the certificate material in the
# format documented in https://kubernetes.io/docs/concepts/services-networking/ingress/#tls
secretName: <tls_secret_name>
models:
persistence:
# The provisioner for this `storageClass` needs to
# support `ReadWriteMany` `accessMode`.
#
storageClass: <storage_class_that_supports_read_write_many>
# This is the space available for
# persisting prediction results.
#
# `50Gi` is the minimum size (and default)
# we recommend `500Gi` if you can make that happen.
#
size: 50Gi
# The `mock` model is the only default model that the chart
# deploys with the default values.
#
# You can enable deployment of other default models by setting
# `deploy.enabled=true`, so for instance
# `models.instances.boltz2.deploy.enabled=true` or
# `models.instances.openfold3.deploy.enabled=true`.
#
instances:
boltz2:
deploy:
enabled: <true|false>
mock:
deploy:
enabled: <true|false>
openfold3:
deploy:
enabled: <true|false>
Authentication and Identity Providers🔗
Set the hub.auth.* values to match your identity provider and frontend configuration. The Authentication Setup guide explains the requirements for Auth0, Microsoft Entra, and Dex and shows how those settings map back to Helm values.
Custom CA Certificates🔗
If your identity provider or external services use TLS certificates signed by a custom Certificate Authority, configure the Hub to trust those certificates. The file will be mounted to /etc/ssl/certs/custom-ca.crt in the Hub container and automatically trusted alongside system CAs.
Create the ConfigMap🔗
Create or update a ConfigMap with your CA certificate (safe to re-run):
kubectl create configmap custom-ca-certs \
--from-file=ca.crt=/path/to/your-ca.crt \
-n apheris-hub --dry-run=client -o yaml | kubectl apply -f -
Mount the certificate🔗
Add to your values file to mount the custom CA into the Hub container:
hub:
extraVolumes:
- name: custom-ca
configMap:
name: custom-ca-certs
extraVolumeMounts:
- name: custom-ca
mountPath: /etc/ssl/certs/custom-ca.crt
subPath: ca.crt
readOnly: true
Apply the Helm upgrade🔗
Re-run your helm upgrade command so the pod picks up the new mount.
Verify the ConfigMap🔗
The Hub Docker image is based on scratch, so kubectl exec and kubectl cp will not work but you can always validate that the CA data stored in the ConfigMap:
# Read the CA data from the ConfigMap into a local file
kubectl get configmap custom-ca-certs -n apheris-hub -o jsonpath='{.data.ca\.crt}' > /tmp/custom-ca.crt
# Inspect the certificate content
openssl x509 -in /tmp/custom-ca.crt -noout -subject -issuer
This confirms the CA content that will be mounted into the Hub pod.
Verify the live mount (optional)🔗
If your cluster allows ephemeral debug containers, you can examine the mounted file without changing the pod:
# Print container name(s) in the Hub pod (needed for --target)
kubectl get pod -n apheris-hub <hub-pod-name> -o jsonpath='{.spec.containers[*].name}'
# Start a debug container and read the mounted CA from the target container's root
kubectl debug -n apheris-hub -it pod/<hub-pod-name> --image=alpine:3.19 --target=<container-name> -- \
sh -c "cat /proc/1/root/etc/ssl/certs/custom-ca.crt" > /tmp/custom-ca.crt
# Inspect the certificate content copied from the pod
openssl x509 -in /tmp/custom-ca.crt -noout -subject -issuer
If debug containers are blocked by policy, rely on the ConfigMap check above and look for certificate-related errors in logs:
# Print container name(s) in the Hub pod (needed for -c)
kubectl get pod -n apheris-hub <hub-pod-name> -o jsonpath='{.spec.containers[*].name}'
# Print Hub container logs and filter for TLS/certificate errors
kubectl logs -n apheris-hub deployment/<hub-deployment-name> -c <container-name> | \
grep -i "certificate\|tls\|x509"
MSA Server Configuration🔗
The Hub supports three MSA (Multiple Sequence Alignment) server types with different architectures:
| Type | How it works | Timeout settings |
|---|---|---|
| Foldify (Apheris-hosted) | Streaming — results stream back in real-time | Not configurable via hub.msa.* |
| ColabFold (self-hosted) | Async polling — submit job, poll until complete, download results | Controlled by hub.msa.* |
| NVIDIA NIM ColabFold (self-hosted) | Synchronous request | Controlled by hub.msa.* |
The hub.msa.* timeout values only affect ColabFold and NVIDIA NIM ColabFold deployments:
hub:
msa:
enabled: true
# How often to check if the job is done (PENDING → RUNNING → COMPLETE)
pollInterval: "10s" # Lower = faster feedback, more API calls
# Per-request HTTP timeout for submit/status/download calls
requestTimeout: "10m" # Increase for slow networks or large downloads
Troubleshooting ColabFold:
- "Failed to check job status" errors → Increase
requestTimeout - Want faster progress updates → Decrease
pollInterval(minimum ~3s recommended)
5. Install the helm release🔗
helm install apheris-hub oci://quay.io/apheris/hub-chart \
--namespace=apheris-hub \
--values=apheris-hub-values.yaml \
--wait \
--timeout=15m
6. Access the Apheris Hub installation🔗
You can now access your Apheris Hub installation via the configured ingress.
For most setups, the external hostname will be the value you configured under
hub.ingress.hostname.
Please do not hesitate to contact Apheris via e-mail in case you encounter any problems.
Helm Chart Values Reference🔗
| Key | Type | Default | Description |
|---|---|---|---|
| apherisApiKey | string | nil |
Apheris API key for queries to Apheris hosted MSA servers and access to Apheris hosted container images |
| hub.affinity | object | {} |
Affinity rules |
| hub.auth | object | {"audience":"","browserUrl":"","clientId":"","domain":"","enabled":false,"extraScopes":"","issuer":"","providerType":""} |
Authentication configuration (OIDC/Auth0/ForgeRock) |
| hub.auth.providerType | string | "" |
Provider type (supported values: "auth0", "forgerock", or empty string for generic OIDC) |
| hub.enabled | bool | true |
Enable Hub deployment (set to false for models-only release) |
| hub.env | list | [] |
Additional environment variables |
| hub.extraVolumeMounts | list | [] |
Extra volume mounts (e.g., for custom CA certificates) |
| hub.extraVolumes | list | [] |
Extra volumes (e.g., for custom CA certificates) |
| hub.image.digest | string | nil |
Image digest (sha256). |
| hub.image.pullPolicy | string | "IfNotPresent" |
Image pull policy |
| hub.image.repository | string | "quay.io/apheris/hub" |
Container image repository |
| hub.image.tag | string | nil |
Overrides the image tag whose default is the chart appVersion |
| hub.imagePullSecrets | list | [] |
Image pull secrets for private registries |
| hub.ingress | object | {"annotations":{},"className":"","enabled":true,"existingGatewayName":"","gatewayNamespace":"","hostname":"","ingressPath":"/","tls":{"enabled":false,"secretName":""},"type":"ingress"} |
Ingress configuration (common for both Gateway API and Ingress resources) |
| hub.ingress.annotations | object | {} |
Additional annotations |
| hub.ingress.className | string | "" |
Ingress/Gateway class name |
| hub.ingress.enabled | bool | true |
Enable ingress (Gateway API or Ingress resource) |
| hub.ingress.existingGatewayName | string | "" |
Existing gateway name (if not set, a new gateway will be created) |
| hub.ingress.gatewayNamespace | string | "" |
Gateway namespace (if different from release namespace) |
| hub.ingress.hostname | string | "" |
Hostname for ingress |
| hub.ingress.ingressPath | string | "/" |
Ingress path |
| hub.ingress.tls | object | {"enabled":false,"secretName":""} |
TLS configuration |
| hub.ingress.tls.enabled | bool | false |
Enable TLS |
| hub.ingress.tls.secretName | string | "" |
TLS certificate secret name |
| hub.ingress.type | string | "ingress" |
Networking type (gateway, ingress) |
| hub.msa | object | {"enabled":false,"pollInterval":"5s","requestTimeout":"5m"} |
MSA server configuration |
| hub.msa.enabled | bool | false |
Enable MSA server configuration |
| hub.msa.pollInterval | string | "5s" |
How frequently the application checks the status of a submitted MSA job on the ColabFold server (e.g., "5s", "10s"). |
| hub.msa.requestTimeout | string | "5m" |
The timeout for each individual HTTP request made to the ColabFold server (e.g., "5m", "10m"). |
| hub.nodeSelector | object | {} |
Node selector |
| hub.persistence | object | {"accessMode":"ReadWriteOnce","annotations":{},"enabled":true,"existingVolumeName":null,"size":"5Gi","storageClass":""} |
Persistence configuration |
| hub.persistence.accessMode | string | "ReadWriteOnce" |
Access mode for state PVC |
| hub.persistence.annotations | object | {} |
Annotations for state PVC |
| hub.persistence.enabled | bool | true |
Enable state persistence |
| hub.persistence.existingVolumeName | string | nil |
Existing PersistentVolume to bind to. If null, a new one will be dynamically created. |
| hub.persistence.size | string | "5Gi" |
Size of state PVC |
| hub.persistence.storageClass | string | "" |
Storage class for state PVC |
| hub.podAnnotations | object | {} |
Pod annotations |
| hub.podLabels | object | {} |
Pod labels |
| hub.podSecurityContext | object | {"fsGroup":65534,"runAsGroup":65534,"runAsNonRoot":true,"runAsUser":65534,"seccompProfile":{"type":"RuntimeDefault"}} |
Pod security context |
| hub.postgresDsnSecretName | string | nil |
Name of a kubernetes secret containing a postgres DSN, needs a key dsn |
| hub.replicaCount | int | 1 |
Number of replicas for the Hub deployment |
| hub.securityContext | object | {"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"readOnlyRootFilesystem":true,"runAsGroup":65534,"runAsNonRoot":true,"runAsUser":65534} |
Container security context |
| hub.service | object | {"annotations":{},"nodePort":null,"port":8080,"type":"ClusterIP"} |
Service configuration |
| hub.service.annotations | object | {} |
Service annotations |
| hub.service.nodePort | string | nil |
NodePort (only used when type is NodePort) |
| hub.service.port | int | 8080 |
Service port |
| hub.service.type | string | "ClusterIP" |
Service type |
| hub.terminationGracePeriodSeconds | int | 30 |
Termination grace period in seconds |
| hub.tolerations | list | [] |
Tolerations |
| hub.websockets.enabled | bool | true |
|
| labels | object | {} |
Additional labels for every object created by the chart |
| models.imagePullRegistry | string | "quay.io/apheris" |
Registry for image pulls |
| models.imagePullSecrets | list | [] |
Secrets for image pulls |
| models.instances.boltz2 | object | {"deploy":{"affinity":{},"enabled":false,"env":[],"extraVolumeMounts":[],"extraVolumes":[],"image":"quay.io/apheris/hub-apps:0.37.1-boltz2-by-file","nodeSelector":{},"podSecurityContext":{"fsGroup":65534,"runAsGroup":65534,"runAsNonRoot":true,"runAsUser":65534,"seccompProfile":{"type":"RuntimeDefault"}},"port":8000,"resources":{"limits":{"cpu":"8","memory":"64Gi","nvidia.com/gpu":1},"requests":{"cpu":"8","memory":"64Gi","nvidia.com/gpu":1}},"securityContext":{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"readOnlyRootFilesystem":true,"runAsGroup":65534,"runAsNonRoot":true,"runAsUser":65534},"shmSize":"16Gi","tolerations":[{"effect":"NoSchedule","key":"nvidia.com/gpu","operator":"Equal","value":"true"}]},"id":"boltz2","model":"boltz2"} |
boltz2 requires a GPU with 40GB of memory, not enabled by default |
| models.instances.boltz2.deploy.enabled | bool | false |
enable boltz2 with enabled: true |
| models.instances.boltz2.deploy.env | list | [] |
Additional environment variables for custom weights configuration |
| models.instances.boltz2.deploy.extraVolumeMounts | list | [] |
Extra volume mounts for custom weights |
| models.instances.boltz2.deploy.extraVolumes | list | [] |
Extra volumes for custom weights |
| models.instances.mock | object | {"deploy":{"affinity":{},"enabled":true,"env":[],"extraVolumeMounts":[],"extraVolumes":[],"image":"quay.io/apheris/hub-apps:0.37.1-mock-by-file","nodeSelector":{},"podSecurityContext":{"fsGroup":65534,"runAsGroup":65534,"runAsNonRoot":true,"runAsUser":65534,"seccompProfile":{"type":"RuntimeDefault"}},"port":8000,"securityContext":{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"readOnlyRootFilesystem":true,"runAsGroup":65534,"runAsNonRoot":true,"runAsUser":65534}},"id":"mock","model":"mock"} |
lightweight mock model that does not require a GPU, enabled by default |
| models.instances.mock.deploy.env | list | [] |
Additional environment variables for custom weights configuration |
| models.instances.mock.deploy.extraVolumeMounts | list | [] |
Extra volume mounts for custom weights |
| models.instances.mock.deploy.extraVolumes | list | [] |
Extra volumes for custom weights |
| models.instances.openfold3 | object | {"deploy":{"affinity":{},"enabled":false,"env":[],"extraVolumeMounts":[],"extraVolumes":[],"image":"quay.io/apheris/hub-apps:0.37.1-openfold3-by-file","nodeSelector":{},"podSecurityContext":{"fsGroup":65534,"runAsGroup":65534,"runAsNonRoot":true,"runAsUser":65534,"seccompProfile":{"type":"RuntimeDefault"}},"port":8000,"resources":{"limits":{"cpu":"8","memory":"64Gi","nvidia.com/gpu":1},"requests":{"cpu":"8","memory":"64Gi","nvidia.com/gpu":1}},"securityContext":{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"readOnlyRootFilesystem":true,"runAsGroup":65534,"runAsNonRoot":true,"runAsUser":65534},"shmSize":"16Gi","tolerations":[{"effect":"NoSchedule","key":"nvidia.com/gpu","operator":"Equal","value":"true"}]},"id":"openfold3","model":"openfold3"} |
openfold3 requires a GPU with 40GB of memory, not enabled by default |
| models.instances.openfold3.deploy.enabled | bool | false |
enable openfold3 with enabled: true |
| models.instances.openfold3.deploy.env | list | [] |
Additional environment variables for custom weights configuration |
| models.instances.openfold3.deploy.extraVolumeMounts | list | [] |
Extra volume mounts for custom weights |
| models.instances.openfold3.deploy.extraVolumes | list | [] |
Extra volumes for custom weights |
| models.persistence | object | {"accessMode":"ReadWriteMany","annotations":{},"enabled":true,"existingVolumeName":null,"size":"50Gi","storageClass":""} |
Artifacts persistence (input/output) |
| models.persistence.accessMode | string | "ReadWriteMany" |
Access mode for artifacts PVC |
| models.persistence.annotations | object | {} |
Annotations for artifacts PVC |
| models.persistence.enabled | bool | true |
Enable artifacts persistence via PVC |
| models.persistence.existingVolumeName | string | nil |
Existing PersistentVolume to bind to. If null, a new one will be dynamically created. |
| models.persistence.size | string | "50Gi" |
Size of artifacts PVC |
| models.persistence.storageClass | string | "" |
Storage class for artifacts PVC |