Skip to Content

Template dependencies

Deploy a template app together with the database or cache it needs.

Some catalog templates need a service to run: a web analytics app needs a PostgreSQL database, an error tracker a database and a Valkey cache. The template declares these dependencies, and the deploy dialog shows a Dependencies tab with one section per dependency.

Three ways to meet a dependency

  • Create new (the default): a new PostgreSQL or Valkey app is created in the same project, named <app>-<dependency> (for example umami-db). It gets the highest version the template allows, one instance and the service template's default storage. Choose Edit to change the name, version, instances or storage size.
  • Use existing: pick a PostgreSQL or Valkey app that already runs in the same project. Only apps whose version satisfies the template are listed (a template asking for >=15 does not offer a PostgreSQL 14).
  • None: only for optional dependencies. The environment variables that dependency would set are left out.

Services in other projects can not be picked.

Databases and roles

For PostgreSQL, the app gets its own logical database inside the service. It defaults to the app name (as a database identifier, so my-umami becomes my_umami), and is created when it does not exist yet. With Use existing you can type another name.

Apps that manage their own schema get the admin role on their database. A database that already exists gets readwrite instead, so a new app can not change another app's tables, unless you tick Keep admin on an existing database.

Valkey has no logical databases: the app gets its own role on the server.

Credentials

Database credentials are never stored in the app's environment. The section lists the variables the dependency sets (such as DATABASE_URL); each pod gets its own short-lived login when it starts, and the app's settings only hold a reference to the service. This is the same lease an IaC app file writes by hand.

Each pod holds its own connections. An app with many replicas can reach the connection limit of a small PostgreSQL (100 by default); give the service more resources or use fewer replicas.

Cost

A new service is an ordinary app: it is billed on its own, like a PostgreSQL you deploy from the catalog. Using an existing service adds no cost.

The app and its new services are created together or not at all. When they do not fit the project quota, or the account can not pay for them, the dialog shows why and nothing is created.

Deploy order

New services are created first. The app's first deploy waits until its services are running, so it does not start before its database exists.

Deleting

Deleting an app keeps its services and their data, also the ones created for it. Delete a service yourself when nothing uses it any more.

A service that an app still uses can not be deleted: the delete is refused and names the app that uses it. The service's header shows Used by with its apps, and an app's header shows Uses with its services. Delete or rebind those apps first.

Templates with dependencies

TemplateNeedsThe app reads
UmamiPostgreSQLDATABASE_URL
GlitchTipPostgreSQL and ValkeyDATABASE_URL, VALKEY_URL
KeycloakPostgreSQLKC_DB_URL_HOST, KC_DB_URL_PORT, KC_DB_URL_DATABASE, KC_DB_USERNAME, KC_DB_PASSWORD

Each one gets the admin role on a database named after the app, because it creates and upgrades its own tables. GlitchTip's Valkey role is admin too: its task queue runs Lua scripts, which the read/write role does not allow.

  • Umami starts with the login admin / umami. Change the password right after deploying.
  • GlitchTip runs its web server, worker and scheduler in one app. The first account that signs up becomes its admin, and sign-up closes after that. Emails go to the app's log until you set EMAIL_URL.
  • Keycloak runs in production mode behind the platform's TLS proxy, with a generated password for the temporary admin of the master realm. Create a permanent admin, then delete the temporary one.

Not supported yet

  • Templates that build a variable from several dependency values (for example a connection string with the host and port in it) can not be deployed with dependencies yet; the dialog shows the reason.
  • A new service is created with the service template's defaults; its own template inputs can not be set from this dialog.

On this page