Skip to main content

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:

  1. defaults.yaml. A file in the working directory. The images contain no such file.
  2. config/settings.yaml. The charts mount no such file.
  3. config/f4ai-*.yaml. Every file whose name starts with f4ai- and ends with .yaml, in byte order of the file name. Files ending in .yml are ignored.
  4. config/secrets/<key path>. One file per key, named by the dotted key path, such as config/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 as app.master next to app.master.key, stops the process with a message that contains is both a value and a table.
  5. 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:

FileSourceContent
f4ai-00-defaults.yamlConfigMap foundation4ai-api-serverThe chart defaults listed in Keys
The configs entriesValues api-server.configs, in the same ConfigMapOperator settings, when the entry name matches f4ai-*.yaml
The secrets entriesValues api-server.secrets, in the Secret foundation4ai-api-serverOperator settings that contain secrets, when the entry name matches f4ai-*.yaml
secrets/database.url, secrets/nats.url, secrets/redis.url, secrets/prometheus.urlSecret foundation4ai-core of the core releaseDatabase, NATS JetStream, cache and Prometheus addresses
secrets/app.license, secrets/app.secret, secrets/app.master.key, secrets/app.master.secretSecret foundation4ai-secretsLicense, application secret and master key
nats-ca.crtThe Secret named in api-server.natsCaSecret, when setCertificate 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.yaml and every configs entry. The value of each entry is a string, usually a YAML block.
  • Secret. Holds every secrets entry.

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 of api-server.huggingfaceCache.path, /cache/huggingface by default, a writable directory for the Hugging Face tokenizers of BM25 indexes. The variable overrides paths.huggingface in every file. The chart omits the variable when api-server.huggingfaceCache.enabled is false or 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-secretsConfiguration keyFile in /app/config
POSTGRES_URL, or POSTGRES_USER, POSTGRES_PASSWORD and POSTGRES_DATABASE with the bundled PostgreSQLdatabase.urlsecrets/database.url, built by the core release
REDIS_URL, or REDIS_PASSWORD with the bundled cacheredis.urlsecrets/redis.url, built by the core release
NATS_URL, or NATS_PASSWORD with the bundled NATS JetStreamnats.urlsecrets/nats.url, built by the core release
PROMETHEUS_URL, optional, read only when the bundled Prometheus is disabledprometheus.urlsecrets/prometheus.url, built by the core release
FOUNDATION4AI_APP_LICENSEapp.licensesecrets/app.license
FOUNDATION4AI_APP_SECRETapp.secretsecrets/app.secret
FOUNDATION4AI_APP_MASTER_KEYapp.master.keysecrets/app.master.key
FOUNDATION4AI_APP_MASTER_SECRETapp.master.secretsecrets/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​

KeyTypeDefaultChartEffect
app.hostStringlocalhost0.0.0.0Address 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.portInteger80008000Port 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_portInteger90909090Port 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_levelString or integerwarnwarnLog 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_endpointsBooleantruetrue, from api-server.allowPrivateEndpointsAccepts 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_originsList of strings[][], from api-server.corsAllowedOriginsBrowser 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_bytesInteger10485760Not setLargest request body that the API server accepts, in bytes, 10 MiB by default. A larger body receives HTTP 413.
app.fastembed_instancesInteger22, from api-server.fastembedInstancesMost 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.licenseStringRequiredCredential fileThe license, as described in Licensing
app.secretStringRequiredCredential fileThe 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.keyUUIDRequiredCredential fileIdentifier of the master key
app.master.secretStringRequiredCredential fileSecret of the master key

Database​

KeyTypeDefaultChartEffect
database.urlStringRequiredCredential filePostgreSQL connection URL, such as postgres://<user>:<password>@<host>:5432/<database>?sslmode=verify-full
database.pool_sizeInteger53Maximum connections of each API server process. Workers always use 1 connection. Database describes the connection budget.
database.schemaStringpublicNot setSchema 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_schemaStringembeddingsNot setSchema of the pipeline tables, created at startup when missing
database.ca_certStringNoneNot setCertificate 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_secondsInteger300Not setLongest 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_levelString or integerNoneNot setLog 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​

KeyTypeDefaultChartEffect
redis.urlStringRequiredCredential fileRedis-compatible cache URL, such as redis://default:<password>@<host>:6379. A rediss:// URL connects over TLS.
nats.urlStringRequiredCredential fileNATS JetStream URL, such as nats://<user>:<password>@<host>:4222. A tls:// URL requires TLS.
nats.bucketStringRequireddocumentsObject store that holds submitted document text for 24 hours
nats.streamStringRequiredDOCUMENTSStream that holds the processing jobs for 24 hours
nats.documents_prefixStringdocumentNot setSubject prefix of the jobs. The workers consume through the consumer <prefix>-processor. Deployments leave the key unset.
nats.replicasInteger13, from global.natsReplicasCopies 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_certStringNone/app/config/nats-ca.crt when api-server.natsCaSecret is setPath 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.urlStringRequiredhttp://localhost:50051Address 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​

KeyTypeDefaultChartEffect
prometheus.urlStringhttp://prometheus:9090Credential fileAddress 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_hostsList of strings["*"]Not setHost 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​

KeyTypeDefaultChartEffect
paths.fastembedStringRequired/data/fastembedFastEmbed 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.gpt4allStringRequired/data/gpt4allGPT4All model directory
paths.huggingfaceStringRequired/data/huggingface, replaced by /cache/huggingface through FOUNDATION4AI__PATHS__HUGGINGFACEHugging 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.nltkStringRequired/data/nltkNLTK data directory
branding.nameStringFoundation4.aiNot setProduct 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 follows database.log_level and app.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 __:

VariableKey
FOUNDATION4AI__APP__LOG_LEVELapp.log_level
FOUNDATION4AI__DATABASE__POOL_SIZEdatabase.pool_size
FOUNDATION4AI__APP__MASTER__KEYapp.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:

  1. Add the file to the values file of the application release:

    api-server:
    configs:
    f4ai-10-logging.yaml: |
    app:
    log_level: info

    Expected result: configs holds f4ai-10-logging.yaml.

  2. 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 10m

    Expected result: Helm reports STATUS: deployed.

  3. Confirm that the new API server and worker pods run:

    kubectl -n foundation4ai rollout status deploy/foundation4ai-api-server
    kubectl -n foundation4ai rollout status deploy/foundation4ai-api-server-worker

    Expected result: each status command ends with successfully rolled out.

  4. Confirm that the file is mounted:

    kubectl -n foundation4ai exec deploy/foundation4ai-api-server -c server -- cat /app/config/f4ai-10-logging.yaml

    Expected result: the content of the file. The files under /app/config/secrets contain secrets and are not printed.

  5. 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 level info and below, not at warn.

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.

ProcessOutputLevel
API server and workersStandard output, text lines with timestamp, level and sourceapp.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 subcommandsStandard errorinfo, or app.log_level when that level is debug or trace
gRPC serviceStandard errorINFO, fixed
DashboardContainer outputNot 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.

VariableEffect
OTEL_EXPORTER_OTLP_ENDPOINTBase URL of the collector for all signals
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINTCollector URL for one signal, overriding the base URL
OTEL_EXPORTER_OTLP_PROTOCOLgrpc 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_PROTOCOLProtocol for one signal
OTEL_EXPORTER_OTLP_HEADERSHeaders sent to the collector, such as an authorization header
OTEL_EXPORTER_OTLP_TIMEOUTExport timeout, in milliseconds
OTEL_SERVICE_NAMEService 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_ARGSampling of traces, such as parentbased_traceidratio with a ratio
OTEL_PROPAGATORSTrace 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.

LocationEffect of branding.name
OpenAPI document /openapi.json, and the documentation pages /docs, /_docs and /_docs-swaggerThe document title is the name, and the description is the name followed by API documentation
API server start log lineStarting <name> API on <address>, at level info
DashboardNot used; the dashboard shows the default name
Worker log, the response of /, the MCP server instructions and the OpenAPI section descriptionsNot 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.

  1. Add the file to the values file of the application release:

    api-server:
    configs:
    f4ai-10-branding.yaml: |
    branding:
    name: Foundation4.ai

    Expected result: configs holds f4ai-10-branding.yaml.

  2. 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 10m
    kubectl -n foundation4ai rollout status deploy/foundation4ai-api-server

    Expected result: Helm reports STATUS: deployed, and the status command ends with successfully rolled out.

  3. 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 -1

    Expected result: "title":"Foundation4.ai", or the name that the file sets.