Skip to content
SHC Docs

App variables

Layer 6. Services. Services

New line, in development. This page describes SHC as it is on the dev branch, 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.

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.

Wherever a field applies, it has one name:

FieldMeaning
hostnameHost to dial. Empty means use the integration.
portTCP port.
usernameLogin on that service.
passwordSecret for that login.
databaseDatabase 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 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.

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>!.

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.

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: false
smtp:
hostname: ""
port: 587
username: ""
password: ""
fromAddress: [email protected]
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.