Skip to content

Kubernetes (Helm) ​

Requirements ​

  • A Kubernetes cluster and Helm 3
  • The ingress-nginx Ingress controller; the annotations in the example values.yaml are specific to it
  • PostgreSQL 15 (14 is supported) with the application and ai-core (flip_ai_core) databases, Valkey 9 (standalone mode) and S3-compatible storage, deployed separately and reachable from the cluster
  • Two DNS names and TLS certificates: the application (example.flip-chart.ru) and the MCP server (mcp.example.flip-chart.ru)
  • SMTP server credentials
  • Outbound HTTPS access from the cluster to ai.flip-chart.ru for AI features (ai-core)

Chart components ​

SubchartImagePortIngress
backendflip-backend9000/app/api, /app/api/v1/ws, /app/api/v1/flip/backup/upload, / redirect
ai-coreflip-ai-core9100—
file-handlersflip-file-handlers8080—
frontendflip-frontend80/app, /app/s3/ → S3 storage
mcp-serverflip-mcp-server8090mcp.example.flip-chart.ru/

Helm chart ​

bash
helm registry login cr.yandex --username json_key --password-stdin < credentials/authorized_key.json
helm show chart oci://cr.yandex/crpbj8irels1kqult74e/onpremise/flip-chart --version 1.2.0
helm show values oci://cr.yandex/crpbj8irels1kqult74e/onpremise/flip-chart --version 1.2.0 > values.yaml

The example values.yaml is the same as the helm show values output.

Delivery files ​

├── credentials
│   ├── authorized_key.json      — access key for the image and Helm chart registry
│   └── License_key.txt          — application license key
└── deploy
    ├── docker-compose
    │   └── config               — example service configuration files
    └── kubernetes
        └── values.yaml          — example values

Installation steps ​

1. Namespace and registry access ​

bash
kubectl create namespace flip
kubectl -n flip create secret docker-registry registrykey \
  --docker-server=cr.yandex \
  --docker-username=json_key \
  --docker-password="$(cat credentials/authorized_key.json)"

2. TLS certificates ​

bash
kubectl -n flip create secret tls flip-tls     --cert=crt.pem     --key=key.pem
kubectl -n flip create secret tls flip-mcp-tls --cert=mcp-crt.pem --key=mcp-key.pem

If you use cert-manager, specify its annotations in the ingress section of the corresponding subcharts; the secret names stay the same.

3. Configuration files ​

Fill in the configuration files as described in backend, ai-core, file-handlers, frontend and mcp-server.

In-cluster addresses

The example configurations are written for docker-compose. In Kubernetes, services are addressed by the chart's Service names:

Fielddocker-composeKubernetes
backend → FileHandlerServiceConfig.Addresshttp://flip-file-handlers:8080/apihttp://file-handlers.flip.svc.cluster.local:8080/api
backend → AI.LocalCore.BaseURLhttp://flip-ai-core:9100http://ai-core.flip.svc.cluster.local:9100
mcp-server → flipApi.internalUrlhttp://flip-backend:9000http://backend.flip.svc.cluster.local:9000

flip in the address is the installation namespace (the release namespace -n or global.namespace). The PostgreSQL, Valkey and S3 addresses are those of the external services.

Create the configuration secrets (the secret and key names must match volumes/volumeMounts in values):

bash
kubectl -n flip create secret generic backend-config       --from-file=config.yaml=config/backend/config.yaml
kubectl -n flip create secret generic file-handlers-config --from-file=config.yaml=config/file-handlers/config.yaml
kubectl -n flip create secret generic frontend-config       --from-file=config.js=config/frontend/config.js
kubectl -n flip create secret generic mcp-server-config    --from-file=config.yaml=config/mcp-server/config.yaml
kubectl -n flip create secret generic ai-core-config       --from-file=config.yaml=config/ai-core/config.yaml \
  --from-literal=POSTGRES_DSN='postgres://flip:secret-passwd@postgres.example.ru:5432/flip_ai_core?sslmode=require'

Create the flip_ai_core database on the PostgreSQL server in advance: CREATE DATABASE flip_ai_core OWNER flip;. The POSTGRES_DSN key of the ai-core-config secret is its connection string (format).

Updating the configuration

bash
kubectl -n flip create secret generic backend-config --from-file=config.yaml=config/backend/config.yaml \
  --dry-run=client -o yaml | kubectl apply -f -

4. S3 storage ​

  • Create a bucket and allow anonymous read access to its objects.
  • Upload the media assets: unpack deploy/sources/s3-assets.tar and upload its contents to the root of the bucket (the app, flip-shape-sets, flip-templates, gifs, logo and spaces directories).
  • In values.yaml, set the storage host in frontend.service.s3.storageurl. The chart creates a Service of type ExternalName and an Ingress for /app/s3/(.*) that proxies requests to the storage through the application domain.

5. values.yaml ​

Edit values.yaml: domains (tlshosts, permanent-redirect), TLS secret names, the S3 host, the image version (image.tag, the same for all components) and resources. The parameters are described in values.yaml parameters.

6. Installation ​

bash
helm registry login cr.yandex --username json_key --password-stdin < credentials/authorized_key.json
helm install flip oci://cr.yandex/crpbj8irels1kqult74e/onpremise/flip-chart --version 1.2.0 -f values.yaml -n flip

7. Verification ​

bash
kubectl -n flip get pods
kubectl -n flip get ingress

All pods must be in the Running state. The application is available at https://example.flip-chart.ru/app. Then proceed to the first launch.

values.yaml parameters ​

global ​

ParameterDescription
global.namespaceInstallation namespace. An empty value means the release namespace (helm -n).
global.imagePullSecretsList of image registry access secrets.

Common subchart parameters ​

The same for backend, ai-core, file-handlers, frontend and mcp-server.

ParameterDescription
enabledEnables the component.
replicaCountNumber of replicas.
image.repository, image.tag, image.pullPolicyComponent image.
annotationsDeployment and pod annotations.
affinity, tolerations, nodeSelectorPod placement.
strategyDeployment update strategy (RollingUpdate, Recreate).
containers.containerPortContainer ports.
containers.readinessProbe, containers.livenessProbe, containers.startupProbeContainer probes. The example uses tcpSocket on the service port (the backend readiness probe is httpGet /metrics; ai-core uses httpGet /readyz and /healthz on port 9102). When changing the probe type, set the previous type to null, for example tcpSocket: null.
env, envFromEnvironment variables. For ai-core: POSTGRES_DSN from the ai-core-config secret.
service.enabled, service.type, service.portsKubernetes Service.
resourcesCPU/memory requests and limits.
volumes, volumeMountsMounting of the configuration secret. The path inside the container is fixed (see configuration files).
securityContextContainer security context.
podSecurityContextPod security context.
serviceMonitor.enabledServiceMonitor for Prometheus Operator (backend, file-handlers).
terminationGracePeriodSecondsPod stop timeout (ai-core, 120 seconds by default).

Ingress ​

ParameterDescription
backend.ingress.ingressClassNameIngress controller class.
backend.ingress.tlshosts, backend.ingress.tlssecretApplication domain and TLS secret.
backend.ingress.externalREST API at /app/api.
backend.ingress.websocketWebSocket at /app/api/v1/ws and nested paths (/ws/space, /ws/document), 86400s timeouts.
backend.ingress.uploadBoard import at /app/api/v1/flip/backup/upload, 6G body size limit, 3600s timeouts.
backend.ingress.redirectRedirect / → /app; the domain is set in the permanent-redirect annotation.
frontend.ingress.uiUser interface at /app.
frontend.ingress.s3S3 proxying from /app/s3/(.*) to the frontend-s3 Service; storage served over HTTPS requires the backend-protocol: "HTTPS" and upstream-vhost annotations.
frontend.service.s3.storageurlS3 storage host for the ExternalName Service.
mcp-server.ingressMCP server on a separate domain (tlshosts/tlssecret).

Upgrading ​

bash
helm upgrade flip oci://cr.yandex/crpbj8irels1kqult74e/onpremise/flip-chart --version 1.2.0 -f values.yaml -n flip
kubectl -n flip get pods

For the version update procedure, see Updates.

Uninstalling ​

bash
helm uninstall flip -n flip
kubectl delete namespace flip

flip on-premise and cloud documentation