Kubernetes (Helm)
Requirements
- A Kubernetes cluster and Helm 3
- The ingress-nginx Ingress controller; the annotations in the example
values.yamlare 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.rufor AI features (ai-core)
Chart components
| Subchart | Image | Port | Ingress |
|---|---|---|---|
backend | flip-backend | 9000 | /app/api, /app/api/v1/ws, /app/api/v1/flip/backup/upload, / redirect |
ai-core | flip-ai-core | 9100 | — |
file-handlers | flip-file-handlers | 8080 | — |
frontend | flip-frontend | 80 | /app, /app/s3/ → S3 storage |
mcp-server | flip-mcp-server | 8090 | mcp.example.flip-chart.ru/ |
Helm chart
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.yamlThe 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 valuesInstallation steps
1. Namespace and registry access
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
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.pemIf 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:
| Field | docker-compose | Kubernetes |
|---|---|---|
backend → FileHandlerServiceConfig.Address | http://flip-file-handlers:8080/api | http://file-handlers.flip.svc.cluster.local:8080/api |
backend → AI.LocalCore.BaseURL | http://flip-ai-core:9100 | http://ai-core.flip.svc.cluster.local:9100 |
mcp-server → flipApi.internalUrl | http://flip-backend:9000 | http://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):
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
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.tarand upload its contents to the root of the bucket (theapp,flip-shape-sets,flip-templates,gifs,logoandspacesdirectories). - In
values.yaml, set the storage host infrontend.service.s3.storageurl. The chart creates a Service of typeExternalNameand 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
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 flip7. Verification
kubectl -n flip get pods
kubectl -n flip get ingressAll 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
| Parameter | Description |
|---|---|
global.namespace | Installation namespace. An empty value means the release namespace (helm -n). |
global.imagePullSecrets | List of image registry access secrets. |
Common subchart parameters
The same for backend, ai-core, file-handlers, frontend and mcp-server.
| Parameter | Description |
|---|---|
enabled | Enables the component. |
replicaCount | Number of replicas. |
image.repository, image.tag, image.pullPolicy | Component image. |
annotations | Deployment and pod annotations. |
affinity, tolerations, nodeSelector | Pod placement. |
strategy | Deployment update strategy (RollingUpdate, Recreate). |
containers.containerPort | Container ports. |
containers.readinessProbe, containers.livenessProbe, containers.startupProbe | Container 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, envFrom | Environment variables. For ai-core: POSTGRES_DSN from the ai-core-config secret. |
service.enabled, service.type, service.ports | Kubernetes Service. |
resources | CPU/memory requests and limits. |
volumes, volumeMounts | Mounting of the configuration secret. The path inside the container is fixed (see configuration files). |
securityContext | Container security context. |
podSecurityContext | Pod security context. |
serviceMonitor.enabled | ServiceMonitor for Prometheus Operator (backend, file-handlers). |
terminationGracePeriodSeconds | Pod stop timeout (ai-core, 120 seconds by default). |
Ingress
| Parameter | Description |
|---|---|
backend.ingress.ingressClassName | Ingress controller class. |
backend.ingress.tlshosts, backend.ingress.tlssecret | Application domain and TLS secret. |
backend.ingress.external | REST API at /app/api. |
backend.ingress.websocket | WebSocket at /app/api/v1/ws and nested paths (/ws/space, /ws/document), 86400s timeouts. |
backend.ingress.upload | Board import at /app/api/v1/flip/backup/upload, 6G body size limit, 3600s timeouts. |
backend.ingress.redirect | Redirect / → /app; the domain is set in the permanent-redirect annotation. |
frontend.ingress.ui | User interface at /app. |
frontend.ingress.s3 | S3 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.storageurl | S3 storage host for the ExternalName Service. |
mcp-server.ingress | MCP server on a separate domain (tlshosts/tlssecret). |
Upgrading
helm upgrade flip oci://cr.yandex/crpbj8irels1kqult74e/onpremise/flip-chart --version 1.2.0 -f values.yaml -n flip
kubectl -n flip get podsFor the version update procedure, see Updates.
Uninstalling
helm uninstall flip -n flip
kubectl delete namespace flip