Configuration reference
This page lists every configuration key of the Foundation4 API server and worker processes, with type, default and effect, and describes the order in which the processes read configuration files and environment variables. The page also describes how the Helm charts supply each key, the OpenTelemetry variables and the branding.name key. Operators who change the behavior of a deployment beyond the Helm values need this page. Values reference lists the Helm values that produce this configuration.
Load order
The API server, the workers and the command-line interface (CLI) read the configuration once, at process start, from the working directory /app. Each source overrides the keys that the previous sources set, and sections merge key by key:
defaults.yaml. A file in the working directory. The images contain no such file.config/settings.yaml. The charts mount no such file.config/f4ai-*.yaml. Every file whose name starts withf4ai-and ends with.yaml, in byte order of the file name. Files ending in.ymlare ignored.config/secrets/<key path>. One file per key, named by the dotted key path, such asconfig/secrets/app.master.secret. The content of the file is the value, without one trailing line break. File names that start with.are skipped. A file named after a key that another file extends, such asapp.masternext toapp.master.key, stops the process with a message that containsis both a value and a table.- Environment variables. Every variable named
FOUNDATION4AI__<SECTION>__<KEY>.
The processes read every file under config/secrets as a string, so these files set keys of type String or UUID only. An integer, boolean or list key belongs in a YAML file or an environment variable.
In a Helm deployment, /app/config holds the following files, read in this order:
| File | Source | Content |
|---|---|---|
f4ai-00-defaults.yaml | ConfigMap foundation4ai-api-server | The chart defaults listed in Keys |
The configs entries | Values api-server.configs, in the same ConfigMap | Operator settings, when the entry name matches f4ai-*.yaml |
The secrets entries | Values api-server.secrets, in the Secret foundation4ai-api-server | Operator settings that contain secrets, when the entry name matches f4ai-*.yaml |
secrets/database.url, secrets/nats.url, secrets/redis.url, secrets/prometheus.url | Secret foundation4ai-core of the core release | Database, NATS JetStream, cache and Prometheus addresses |
secrets/app.license, secrets/app.secret, secrets/app.master.key, secrets/app.master.secret | Secret foundation4ai-secrets | License, application secret and master key |
nats-ca.crt | The Secret named in api-server.natsCaSecret, when set | Certificate authority of the NATS server certificate |
Digits sort before letters, so an operator file named f4ai-10-<topic>.yaml is read after the chart defaults. The files under /app/config/secrets override every YAML file, and environment variables override every file.
The configuration takes effect only when a process starts. Each API server and worker pod carries a checksum of the ConfigMap, of the Secret foundation4ai-api-server, of the credentials in foundation4ai-secrets and of the addresses in foundation4ai-core, so a helm upgrade of the application release that changes one of them replaces the pods. A change that reaches the cluster without an upgrade of the application release reaches running pods after kubectl rollout restart, as described in Configuration change.
The processes ignore unknown keys, so a misspelled key has no effect and produces no error. A missing required key stops the process at startup with a message that starts with Failed to parse config:.
Chart delivery
The application release creates the ConfigMap foundation4ai-api-server and the Secret foundation4ai-api-server as Helm hooks on every install and upgrade:
- ConfigMap. Holds
f4ai-00-defaults.yamland everyconfigsentry. The value of each entry is a string, usually a YAML block. - Secret. Holds every
secretsentry.
The chart mounts both objects at /app/config in the server and worker containers and in the hook Jobs. The same volume holds the keys of the Secret foundation4ai-core of the core release and the application credentials of foundation4ai-secrets as files under /app/config/secrets, so the application chart renders without access to the cluster, such as with helm template or a GitOps tool. The core release reads foundation4ai-secrets from the cluster to build the addresses and renders only against the cluster. An offline render of the application release computes no checksum of the two Secrets, so a credential change then needs kubectl rollout restart.
Every key of the ConfigMap also becomes an environment variable in the server and worker containers. The Secrets reach the processes only as files, and the hook Jobs receive no environment variables from the chart. The chart sets the following variables in the server and worker containers:
F4AI_FASTEMBED_CACHE./cache/fastembed, a writable directory into which the processes download FastEmbed models that the model directory lacks, as described in Models, packages and air-gapped installs. A process started without the variable uses/tmp/foundation4ai-fastembed.FOUNDATION4AI__PATHS__HUGGINGFACE. The value ofapi-server.huggingfaceCache.path,/cache/huggingfaceby default, a writable directory for the Hugging Face tokenizers of BM25 indexes. The variable overridespaths.huggingfacein every file. The chart omits the variable whenapi-server.huggingfaceCache.enabledisfalseor when a model image is mounted at/data/huggingface.
A credential in foundation4ai-secrets reaches the processes at the next start of the pods. A value from which the core release builds an address, such as a password, reaches foundation4ai-core with an upgrade of the core release, and then the pods at their next start. An upgrade of the application release after either change replaces the pods. Secrets and keys describes the Secret keys.
The Secret keys and the configuration keys follow two naming schemes. The processes never read the single-underscore names:
Key in foundation4ai-secrets | Configuration key | File in /app/config |
|---|---|---|
POSTGRES_URL, or POSTGRES_USER, POSTGRES_PASSWORD and POSTGRES_DATABASE with the bundled PostgreSQL | database.url | secrets/database.url, built by the core release |
REDIS_URL, or REDIS_PASSWORD with the bundled cache | redis.url | secrets/redis.url, built by the core release |
NATS_URL, or NATS_PASSWORD with the bundled NATS JetStream | nats.url | secrets/nats.url, built by the core release |
PROMETHEUS_URL, optional, read only when the bundled Prometheus is disabled | prometheus.url | secrets/prometheus.url, built by the core release |
FOUNDATION4AI_APP_LICENSE | app.license | secrets/app.license |
FOUNDATION4AI_APP_SECRET | app.secret | secrets/app.secret |
FOUNDATION4AI_APP_MASTER_KEY | app.master.key | secrets/app.master.key |
FOUNDATION4AI_APP_MASTER_SECRET | app.master.secret | secrets/app.master.secret |
Keys
The "Chart" column shows the value in f4ai-00-defaults.yaml, or "Credential file" for a value that the chart mounts as a file under /app/config/secrets. "Required" means that the process does not start without the key.
Application
| Key | Type | Default | Chart | Effect |
|---|---|---|---|---|
app.host | String | localhost | 0.0.0.0 | Address on which the API server listens, for the API port and the metrics port. The chart value accepts traffic from the Service and from Prometheus. |
app.port | Integer | 8000 | 8000 | Port of the API server. The container port, the probes and the Service target port are fixed at 8000, so a deployment keeps the default. |
app.metrics_port | Integer | 9090 | 9090 | Port on which the API server serves the Prometheus endpoint /metrics, apart from the API port. A value equal to app.port stops the API server at startup with the message app.metrics_port must differ from app.port. The workers serve /metrics on port 9090 whatever the key. The container ports and the Prometheus annotations are fixed at 9090, so a deployment keeps the default. |
app.log_level | String or integer | warn | warn | Log level of the API server and worker processes: off, error, warn, info, debug or trace, or 0 to 5 in the same order. Any other value stops the process at startup. |
app.allow_private_endpoints | Boolean | true | true, from api-server.allowPrivateEndpoints | Accepts LLM and embedding provider addresses that point at private, loopback and link-local networks, where on-premises model servers usually run. false accepts public addresses only. The chart passes the same value to the gRPC service. LLMs describes the effect. |
app.cors_allowed_origins | List of strings | [] | [], from api-server.corsAllowedOrigins | Browser origins allowed to call the API from another site, such as https://app.example.com. An empty list allows none, and * allows any origin. API conventions describes the headers. |
app.max_body_bytes | Integer | 10485760 | Not set | Largest request body that the API server accepts, in bytes, 10 MiB by default. A larger body receives HTTP 413. |
app.fastembed_instances | Integer | 2 | 2, from api-server.fastembedInstances | Most copies of each FastEmbed model that one process loads, so that searches and document processing embed in parallel. A process loads a further copy only when calls overlap, and each copy takes as much memory as the model. A value of 0 counts as 1. Scaling and performance describes the effect. |
app.license | String | Required | Credential file | The license, as described in Licensing |
app.secret | String | Required | Credential file | The application secret: a 32-byte key in URL-safe Base64. An invalid value stops the process with a message that contains Error decoding secret key. |
app.master.key | UUID | Required | Credential file | Identifier of the master key |
app.master.secret | String | Required | Credential file | Secret of the master key |
Database
| Key | Type | Default | Chart | Effect |
|---|---|---|---|---|
database.url | String | Required | Credential file | PostgreSQL connection URL, such as postgres://<user>:<password>@<host>:5432/<database>?sslmode=verify-full |
database.pool_size | Integer | 5 | 3 | Maximum connections of each API server process. Workers always use 1 connection. Database describes the connection budget. |
database.schema | String | public | Not set | Schema of the main tables, created at startup when missing. The system ID that a license is issued for depends on the schema, as described in Licensing, so a deployment keeps the schema of the license. |
database.embeddings_schema | String | embeddings | Not set | Schema of the pipeline tables, created at startup when missing |
database.ca_cert | String | None | Not set | Certificate authority for TLS connections to PostgreSQL, as PEM text. With sslmode=require, verify-ca or verify-full, the processes and the CLI verify the server certificate against this certificate; prefer checks no certificate. |
database.statement_timeout_seconds | Integer | 300 | Not set | Longest time that one SQL statement runs while the API server and the workers serve requests, in seconds. PostgreSQL ends a longer statement. 0 disables the limit. Database migrations and the build of a search index run without the limit. |
database.log_level | String or integer | None | Not set | Log level of the database library, with the values of app.log_level. Without the key, the database library logs at debug or trace when app.log_level is debug or trace, and at warn otherwise. |
Cache, queue and gRPC service
| Key | Type | Default | Chart | Effect |
|---|---|---|---|---|
redis.url | String | Required | Credential file | Redis-compatible cache URL, such as redis://default:<password>@<host>:6379. A rediss:// URL connects over TLS. |
nats.url | String | Required | Credential file | NATS JetStream URL, such as nats://<user>:<password>@<host>:4222. A tls:// URL requires TLS. |
nats.bucket | String | Required | documents | Object store that holds submitted document text for 24 hours |
nats.stream | String | Required | DOCUMENTS | Stream that holds the processing jobs for 24 hours |
nats.documents_prefix | String | document | Not set | Subject prefix of the jobs. The workers consume through the consumer <prefix>-processor. Deployments leave the key unset. |
nats.replicas | Integer | 1 | 3, from global.natsReplicas | Copies that NATS JetStream keeps of the stream and the object store, at most the number of NATS servers: 3 for the bundled cluster, 1 for a single external server |
nats.ca_cert | String | None | /app/config/nats-ca.crt when api-server.natsCaSecret is set | Path of a PEM file with the certificate authority of the NATS server certificate. With the key, the processes require TLS to NATS JetStream and trust this certificate authority. |
grpc.url | String | Required | http://localhost:50051 | Address of the gRPC service. The chart value reaches the sidecar container in the same pod. |
The API server and the workers create the stream and the object store at startup when the stream and the object store do not exist, and set the replica count of an existing stream and object store to nats.replicas. The workers create or update the consumer. Scaling and performance describes the queue retention.
Prometheus and MCP server
| Key | Type | Default | Chart | Effect |
|---|---|---|---|---|
prometheus.url | String | http://prometheus:9090 | Credential file | Address of the Prometheus server that the statistics route queries. An empty value selects the default. The core release writes the address of the bundled Prometheus server, or PROMETHEUS_URL when the bundled Prometheus is disabled. |
mcp.allowed_hosts | List of strings | ["*"] | Not set | Host header values that the MCP endpoint accepts, as <host> or <host>:<port>. * accepts any host. With an explicit list, localhost, 127.0.0.1 and ::1 stay accepted. MCP server describes the check. |
Model paths and branding
| Key | Type | Default | Chart | Effect |
|---|---|---|---|---|
paths.fastembed | String | Required | /data/fastembed | FastEmbed model directory. When the directory is not writable, the processes download missing built-in models into the directory named in F4AI_FASTEMBED_CACHE, or into /tmp/foundation4ai-fastembed when the variable is not set. |
paths.gpt4all | String | Required | /data/gpt4all | GPT4All model directory |
paths.huggingface | String | Required | /data/huggingface, replaced by /cache/huggingface through FOUNDATION4AI__PATHS__HUGGINGFACE | Hugging Face directory. The API server and the workers download the Hugging Face tokenizers of BM25 indexes into the directory. In a chart installation, Hugging Face embedding models and the sentence-transformers token splitter read from a Hugging Face model image mounted at /data/huggingface. |
paths.nltk | String | Required | /data/nltk | NLTK data directory |
branding.name | String | Foundation4.ai | Not set | Product name in the API documentation, as described in Branding |
Models, packages and air-gapped installs describes the model directories.
Keys without effect
The processes ignore the following keys, which configuration files of earlier releases set:
database.debug. Database library logging followsdatabase.log_levelandapp.log_level, as described in Logging.routes.openai. The OpenAI-compatible endpoint is fixed at/openai/v1.
Environment variables
An environment variable overrides one key. The name is FOUNDATION4AI__, followed by the key path in upper case with each . replaced by __:
| Variable | Key |
|---|---|
FOUNDATION4AI__APP__LOG_LEVEL | app.log_level |
FOUNDATION4AI__DATABASE__POOL_SIZE | database.pool_size |
FOUNDATION4AI__APP__MASTER__KEY | app.master.key |
The processes parse numeric values as numbers and true or false as booleans.
The charts set FOUNDATION4AI__PATHS__HUGGINGFACE, as described in Chart delivery, and no other FOUNDATION4AI__ variable. A configs entry whose name is a valid variable name becomes an environment variable of the server and worker containers, because the chart loads the ConfigMap with envFrom. The same entry also appears as a file in /app/config, which the processes ignore because the name does not match f4ai-*.yaml. A secrets entry becomes no environment variable, and the hook Jobs receive none of these variables. Secrets belong in secrets entries named f4ai-*.yaml, which the chart stores in a Kubernetes Secret.
api-server:
configs:
FOUNDATION4AI__DATABASE__POOL_SIZE: "5"
Configuration change
The following procedure adds an operator configuration file. The example raises the log level for a diagnosis:
-
Add the file to the values file of the application release:
api-server:configs:f4ai-10-logging.yaml: |app:log_level: infoExpected result:
configsholdsf4ai-10-logging.yaml. -
Upgrade the application release. The changed ConfigMap changes the checksum annotation of the API server and worker pods, so the upgrade replaces the pods:
helm upgrade --install foundation4ai ./charts/foundation4ai \-n foundation4ai -f foundation4ai.values.yaml --wait --timeout 10mExpected result: Helm reports
STATUS: deployed. -
Confirm that the new API server and worker pods run:
kubectl -n foundation4ai rollout status deploy/foundation4ai-api-serverkubectl -n foundation4ai rollout status deploy/foundation4ai-api-server-workerExpected result: each status command ends with
successfully rolled out. -
Confirm that the file is mounted:
kubectl -n foundation4ai exec deploy/foundation4ai-api-server -c server -- cat /app/config/f4ai-10-logging.yamlExpected result: the content of the file. The files under
/app/config/secretscontain secrets and are not printed. -
Confirm the new level in the API server log:
kubectl -n foundation4ai logs deploy/foundation4ai-api-server -c server | grep "API on 0.0.0.0:8000"Expected result: a line that ends with
Starting Foundation4.ai API on 0.0.0.0:8000. The line appears at levelinfoand below, not atwarn.
The operator removes the entry and repeats steps 2 and 3 when the diagnosis ends.
A change to foundation4ai-secrets or to foundation4ai-core without an upgrade of the application release, or with a release rendered offline, reaches the processes after a restart:
kubectl -n foundation4ai rollout restart deploy/foundation4ai-api-server deploy/foundation4ai-api-server-worker
Expected result: deployment.apps/foundation4ai-api-server restarted and deployment.apps/foundation4ai-api-server-worker restarted. The status commands of step 3 confirm the restart.
Logging
app.log_level sets the level of the API server and worker processes. The chart default is warn, and a production deployment keeps warn outside a limited diagnosis period, as described in Security hardening. The sample values file supplied with the charts shows a debug setting as a commented example, which is not a production value.
| Process | Output | Level |
|---|---|---|
| API server and workers | Standard output, text lines with timestamp, level and source | app.log_level. The database library logs at database.log_level, or, without that key, at debug or trace when app.log_level is debug or trace and at warn otherwise. The h2, hyper_util and tower::buffer libraries are silenced, and the NATS client logs at warn. |
| Hook Jobs and other CLI subcommands | Standard error | info, or app.log_level when that level is debug or trace |
| gRPC service | Standard error | INFO, fixed |
| Dashboard | Container output | Not configurable |
The API server writes one line per request with the method, path, status, duration and request identifier: request failed at warn for a status of 500 or above, request refused at info for a status from 400 to 499, and request at debug for any other status. The warn default therefore shows server errors and hides refused and successful requests.
The RUST_LOG variable has no effect: the API server and the worker set the log filter from app.log_level and database.log_level. Monitoring and logging describes how to read the logs.
OpenTelemetry
The API server and the workers export traces and log records through the OpenTelemetry Protocol (OTLP) when an OTLP variable is set. A queued document carries the trace context of the request that submitted the document. The worker span process_documents of a batch from one request joins the trace of that request, and the span of a batch with documents from several requests links to each of their traces. The gRPC service and the dashboard export no OpenTelemetry data. No collector ships with the charts.
| Variable | Effect |
|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT | Base URL of the collector for all signals |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | Collector URL for one signal, overriding the base URL |
OTEL_EXPORTER_OTLP_PROTOCOL | grpc or http/protobuf. Without the variable, an endpoint that contains :4317 selects grpc, and any other endpoint selects http/protobuf. |
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, OTEL_EXPORTER_OTLP_LOGS_PROTOCOL | Protocol for one signal |
OTEL_EXPORTER_OTLP_HEADERS | Headers sent to the collector, such as an authorization header |
OTEL_EXPORTER_OTLP_TIMEOUT | Export timeout, in milliseconds |
OTEL_SERVICE_NAME | Service name of the exported data. The default is foundation4ai for the API server and foundation4ai-worker for the workers. |
OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG | Sampling of traces, such as parentbased_traceidratio with a ratio |
OTEL_PROPAGATORS | Trace context formats read from and written to HTTP headers. The default is tracecontext,baggage. |
Without any endpoint or protocol variable, the processes create no exporter and send nothing. A configs entry with the name of a variable reaches the server and worker containers, as described in Environment variables. The build does not include the TLS option of the gRPC exporter, so a collector reached over gRPC uses an unencrypted connection. Metrics stay on the Prometheus endpoints described in Monitoring and logging, which also shows how to set the variables through configs.
Branding
branding.name sets the product name that the API server shows in the API documentation. The default is Foundation4.ai.
| Location | Effect of branding.name |
|---|---|
OpenAPI document /openapi.json, and the documentation pages /docs, /_docs and /_docs-swagger | The document title is the name, and the description is the name followed by API documentation |
| API server start log line | Starting <name> API on <address>, at level info |
| Dashboard | Not used; the dashboard shows the default name |
Worker log, the response of /, the MCP server instructions and the OpenAPI section descriptions | Not used; the default name is fixed in the code |
The following procedure sets the name. The example shows the default name; a deployment replaces the value.
-
Add the file to the values file of the application release:
api-server:configs:f4ai-10-branding.yaml: |branding:name: Foundation4.aiExpected result:
configsholdsf4ai-10-branding.yaml. -
Upgrade the application release, which replaces the API server pods, and wait for the new pods:
helm upgrade --install foundation4ai ./charts/foundation4ai \-n foundation4ai -f foundation4ai.values.yaml --wait --timeout 10mkubectl -n foundation4ai rollout status deploy/foundation4ai-api-serverExpected result: Helm reports
STATUS: deployed, and the status command ends withsuccessfully rolled out. -
Read the title of the OpenAPI document through the port forward of API and dashboard access:
curl -s "$FOUNDATION4_URL/openapi.json" | grep -o '"title":"[^"]*"' | head -1Expected result:
"title":"Foundation4.ai", or the name that the file sets.