App variables
Layer 6. Services. Services
New line, in development. This page describes SHC as it is on the
devbranch, not the released product. See The new line.
Every app’s vars.yaml uses the same shape, so an operator can read one app and know where the database password, the bucket and the first login live in any other. The catalogue lint TestEveryCatalogueAppVariableFollowsTheLayout refuses an app that drifts.
app.yaml’s vars: block declares the same paths (postgres.password@secret!). Defaults live in vars.yaml. There is no second spelling of a name.
One object per backing service
Section titled “One object per backing service”A backing service is a top-level object named for the kind, and that name is the plug’s name (the stem of *.plug.yaml). A service the app bundles is named for its kind too. The kinds:
postgres, mysql, mongodb, clickhouse, neo4j, valkey, redis, rabbitmq, redpanda, meili, s3, webdav, smtp, imap, oidc, llm, coturn, gitlab
Name the kind, never the product. Keycloak is the product that serves oidc. A cache is valkey. Mail submission is smtp. A plug named redis (the redis socket) keeps the object redis, because the object name and the plug name are the same string. An app with no plug or socket of the kind may still carry the product spelling mail or keycloak; the lint checks its fields the same way and refuses it beside a plug or socket of the kind. integration holds a socket’s own settings (gitlab’s minting user) and uses the same field names. The lint’s list and this one are the same list, held together by TestVariablesPageListsTheLintKinds.
A connection is never nested under another object. huly’s ai-bot reads mongodb and llm, not aiBot.mongo and aiBot.openai. The lint refuses an object with an address field (hostname, host, endpoint, baseUrl, uri, url) beside a port, a credential or a database name anywhere below the top level.
An empty hostname, or an empty endpoint on s3, means the value is not given directly: the plug is required and the integration fills it, or, where the plug is optional (huly’s mongodb), the feature it serves stays off. nextcloud’s postgres.plug.yaml is the shape: required when vars.postgres.hostname is empty.
The same fields
Section titled “The same fields”Wherever a field applies, it has one name:
| Field | Meaning |
|---|---|
hostname | Host to dial. Empty means use the integration. |
port | TCP port. |
username | Login on that service. |
password | Secret for that login. |
database | Database or schema name. |
s3 uses its own set: endpoint, bucket, accessKey, secretKey, region, useSsl. region is that service’s field. An SHC place is a location. Empty endpoint means use the integration. port sits beside those when the app has one.
Do not invent a synonym. host, user, name and db are not field names. mail, database and keycloak are not object names when a plug of the real kind is in the app.
Keys are camelCase.
The first account
Section titled “The first account”The app’s own first login is one object, admin, with username, password and email. Leave out a field the app does not have. Do not add adminUser, adminPassword, adminEmail, rootUser, rootPassword or initialLogin* beside it.
A service user (the postgres role, the bucket key) stays on the service object. admin is the person who signs in to the app.
Names that moved
Section titled “Names that moved”The layout renamed 509 keys across 85 apps: keycloak.* to oidc.*, the flat adminUser/adminPassword/adminEmail to admin.*, mail.* to smtp.*, host to hostname, and the external-* adapters’ flat fields under their kind (SHC-1360), and huly’s aiBot.mongo.* and aiBot.openai.* to mongodb.* and llm.* (SHC-1748). The old-to-new list is var-renames-shc-1360.tsv, one row per app and key. A --var or a persisted override on an old name is kept, read by nothing, and the new default applies; every install and update says so with X200977VARUND, naming the keys. Re-set the value under the new name and drop the old one with --var <old>!.
Secrets
Section titled “Secrets”A secret the app can mint defaults to a vault reference with autogen:
password: "ref+vault://postgres_password?autogen"A secret the operator pastes from a provider (an external SMTP password, an external bucket key) stays empty. Do not autogen a value that has to match a credential someone else already issued.
Worked example
Section titled “Worked example”A small app with Postgres, a bucket, mail and a first login:
admin: username: admin password: "ref+vault://admin_password?autogen"postgres: hostname: "" port: 5432 database: feedback username: feedback password: "ref+vault://postgres_password?autogen"s3: endpoint: "" port: 9000 bucket: feedback accessKey: feedback secretKey: "ref+vault://s3_secret_key?autogen" region: us-east-1 useSsl: falsesmtp: hostname: "" port: 587 username: "" password: ""oidc: realm: "" clientId: feedback clientSecret: "ref+vault://oidc_client_secret?autogen"Empty postgres.hostname, s3.endpoint and smtp.hostname mean those plugs are how the app reaches the service. Set the field to a real host only to point at something that is not an integration.