Skip to main content

Configuration

Every environment has one configuration document — hosting.yaml — describing the application in it, the database it uses, its storage and its secrets. What that document says is what Hosting applies; nothing else changes an environment's shape.

Open it from Hosting → Configuration. There are three ways to write it, and all produce the same document:

  • Form builds it from fields;
  • YAML lets you write or paste the document itself;
  • Repository YAML imports a document from a connected GitHub repository.

An environment's Configuration page

Repositories are connected under Company → Code sources → GitHub repositories: choose Connect GitHub, then Select repository, and enter its branch and YAML path from the repository root (for example deploy/hosting.yaml). An empty branch uses the repository’s default branch. Back on Configuration, Import from a repository lists them; choose Review repository YAML to fetch the document at an exact commit and open it in the configuration editor. Review it and set any environment-specific public values before saving or applying. Credentials still use the separate secret controls.

The review records the repository, YAML path and commit. A build from that revision uses the recorded commit, including when the branch has moved since import. To use a newer commit, import and review its configuration again. Saving or importing alone does not build or deploy a release.

Portable site setup​

Portable site patterns extend the configuration workflow with selected linked company setup. They are setup intent, not an exact clone: no databases, messages, uploaded files, volumes, backups, passwords, tokens or private keys are copied.

From the existing Configuration page:

  1. Export the current site's desired settings and explicitly choose the linked sections to include. Review the coverage report: deliberate omissions and unsupported required settings must be visible.
  2. Edit the YAML's logical names and public settings for the destination. A portable pattern has its own version; its nested hosting document keeps the existing hosting format version.
  3. Select an authorized destination environment, upload or paste the pattern, and supply explicit target resource and principal bindings. A matching name alone never grants ownership.
  4. Preview the whole setup. Review new and reused resources, capacity, required secrets and every refusal. Preview writes nothing and does not buy capacity, verify domains or switch DNS/MX.
  5. If new secret declarations are needed, explicitly prepare a draft, then use the existing write-only secret controls to enter fresh destination values. Preparation records configuration metadata; it is not a provisioned site. Re-preview after entering values.
  6. Confirm the reviewed additive setup. The server rechecks current permissions, bindings, state and capacity. Existing compatible declarations are reused; conflicting settings are refused, not overwritten. Omission never deletes or cancels anything.

After confirmation, follow the existing application, domain, DNS, email and access status surfaces. Accepted intent is not readiness. Provisioning and any required verification or credential setup still use their normal controls. An unchanged accepted pattern can be previewed and imported again without duplicating resources. Correct a refused component through its normal controls and re-preview; no database console or cluster credentials are required.

Keep secret values out of the pattern. Repository choices, target users, access keys and other nonportable identities must be explicitly bound or prepared on the destination. Import never starts a build, mail copy or destructive synchronization implicitly. Consequential operations retain their separate review and consent.

A worked pattern​

A pattern is one YAML document whose own version selects the portable format while its nested hosting document keeps its usual hosting version. This one declares an application, its desired member shape, a repository source, a website name, one DNS record set, one mail name and the access it needs:

site-pattern.yaml
version: "1.0"
hosting:
version: "1.3"
applications:
web:
runtime: node
source:
root: .
build:
install: [npm, ci]
command: [npm, run, build]
run:
command: [node, dist/server.js]
port: 3000
env:
NODE_ENV: production
API_TOKEN:
secret: api_token
secrets:
api_token:
description: Token the application uses to call its upstream API
required: true
allocation:
applications:
web:
replicas: 1
resources:
cpuRequestMillicores: 250
cpuLimitMillicores: 500
memoryRequestMib: 256
memoryLimitMib: 512
sources:
applications:
web:
repository: example-org/site
ref: main
autoDeploy: false
domains:
- hostname: shop.example.com
application: web
primary: true
dns:
records:
- domain: example.com
name: blog
type: cname
ttl: 3600
values: [shop.example.com.]
email:
domains:
- hostname: example.com
mailboxes:
- localPart: office
quota: gb-5
aliases:
- localPart: sales
destinations: [office@example.com]
access:
requiredSignIn: true
passwordEnabled: false
sftpOnly: true
users:
- email: person@example.com
logins:
- username: deploy
name: Deployment login
readOnly: false
keyRequired: true
passwordRequired: false
grants:
- principalEmail: person@example.com
login: deploy

The pattern's schema is published so your editor can validate it as you type. Like the hosting schemas it is public and immutable, one artifact per format version:

{
"yaml.schemas": {
"https://hosting.haak.co/api/v1/hosting/portable-site/schemas/1.0": "site-pattern.yaml"
}
}

Choosing what an export includes​

An export never widens to everything the company owns. Its selection names the sections and the linked names to include; an omitted field keeps that section's own default, and a section that cannot be represented is reported in the coverage list rather than exported silently:

selection.json
{
"sections": ["hosting", "domains", "dns", "email", "access", "sources"],
"domains": ["shop.example.com"],
"emailDomains": ["example.com"],
"dns": ["example.com"],
"access": true,
"sources": true
}

Binding a pattern to the destination​

Logical names in the pattern mean nothing on the target until you bind them to resources you are authorized to use. A binding maps the pattern's own reference to the target's identifier; a name that merely matches never counts as authorization, and a target the pattern does not bind is reported as unresolved rather than guessed:

bindings.json
{
"bindings": {
"applications": { "web": "<target-application-uuid>" },
"repositories": { "web": "<target-repository-selection-uuid>" },
"domains": { "shop.example.com": "<company-domain-uuid>", "example.com": "<company-domain-uuid>" },
"emailDomains": { "example.com": "<email-domain-uuid>" },
"services": { "cache": "<service-uuid>" },
"siteUsers": { "person@example.com": "<site-user-uuid>" },
"accessUsers": { "deploy": "<access-user-uuid>" },
"members": { "person@example.com": "<company-member-user-uuid>" },
"aliasRecipients": ["external@example.com"],
"loginKeys": { "deploy": "ssh-ed25519 AAAA... deploy@laptop" }
},
"consents": {
"serviceAddition": false,
"emailInvitations": false,
"autoDeploy": false
}
}

A binding always names a target that already exists: an existing workload (applications), the repository selection a source builds from (repositories), a company-owned website name or the customer DNS zone a record set lives in (domains — this pattern needs both shop.example.com and the example.com zone its records sit in), the attached email name (emailDomains), an existing access login (accessUsers), an existing agency site user (siteUsers), the Company member a grant names (members), and every alias destination the pattern does not itself declare (aliasRecipients). A declaration that creates a resource — a new application, mailbox or login — needs no binding, and a name that merely matches a target is never authorization.

loginKeys carries the public half of a key that a declared SFTP/SSH login needs. A key or password value never belongs in the pattern, and a consent left false keeps the consequential operation refused: a pattern that declares autoDeploy: false stays that way unless you say otherwise.

Preview before you apply​

Choose Preview changes to see what your edit would do before anything is applied. The preview shows the normalized document — the same document however you typed it — with the resources it would use, whether every reference resolves, and whether the secrets it declares have values yet.

For container images the preview adds an Inferred section: each port public or private with its ready check, each disk with its storage class, and who may reach whom (api → db). Notices below it say what applying means beyond the document: a new or retained disk, who owns its backups, a stop-start rollout, or a PostgreSQL restart. hostingctl environment configuration preview prints the same.

Then either Save reviewed draft, which records the document without applying it, or Apply reviewed configuration, which submits exactly the reviewed document. A draft changes nothing in your environment until you apply it.

The preview also states what the document commits: how many applications share the environment, the requests and limits they add up to, the sharing ceiling those limits may reach, and how much of each ceiling is already spoken for. A limit is a burst ceiling — past it your application is slowed, not removed — so applications that do not peak together share one, and the ceiling is the purchase with that sharing allowed for. Memory shares far less than CPU, because past a memory limit an application is stopped rather than slowed.

Every review and apply also names where it lands, before anything else: the installation, cluster, company and environment. Read those four names before you confirm — a document reviewed against the wrong cluster is visible there and nowhere else.

Versions​

For worked setup steps and screenshots, see Deploy other application types. Laravel, Ruby and environment-owned database declarations use the same preview/apply path; the target environment reports which runtimes and engines are available. A saved draft still changes nothing live.

version selects the format. Both of these are supported, and each has its own immutable schema:

VersionAdds
1.0An application with a runtime, a build, a run command and declared secrets
1.1Typed database declarations, declared storage volumes, and database, redis and secret runtime references
1.2Several applications and databases in one environment — up to 16 of each — and up to 64 secrets, sharing the environment's storage volume, plus background workers, scheduled commands and one pre-release task per Node application
1.3Declared path routes between the document's own applications, with none (preserve) or strip path handling, plus tls-url and tls-ca-path database fields for a verified MariaDB connection
1.4The laravel runtime on the same immutable-bundle contract as node, and environment-owned databases: a declared database no longer needs an owning application, and a document that declares no applications at all is valid
1.5Named service declarations — a private endpoint an application asks for — and the ruby runtime
1.6The quorum's own password as a redis binding value, and an optional reverb declaration naming the public path its socket is served on
1.7The named sub-minute scheduler mode (mode: sub-minute with intervalSeconds) beside the cron-expression schedule
1.8A secret's non-secret local value, so a local run resolves a harmless default instead of borrowing a production credential
1.9The curated supabase-auth, supabase-rest and supabase-realtime runtimes, declared by runtime only
1.10The per-application cache: block: enabled, freshSeconds, backgroundSeconds and browserMaxAgeSeconds
1.11A declared runtime's phpMinor, so a Laravel application can pin the PHP minor it is built and served on. Renamed in 1.14 — see the runtimeVersion row
1.12A PostgreSQL database's optional extensions selection, so a document can name what the database enables instead of leaving it to the databases API
1.13Declarations tightened; no new field
1.14phpMinor becomes runtimeVersion: one vocabulary for every runtime's version line, not only PHP's
1.15A declared application's documentRoot, its routing (mode, entry, index, fallback, notFound) and a build.lane, so either serving shape and a separate build toolchain can be declared instead of inferred
1.16A declared application's own resources — CPU and memory requests and limits — beside the environment's budget
1.17{storage: …} runtime references to the environment's platform object-storage bucket
1.18Explicit generate-once internal secrets
1.19The top-level buckets: declaration: the platform bucket this environment uses, funded from the storage the package already includes, which the 1.17 references then resolve
1.20A declared client_image application: one published image and the port to route, with an optional connection naming the registry credential it is pulled with
1.21A declared application's own filesGib and a database's storageGib: the physical capacity a document asks for, instead of leaving both at the platform minimum
1.22A declared application's webServer: which of the servers its runtime's recipe declares should serve it. Omit it to keep the current choice (or follow the recipe default for a new application); send null to return to that default
1.23The {application: <key>, field: url} reference: another application's public address, delivered to the web, worker, schedule and release env blocks
1.24An application's resources limits become optional, as a pair. Requests alone let the application share the environment's resources; declaring limits sets a cap for that one application, honoured inside the shared limit. A limit in an earlier version was required, so it is not treated as a cap
1.25Several container images as one system: a container image's run.protocol (any protocol but http is private), up to eight disks per image at any absolute path, its own workers, cron and release, and a container image as a {service: <app>, field: host|port|url} reference target. See Running your own database or engine

Set applications.<key>.webServer in schema 1.22 or later. New Generic PHP applications created from YAML or a repository document default to fpm_nginx. Omission keeps an existing application’s choice. Set webServer: apache for Apache or webServer: null for the recipe default.

The servers a webServer may name are the ones that application's recipe declares — apache, fpm_nginx and, for Generic PHP, frankenphp. A name the recipe does not declare is refused at the field rather than silently served by something else. Confirming the document records what the application should use; it does not by itself confirm which server is answering traffic, which is the environment's own reconciliation and deployment status. Applications describes the shapes and what each one is for.

Each is a Draft 2020-12 JSON Schema. Point your editor at the one you use and it validates as you type, naming the field it refuses rather than leaving you to find out at apply time:

{
"yaml.schemas": {
"https://hosting.haak.co/api/v1/hosting/schemas/1.1": "hosting.yaml"
}
}

Do not put $schema in the document itself — version selects the format.

More than one application​

From version 1.2 an environment can hold several applications — up to 16 — each with its own runtime, build, release history, routes and address, sharing the environment's storage volume, its MariaDB server and its cache. Adding a second application to an existing environment is the cheaper way to run two sites together; creating a second environment gives each one its own host.

Applications in one environment share a host

Sharing an environment is a capacity choice, not an isolation or uptime one. Running applications side by side in one environment means:

  • they restart together. The applications run in the same host Pod, so a change that replaces that Pod — applying configuration, or rolling a release — interrupts the others too. Each application keeps its own release history, and that still does not give it its own uptime;
  • they borrow capacity from each other. Memory and CPU are shared inside one environment envelope, so an application can use capacity an idle neighbour is not using, and can also compete with it when both are busy;
  • the cache is shared and unauthenticated inside the environment. Key prefixes keep applications' keys from colliding; they are not an access boundary between them;
  • they share a host for routing. Requesting one application's path on another application's address discloses that the host is shared and redirects you to the canonical address rather than serving the wrong application.

Choose a separate environment when an application needs independent uptime, its own resource envelope, or a protection boundary rather than shared capacity.

Running more than one copy​

An application normally runs as one container of your environment's shared Pod. Give it two or more replicas and it runs as copies of its own instead, spread across servers, so it keeps serving while one server is being maintained. Updates replace one copy at a time.

  • Each copy reserves its memory outright. Set memoryRequestMib equal to memoryLimitMib; every copy is charged that line from your package, and the shared Pod must still fit beside them.
  • WordPress and Moodle need shared file storage. Every copy serves the same site files, so the environment's application files must be on a storage class every server can mount (CephFS), chosen by name when the environment is created. hostingctl storage-classes lists the classes you may choose, with whether each is shared across servers and encrypted; then hostingctl environment create … --storage-classes application-files=cephfs-hosting-encrypted. An environment whose files are on single-server storage keeps these applications at one copy, and the preview says why.
  • The HTTP cache still serves them. Your environment keeps one cache: every copy sends requests through it, and a purge clears the site once. While the cache itself is moving between servers, each copy serves the site directly, so the site stays up.
  • Moodle's scheduled tasks run once. Its cron runs beside the cache, not in every copy.
  • Encrypted, like all storage. Every storage class you can choose is encrypted at rest.
  • Logs go to the log view, not to a file. Two copies writing one log file can lose lines.

Going back to one copy moves the application back into the shared Pod. Nothing is copied: it serves the same files throughout.

Several applications on one address​

From version 1.3 a document can also declare path routes between its own applications. Each route names the application that publishes the path (source) and the application served there (target), both by configuration key:

version: "1.3"
applications:
web:
runtime: node
source:
root: .
build:
install: [npm, ci]
command: [npm, run, build]
run:
command: [node, dist/server.js]
port: 3000
healthPath: /health
env:
NODE_ENV: production
API_TOKEN:
secret: api_token
storage:
- volume: files
mountPath: /data/web
admin:
runtime: node
source:
root: .
build:
install: [npm, ci]
command: [npm, run, build]
run:
command: [node, dist/admin.js]
port: 3001
healthPath: /health
env:
NODE_ENV: production
API_TOKEN:
secret: admin_token
storage:
- volume: files
mountPath: /data/admin
routes:
admin_path:
source: web
target: admin
path: /admin
rewrite: none
canonical: true
storage:
files:
sizeMib: 2048
secrets:
api_token:
description: Token the web application uses to call its upstream API
required: true
admin_token:
description: Token the admin application uses to call its upstream API
required: true
  • canonical: true selects this path as the served application's own address: it is the address the application is told, and other addresses for that application redirect to it. canonical: false does not deselect an address that is already selected — changing a selected address is one explicit choice, made under Applications.
  • rewrite: none (the default) preserves the path and tells the application its base path, so an application that understands a base path builds matching URLs.
  • rewrite: strip removes the route's path before the request reaches the application, for one that cannot be told — /admin/foo then arrives as /foo. A stripped route must be canonical: it is served directly, so it cannot also be an alias that redirects. Choose per route; the platform does not guess.
  • A route's key is its stable identity. Editing its path, target or rewrite and applying again updates that route; removing a declaration stops managing the route but does not delete it, and deleting a route is the review under Applications.
  • A route's source cannot change. A key names a route on one host; to move it, remove the route and declare it again under the new source.
  • Routes only reach applications declared in the same document. Two routes cannot publish one path on one source, and only one route may be an application's canonical address.
  • Routes may not contain one another on the same source when the outer route is an alias or stripped. Those two are served by a higher-priority rule that would capture the deeper path first, so the deeper route would be unreachable (or an alias would loop). A canonical address that is already selected also cannot be retargeted by editing its declaration; select the replacement address first.

The routes share the host they are published on, so the shared-host warning above applies to them as well.

An example​

A Node application with a database, a private volume, a secret, a cache reference and a health check:

version: "1.1"
applications:
web:
runtime: node
source:
root: .
build:
install: [npm, ci]
command: [npm, run, build]
publicEnv:
NODE_ENV: production
run:
command: [node, server.js]
port: 3000
healthPath: /health
env:
DATABASE_URL:
database: primary
field: url
REDIS_HOST:
redis: host
API_TOKEN:
secret: api_token
storage:
- volume: files
mountPath: /data
databases:
primary:
engine: mariadb
application: web
storage:
files:
sizeMib: 2048
secrets:
api_token:
description: Token the application uses to call its upstream API
required: true

What an environment value may reference​

A value in env is either a literal or a reference. A reference names the thing it wants and the platform delivers the value, so a document never carries an address or a password.

ShapeNamesNeeds a field
{secret: key}A secret this document declaresNo
{database: key, field: name}A database this document declaresYes
{redis: attribute}This environment's own cacheNo
{service: name, field: name}A workload this environment runs, a component it hosts, or (schema 1.25) one of the document's container images: host, port or urlYes

The cache shape names an attribute rather than a store, because the environment has exactly one cache: {redis: url} is the address, and {redis: host} and {redis: port} are its parts.

A field the platform marks as a credential is delivered to the process and never shown back in a browser or an API response. Nothing on this page can list the producers for you either: the answer is per environment, so it is asked for.

One container image reaching another (schema 1.25)​

A reference to another container image is also the network grant: api below may connect to db, and nothing else may. db speaks postgres, so it is private — no route, no public address — and its url is postgres://<host>:5432, with no credentials in it. Its data lives on two disks of its own.

version: "1.25"
applications:
api:
runtime: client_image
image: {registryHost: ghcr.io, repository: acme/api, reference: "2.3.0"}
run: {port: 8080, healthPath: /up}
env:
DATABASE_URL: {service: db, field: url}
cron:
nightly_report: {schedule: "0 2 * * *", command: [bin/report]}
db:
runtime: client_image
image: {registryHost: ghcr.io, repository: acme/postgres, reference: "18"}
run: {port: 5432, protocol: postgres}
env:
POSTGRES_PASSWORD: {secret: db_password}
storage:
- {volume: db_data, mountPath: /var/lib/postgresql}
- {volume: db_dumps, mountPath: /dumps}
storage:
db_data: {sizeMib: 10240}
db_dumps: {sizeMib: 20480}
secrets:
db_password: {description: Password for the postgres user, required: true}

Running your own database or engine covers what Hosting infers, disks and backups.

Listing what an environment may reference​

hostingctl environment references <environment-uuid>

Each entry prints the exact expression to paste. The configuration editor shows the same list beside hosting.yaml, with a copy button per field and a note on every credential-shaped one.

Encrypted and verified database connections​

A MariaDB binding can deliver both forms, so the client chooses:

  • field: url (or the separate host, port, database, user and password fields) is the plaintext connection, unchanged from earlier versions — an existing binding keeps working exactly as it did.
  • field: tls-url is the MySQL-family verified URL: it asks for VERIFY_IDENTITY and names the CA file the application's container already has mounted. field: tls-ca-path delivers that file's path on its own, for a driver that takes a CA file rather than a URL.

Encrypted is not the same as verified. The URL states what to ask for; the session is verified only when the client you configure loads that CA and checks the server name against it. Measured against a throwaway server: the trusted CA on the certified name connects encrypted, an unrelated CA is refused, and a name the certificate does not carry is refused when the client checks it — while the same URL passed on its own, with no CA loaded, connects unencrypted. For the Node driver most applications use, that means:

mysql.createConnection({
host: process.env.DB_HOST, // the certified service name, not an address
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
database: process.env.DB_NAME,
ssl: {
ca: fs.readFileSync(process.env.DB_TLS_CA),
rejectUnauthorized: true,
verifyIdentity: true, // without this the name is not checked
},
});

PostgreSQL already behaves this way through its single url, which carries sslmode=verify-full and the CA path. WordPress cannot verify inside its core database layer, so point your own client or a maintained plugin at these values; Moodle can require encryption but cannot be pointed at this CA file.

Databases an environment owns​

From version 1.4 a declared database does not need an owning application. application and bindings are two different things:

  • application: web is the older single-owner form: the identity is created beside that application, and that application references it;
  • bindings: [web, worker] grants named applications access to a database the environment owns. An application may reference a database it owns or one it is granted, and an owner implicitly holds a grant;
  • a database with neither is environment-owned and referenced by nobody yet. A document that declares no applications at all — applications: {} — is valid, which is how a database is declared without buying a web runtime for it.
version: "1.4"
applications: {}
databases:
reporting:
engine: postgres

One application references one database, owned or granted. Sharing one database between several applications of a single document is declared by granting it to each of them.

Using MySQL​

engine: mysql declares an Oracle MySQL database, created and reached exactly like the PostgreSQL one: the application never receives a host or a password, only a DB_URL binding it references. What changes is the driver name it announces and — when the application has no database-backed session or cache tables of its own — the stores it names instead.

version: "1.4"
applications:
api:
runtime: laravel
source:
root: api
build:
install: [composer, install, --no-dev, --no-interaction, --no-progress, --prefer-dist, --no-scripts]
run:
command: [hosting-laravel-web]
port: 3000
healthPath: /up
env:
APP_KEY:
secret: app_key
DB_CONNECTION: mysql
DB_URL:
database: primary
field: url
MYSQL_ATTR_SSL_CA:
database: primary
field: tls-ca-path
CACHE_STORE: file
SESSION_DRIVER: file
QUEUE_CONNECTION: database
workers:
queue:
command: [php, artisan, queue:work, database, --sleep=1, --tries=1, --timeout=60]
env:
APP_KEY:
secret: app_key
DB_CONNECTION: mysql
DB_URL:
database: primary
field: url
MYSQL_ATTR_SSL_CA:
database: primary
field: tls-ca-path
CACHE_STORE: file
SESSION_DRIVER: file
QUEUE_CONNECTION: database
cron:
scheduler:
schedule: "* * * * *"
timezone: UTC
command: [php, artisan, schedule:run]
timeoutSeconds: 60
env:
APP_KEY:
secret: app_key
DB_CONNECTION: mysql
DB_URL:
database: primary
field: url
MYSQL_ATTR_SSL_CA:
database: primary
field: tls-ca-path
CACHE_STORE: file
SESSION_DRIVER: file
QUEUE_CONNECTION: database
release:
command: [php, artisan, migrate, --force]
timeoutSeconds: 300
env:
APP_KEY:
secret: app_key
DB_CONNECTION: mysql
DB_URL:
database: primary
field: url
MYSQL_ATTR_SSL_CA:
database: primary
field: tls-ca-path
CACHE_STORE: file
SESSION_DRIVER: file
QUEUE_CONNECTION: database
databases:
primary:
engine: mysql
bindings: [api]
secrets:
app_key:
description: Existing or newly generated application encryption key
required: true

DB_CONNECTION: mysql is the PDO driver name Laravel selects, not a second endpoint: the host, port and credentials arrive through the DB_URL binding. Certificate verification is separate, because Laravel loads the CA into its PDO options rather than reading it from a connection string — that is what MYSQL_ATTR_SSL_CA is for, mapped to the database's tls-ca-path field, and why every process in this example declares it beside its DB_URL. The application's own migrations create the jobs and failed_jobs tables the database queue uses. Laravel defaults sessions and cache to the database store, so when the application does not create those tables declare SESSION_DRIVER: file and CACHE_STORE: file as this example does — otherwise the first request fails on a table that was never migrated.

PostgreSQL extensions​

extensions names the optional PostgreSQL extensions a database enables. The platform loads the library each one needs when the cluster starts and enables the extension inside the database, so changing the selection restarts that cluster. pgcrypto is always on and is never listed.

version: "1.12"
applications: {}
databases:
reporting:
engine: postgres
extensions: [pgaudit]

Leaving extensions out is not the same as declaring []. An omission keeps the selection the database already records, so re-applying a document does not remove a choice made earlier; [] asks for the always-on set and no optional extension, and is written back as [] so a save, an export or a review cannot read your intent as silence. A selection on a MariaDB or MySQL database, or a name the platform does not offer, is refused before the apply at document.databases.<key>.extensions. An extension being installed in the database image does not mean Hosting offers it.

What is offered. About 70 extensions, grouped in the panel's picker by purpose: search (pg_trgm, pg_textsearch, rum), vectors (vector, vectorscale), time series and analytics (hll, pg_ivm), geospatial (postgis, pgrouting, h3), data types (hstore, ltree, citext, pg_uuidv7), operations and monitoring (pg_stat_statements, pg_qualstats, hypopg, pgstattuple) and development (pgtap, plpgsql_check). The picker and hostingctl environment database create --extensions list the exact set. Clearing an extension from the selection does not remove it from the database, and the library it needs stays loaded. Extensions that reach outside the database (outbound connections, server files, replication) or need superuser steps are not offered.

TimescaleDB is not offered on the managed server. Its licence does not allow it as part of a database service. To use it, run your own PostgreSQL image as a client-run image under your own Timescale licence; Hosting runs that image but does not manage its backups, upgrades or credentials.

Declared runtimes​

node, laravel and ruby are declared runtimes: the document carries the build, run command, port and any processes, and Hosting builds one immutable release from your source. laravel installs with Composer and answers /up by default; node installs with npm and answers /health; ruby installs with Bundler. Each is served from the runtime image the operator pins, so a runtime with no pinned image is refused at apply time rather than served from an invented one.

From version 1.14 a declared application names the version line it is built and served on, with one field for every runtime rather than a PHP-only one (1.11 to 1.13 called it phpMinor):

applications:
web:
runtime: laravel
runtimeVersion: "8.4"

The line is recorded on that application, not on the environment, so siblings keep their own; a document that names none follows the recipe's default. It is refused by name when the platform publishes no pinned image for that line, or when the line no longer takes new work, rather than accepted and then failing to start. Changing it replaces that application's runtime image, and where several applications share one runtime that replacement interrupts the siblings it serves beside.

runtimeVersion is required for an application whose release is built (node, php, python, laravel, ruby, go, rust, dotnet): its release was compiled by one interpreter and cannot follow a default that may change. A managed runtime (wordpress, moodle) may omit it.

WordPress and Moodle are managed: their documents carry only the runtime — runtime: wordpress or runtime: moodle — and Hosting owns their database, files, settings and layout. A Company Admin declares one in the form or YAML like any other application. A single managed application can be created from the configuration: saving a draft records the document without creating anything, and on review Apply managed application after review (WordPress or Moodle) creates the application.

An existing managed application can instead be adopted by entering its application UUID in Existing application UUID to adopt, which is shown while the environment has no saved configuration revision. Adoption records the identity only: the existing files, database identity, administrator password and database password are preserved, and nothing is reinstalled or restarted by the adoption itself. It is offered only for a document that declares exactly one application, and it must be the same runtime as the workload being adopted — a WordPress document cannot adopt a Moodle application, a workload in another environment or another company cannot be adopted, and a workload already bound to another configuration key cannot be adopted again. See Applications.

Background workers, schedules and release tasks​

A Node, Laravel or Ruby application can declare processes that run beside its web process, all from the same immutable release:

  • a worker runs continuously for as long as the environment is serving. In a shared environment it runs inside the environment's shared resources, like a process on one server, and needs no allowance of its own;
  • a schedule runs a command on a standard five-field cron expression with an explicit IANA timezone (UTC when omitted);
  • the release task runs once per release, after the build and its bindings are ready and before the web and worker processes change.

Schedule runs and the release task use the room the platform keeps for rollouts, so none of these processes takes resources away from your sites while it is not running.

Each process keeps its own env. A process never inherits the web process's values, so a credential one process needs is granted to that process and no other — the same secret, database and redis references are available, and they resolve against the same document.

version: "1.2"
applications:
web:
runtime: node
source:
root: .
build:
install: [npm, ci]
command: [npm, run, build]
run:
command: [node, dist/server.js]
port: 3000
env:
DATABASE_URL:
database: primary
field: url
API_TOKEN:
secret: api_token
workers:
queue:
command: [node, dist/worker.js]
env:
DATABASE_URL:
database: primary
field: url
API_TOKEN:
secret: api_token
cron:
cleanup:
schedule: "0 2 * * *"
timezone: Africa/Johannesburg
command: [node, dist/cleanup.js]
timeoutSeconds: 300
env:
DATABASE_URL:
database: primary
field: url
release:
command: [npm, run, migrate]
timeoutSeconds: 300
env:
DATABASE_URL:
database: primary
field: url
databases:
primary:
engine: mariadb
application: web
secrets:
api_token:
description: Token the application uses to call its upstream API
required: true
version: "1.4"
applications:
api:
runtime: laravel
source:
root: api
build:
install: [composer, install, --no-dev, --no-interaction, --no-progress, --prefer-dist, --no-scripts]
run:
command: [hosting-laravel-web]
port: 3000
healthPath: /up
env:
APP_KEY:
secret: app_key
DB_URL:
database: primary
field: url
QUEUE_CONNECTION: database
workers:
queue:
command: [php, artisan, queue:work, database, --timeout=60]
env:
APP_KEY:
secret: app_key
DB_URL:
database: primary
field: url
cron:
scheduler:
schedule: "* * * * *"
timezone: UTC
command: [php, artisan, schedule:run]
timeoutSeconds: 60
env:
APP_KEY:
secret: app_key
DB_URL:
database: primary
field: url
release:
command: [php, artisan, migrate, --force]
timeoutSeconds: 300
env:
APP_KEY:
secret: app_key
DB_URL:
database: primary
field: url
databases:
primary:
engine: postgres
bindings: [api]
secrets:
app_key:
description: Existing or newly generated application encryption key
required: true

This API-only Laravel example uses the image-owned hosting-laravel-web entrypoint, which serves only public/ and reads the validated port. Its build installs PHP dependencies; declare a separate asset build command only when the source actually has frontend assets. Each process explicitly receives the same application key and its own DB_URL mapping; the web process's environment is not inherited. The application's own migrations must provide the tables its database-backed sessions, cache and queue use. A new Laravel member with No database instead starts with file-backed session/cache settings in the form; existing custom settings and imported declarations are preserved. The default worker drain allowance is 90 seconds. Keep the queue worker timeout (60 seconds in this example) below that allowance and the application’s database queue retry_after, so a stop can finish the current job before it becomes available to another worker.

A schedule that overlaps its own previous run is refused rather than started again: two runs of one command writing the same data is an application bug, not a scheduling preference. A run that exceeds its timeoutSeconds is reported as a timeout, separately from a command that exits with an error.

If the release task fails, the release does not start serving and the healthy release keeps running. timeoutSeconds is your choice beneath a platform ceiling, not a guarantee that the allowance is enough.

A failed release task is not rolled back and is not retried. Hosting runs your command once and reports its exit status, so whatever it committed before it failed is still there. That matters most where schema changes are not transactional: on MySQL, a migration that creates a table and then fails leaves that table behind, and the next attempt stops on it instead of starting clean. Repairs therefore ship as a new release, so write a migration that can be applied to a database its own earlier partial attempt may already have touched — Laravel's Schema::hasTable() guards are the usual way. Resetting an environment's database is an explicit choice you make, and it discards that database's data; Hosting never does it as part of a release.

HTTP cache​

From version 1.10 an application can declare its HTTP cache in the document, so the behaviour that decides what every visitor receives is reviewed, diffed and copied with the rest of the configuration instead of living only in the application's Cache screen:

version: "1.10"
applications:
web:
runtime: node
source:
root: .
build:
install: [npm, ci]
command: [npm, run, build]
run:
command: [node, dist/server.js]
port: 3000
healthPath: /health
cache:
enabled: true
freshSeconds: 300
backgroundSeconds: 60
browserMaxAgeSeconds: 60
FieldMeansAllowed
enabledWhether this application is served through the cache. Required — a block always states the switchtrue or false
freshSecondsHow long a stored response is reused before it is fetched again0–300
backgroundSecondsHow long an expired response may still be served while one request refreshes it0–60
browserMaxAgeSecondsThe browser's own reuse window, sent as Cache-Control on a response the cache stored0–86400

An omitted bound follows the platform default; it is not zero. The two mean different things: omitting freshSeconds keeps the platform's own lifetime, while freshSeconds: 0 is you saying "store nothing for a request no rule matches". Omitting browserMaxAgeSeconds sends no override at all, so your application's own Cache-Control reaches the browser untouched.

What the block does and does not carry. These four knobs are the whole block. There is no raw VCL and no per-route cache fragment, because a free-text VCL body would be an unbounded way around the cache's own limits, and a second place to describe a path is how two descriptions start disagreeing. The cache's rules — which paths are stored and how each is treated — stay in the application's Cache screen.

Applying a block is the same change as saving that screen. It writes the same stored settings through the same validation, so the two surfaces cannot describe two different caches, and what the block changes is reconciled like any other change. Two consequences worth knowing before you write one:

  • your custom rules are left alone. The document declares none. A sole platform origin policy follows the document's lifetimes only while its complete shape and lifetimes still match the current site settings or defaults; a changed path, action, hostname or lifetime remains your custom policy;
  • enabling with no rule at all declares a safe origin policy for you, because a cache that stores nothing is a switch that does nothing. That policy respects your application's own Cache-Control on every path, so only a response your application marks public is stored. Its lifetimes follow the four settings above, including zero freshness and later document changes. A response that sets a cookie is never stored, so a visitor's own session is never shared with anyone else. A cache: {enabled: false} block declares no policy at all — switching the cache off asks for nothing to be stored.

The cache is served by a sidecar inside your environment's shared Pod, and enabling it is refused when its request cannot fit inside that Pod's ceiling, rather than silently taking resources from your application.

Environment references​

A value under an application's env is either a literal string or a reference to something Hosting owns, which is how a credential reaches an application without being written into the document:

ReferenceMeans
{secret: api_token}A secret declared under secrets. Its value is written separately, and never appears in the document or in a preview.
{database: primary, field: url}One field of a database declared under databases: host, port, database, user, password, url, tls-url or tls-ca-path. The database must belong to that same application, or be granted to it with bindings.
{redis: host}The environment's cache: host, port or url.
{storage: endpoint}From schema 1.17, the environment's bound platform bucket: endpoint, region, bucket, access-key-id or secret-access-key.

Platform storage references require exactly one ready, non-retired bucket bound to this environment in your company — either the bucket buckets: declares (schema 1.19, below) or one you bound yourself. Native access is sufficient; no mount is needed. Package-assigned capacity counts even when purchased capacity is zero. A missing, ambiguous or unfunded binding is refused by variable name. There is no bucket selector in the document, and the reference never creates or rotates a key. The existing active client credentials reach only the workload Secret, never the document or preview. The form labels retained storage fields read-only; author the references in YAML or JSON, or explicitly change their type to replace them.

The bucket the document declares (schema 1.19)​

A document can name the platform bucket its environment uses, and fund it out of the storage the package already includes:

version: "1.19"
buckets:
assets:
packageGib: 10

The key is the bucket's name inside your company, so applying the document twice uses the same bucket instead of buying another. packageGib is whole GiB assigned from your package — the declaration never buys capacity, so it adds no STO line and opens no capacity period. Applying the document founds the bucket if it does not exist, sets the assignment to the declared quantity, and records this environment's native access path, in that order; an apply that finds all three already true writes nothing. One bucket per environment, because the {storage: …} references resolve the environment's single binding.

Removing the declaration is not a deletion: the bucket, its objects, its assignment and its binding stay exactly as they were. Bought capacity stays a priced operation (hostingctl storage add), and a bucket that pays for what it stores, or one that has been retired, is refused by the declaration's own name instead of being converted.

env:
S3_ENDPOINT: {storage: endpoint}
S3_REGION: {storage: region}
S3_BUCKET_NAME: {storage: bucket}
S3_ACCESS_KEY_ID: {storage: access-key-id}
S3_SECRET_ACCESS_KEY: {storage: secret-access-key}

Build-time values under build.publicEnv must be literal strings — a build cannot read a secret from your environment. They are public by definition and are visible to anything that can ask for the document.

What is checked before it is applied​

  • the document parses at a supported version, without unknown or misspelled fields;
  • every secret, database, storage and redis reference resolves within the same document;
  • the requested CPU, memory and storage fit what the environment has purchased — an application that would overspend is refused rather than accepted and reconciled afterwards;
  • application and database counts in standard packages depend on purchased resources, with no fixed count ceiling; Low End packages retain their fixed count limits;
  • from 1.4 a database names an owner, or the applications granted access to it, or neither;
  • every declared route names two applications in the same document, publishes a path no other route already publishes on its source, and leaves each served application at most one canonical address;
  • declared secrets that are required have a value before the document is applied.
  • every cache bound is within the range the cache engine can honour, refused at the field that is out of range rather than at render time.

A document that fails any check is refused with the field that failed. Nothing is applied, and nothing in your environment changes. The target environment reports which database engines are available; add the required engine under Services before applying a declaration that needs it.

Next​