This guide covers Docker Compose (local/bare-metal), Helm on Kubernetes, and the local-k8s quickstart. For
the source-of-truth hierarchy (which service reads a YAML file, which reads env vars, and how Helm is the canonical K8s
contract), see Configuration reference.
Three logical databases required: apihub_backend, api_linter, agents_backend (names are configurable). Pre-create them before first start — see scripts/init-db/init.sql in the Compose folder.
S3-compatible storage
Any
Optional
Offloads build artefacts; reduces PG growth. Configure under s3Storage in backend config.yaml / Helm values.
config.yaml (path set by AGENT_CONFIG_FOLDER), same schema as config.template.yaml
APIHUB_CONFIG_FOLDER
Helm:qubershipApihubBackend.env, qubershipApiLinterService.env, and qubershipApihubAgentsBackend.env in
values.yaml are each serialised as YAML into a per-service Secret config.yaml, mounted under /app/<service>/etc/.
The UI and builder receive env vars injected directly by Deployment templates.
Go runtime memory soft limit. Keep below the container memory limit (~80% of limit in chart/Compose defaults). Helm: qubershipApihubBackend.goMemLimit. Compose: docker-compose.ymlenvironment.
Custom CA certificates (HTTPS outbound): from backend and linter releases with
qubership-core-base, mount PEM files at /tmp/cert
(Compose: ./certs:/tmp/cert:ro on backend, linter, and agents-backend; Helm: *.customCa values).
The base image entrypoint imports them into the system trust store before the process starts.
MinIO/S3 endpoint CA stays in s3Storage.crt in config.yaml.
See Configuration reference — custom CA Secret.
All other parameters are config.yaml keys. Most important:
config.yaml key
Mandatory
Default
Description
database.host
Yes
localhost
PostgreSQL host
database.port
Yes
5432
PostgreSQL port
database.name
Yes
apihub
Database name (must be pre-created)
database.username
Yes
apihub
Database user
database.password
Yes
apihub
Database password
security.productionMode
No
true
false allows local APIHUB account login; true requires IdP
All configuration via config.yaml (path: LINTER_CONFIG_FOLDER). Helm renders
qubershipApiLinterService.env into this file; Compose mounts qubership-api-linter-service-config.yaml.
LOG_LEVEL and GOMEMLIMIT stay container environment variables (GOMEMLIMIT default 800MiB Helm /
1600MiB Compose; Helm key qubershipApiLinterService.goMemLimit).
Custom CA certificates (HTTPS outbound): with the
qubership-core-base runtime image, mount PEM files at
/tmp/cert (Compose: uncomment the linter ./certs:/tmp/cert:ro volume; Helm:
qubershipApiLinterService.customCa). Required for corporate HTTPS to APIHUB or OpenAI when public CAs are
insufficient.
Config key
Mandatory
Default
Description
database.host
Yes
localhost
PostgreSQL host
database.port
Yes
5432
PostgreSQL port
database.name
Yes
apihub_linter
Database name (must be pre-created)
database.username
Yes
apihub_linter
Database user
database.password
Yes
—
Database password
technicalParameters.apihub.url
Yes
http://localhost:8090
Portal base URL reachable from inside the linter container (e.g. http://qubership-apihub-ui:8080)
technicalParameters.apihub.accessToken
Yes
—
System API token. Must match zeroDayConfiguration.accessToken in backend config
technicalParameters.basePath
No
.
Base path for binary and static files
technicalParameters.listenAddress
No
:8080
Listen address for the HTTP server
technicalParameters.apiSpecDirectory
No
<basePath>/api
Directory of API specifications to expose
security.allowedOrigins
No
[]
Extra CORS origins (dev only; empty on prod)
linters.spectral.binPath
Yes
resources/spectral/linux/spectral
Path to the Spectral binary inside the container
linters.spectral.workers
No
1
Number of concurrent Spectral linter workers
linters.ai.enabled
No
false
Enable the AI-powered OpenAPI linter
linters.ai.workers
No
1
Number of concurrent AI linter workers
linters.ai.excludedPackages
No
[]
Package IDs to exclude from AI linting
linters.ai.includedPackages
No
[]
Package IDs to include (empty = all)
linters.ai.openAI.apiKey
Cond.
—
OpenAI API key (required when linters.ai.enabled: true)
linters.ai.openAI.apiProxy
No
—
HTTP proxy for OpenAI requests
linters.ai.openAI.model
No
—
OpenAI model to use (e.g. gpt-4o)
linters.ai.openAI.rateLimitRPS
No
10
OpenAI requests per second limit
linters.ai.openAI.rateLimitBurst
No
30
OpenAI burst limit
olric.discoveryMode
No
local
Olric discovery: local (single pod) or lan (multi-pod)
olric.replicaCount
No
1
Olric replica count
olric.namespace
No
—
Olric discovery namespace (set by Helm to the release namespace)
All configuration via config.yaml (path: AGENTS_BACKEND_CONFIG_FOLDER). Helm renders
qubershipApihubAgentsBackend.env into this file; Compose mounts qubership-apihub-agents-backend-config.yaml.
LOG_LEVEL and GOMEMLIMIT stay container environment variables (GOMEMLIMIT default 205MiB; Helm key
qubershipApihubAgentsBackend.goMemLimit).
Config key
Mandatory
Default
Description
database.host
Yes
localhost
PostgreSQL host
database.port
Yes
5432
PostgreSQL port
database.name
Yes
apihub_agents_backend
Database name (must be pre-created)
database.username
Yes
apihub_agents_backend
Database user
database.password
Yes
—
Database password
technicalParameters.apihub.url
Yes
http://localhost:8090
Portal base URL reachable from inside the agents-backend container
technicalParameters.apihub.accessToken
Yes
—
System API token. Must match zeroDayConfiguration.accessToken
technicalParameters.basePath
No
.
Base path for binary and static files
technicalParameters.listenAddress
No
:8080
Listen address for the HTTP server
technicalParameters.apiSpecDirectory
No
<basePath>/api
Directory of API specifications to expose
businessParameters.defaultWorkspaceId
No
—
If set, package structure is copied from this workspace to the target workspace during discovery
security.allowedOrigins
No
[]
Extra CORS origins (dev debugging only)
security.insecureProxy
No
false
Deprecated. Enable the unauthenticated proxy endpoint. Dangerous — do not enable on prod
cleanup.snapshots.schedule
No
0 22 * * 0
Cron schedule for the snapshots cleanup job
cleanup.snapshots.ttlDays
No
30
Retention period in days for snapshots (0 removes all)
Custom CA certificates (HTTPS outbound): with the
qubership-core-base runtime image, mount PEM files at
/tmp/cert (Compose: uncomment the agents-backend ./certs:/tmp/cert:ro volume; Helm:
qubershipApihubAgentsBackend.customCa). Required for corporate HTTPS to APIHUB or remote agents when public CAs
are insufficient.
Chart: oci://ghcr.io/netcracker/charts/qubership-apihub, one version per product release. A released chart pins
every image tag to the component versions of that release, so --version selects the whole product. The versions are
listed on the releases page; the Latest release is the
newest product version, and its .tgz is attached to it.
The chart sources are in deploy/helm-templates/qubership-apihub/.
Their image tags are dev, the state of develop: install from the sources only for development.
Write a values.yaml with the mandatory fields below; the chart defaults cover the rest. To see every value of a
version, with its defaults and comments:
qubershipApihubBackend.env in values.yaml maps 1:1 to config.yaml keys — same table as
qubership-apihub-backend above. Helm additionally auto-patches olric.namespace and
olric.replicaCount from the release namespace and replicas value.
Optional Secret mounted at /tmp/cert for corporate HTTPS outbound
For secrets management on production clusters use Kubernetes ExternalSecrets, CSI driver, or sealed-secrets — do not
commit plaintext credentials in values.yaml.
Not for production.deploy/helm-templates/local-k8s-quickstart/ contains
scripts for Kind or Rancher Desktop with an ingress controller and PostgreSQL. Optional Apache Superset can be deployed
for analytics.