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.

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:
- 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.
- Edit the YAML's logical names and public settings for the destination. A portable pattern has its
own
version; its nestedhostingdocument keeps the existing hosting format version. - 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.
- 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.
- 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.
- 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:
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:
{
"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": {
"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:
| Version | Adds |
|---|---|
1.0 | An application with a runtime, a build, a run command and declared secrets |
1.1 | Typed database declarations, declared storage volumes, and database, redis and secret runtime references |
1.2 | Several 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.3 | Declared 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.4 | The 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.5 | Named service declarations — a private endpoint an application asks for — and the ruby runtime |
1.6 | The quorum's own password as a redis binding value, and an optional reverb declaration naming the public path its socket is served on |
1.7 | The named sub-minute scheduler mode (mode: sub-minute with intervalSeconds) beside the cron-expression schedule |
1.8 | A secret's non-secret local value, so a local run resolves a harmless default instead of borrowing a production credential |
1.9 | The curated supabase-auth, supabase-rest and supabase-realtime runtimes, declared by runtime only |
1.10 | The per-application cache: block: enabled, freshSeconds, backgroundSeconds and browserMaxAgeSeconds |
1.11 | A 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.12 | A PostgreSQL database's optional extensions selection, so a document can name what the database enables instead of leaving it to the databases API |
1.13 | Declarations tightened; no new field |
1.14 | phpMinor becomes runtimeVersion: one vocabulary for every runtime's version line, not only PHP's |
1.15 | A 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.16 | A 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.18 | Explicit generate-once internal secrets |
1.19 | The 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.20 | A 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.21 | A 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.22 | A 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.23 | The {application: <key>, field: url} reference: another application's public address, delivered to the web, worker, schedule and release env blocks |
1.24 | An 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.25 | Several 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 |
- version
1.0: hosting.haak.co/api/v1/hosting/schemas/1.0 - version
1.1: hosting.haak.co/api/v1/hosting/schemas/1.1 - version
1.2: hosting.haak.co/api/v1/hosting/schemas/1.2 - version
1.3: hosting.haak.co/api/v1/hosting/schemas/1.3 - version
1.4: hosting.haak.co/api/v1/hosting/schemas/1.4 - version
1.5: hosting.haak.co/api/v1/hosting/schemas/1.5 - version
1.6: hosting.haak.co/api/v1/hosting/schemas/1.6 - version
1.7: hosting.haak.co/api/v1/hosting/schemas/1.7 - version
1.8: hosting.haak.co/api/v1/hosting/schemas/1.8 - version
1.9: hosting.haak.co/api/v1/hosting/schemas/1.9 - version
1.10: hosting.haak.co/api/v1/hosting/schemas/1.10 - version
1.11: hosting.haak.co/api/v1/hosting/schemas/1.11 - version
1.12: hosting.haak.co/api/v1/hosting/schemas/1.12 - version
1.13: hosting.haak.co/api/v1/hosting/schemas/1.13 - version
1.14: hosting.haak.co/api/v1/hosting/schemas/1.14 - version
1.15: hosting.haak.co/api/v1/hosting/schemas/1.15 - version
1.16: hosting.haak.co/api/v1/hosting/schemas/1.16 - version
1.17: hosting.haak.co/api/v1/hosting/schemas/1.17 - version
1.18: hosting.haak.co/api/v1/hosting/schemas/1.18 - version
1.19: hosting.haak.co/api/v1/hosting/schemas/1.19 - version
1.20: hosting.haak.co/api/v1/hosting/schemas/1.20 - version
1.21: hosting.haak.co/api/v1/hosting/schemas/1.21 - version
1.22: hosting.haak.co/api/v1/hosting/schemas/1.22 - version
1.23: hosting.haak.co/api/v1/hosting/schemas/1.23 - version
1.24: hosting.haak.co/api/v1/hosting/schemas/1.24 - version
1.25: hosting.haak.co/api/v1/hosting/schemas/1.25
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.
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
memoryRequestMibequal tomemoryLimitMib; 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-classeslists the classes you may choose, with whether each is shared across servers and encrypted; thenhostingctl 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: trueselects 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: falsedoes 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: stripremoves the route's path before the request reaches the application, for one that cannot be told —/admin/foothen 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
keyis its stable identity. Editing itspath,targetorrewriteand 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
sourcecannot 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.
| Shape | Names | Needs a field |
|---|---|---|
{secret: key} | A secret this document declares | No |
{database: key, field: name} | A database this document declares | Yes |
{redis: attribute} | This environment's own cache | No |
{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 url | Yes |
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 separatehost,port,database,userandpasswordfields) is the plaintext connection, unchanged from earlier versions — an existing binding keeps working exactly as it did.field: tls-urlis the MySQL-family verified URL: it asks forVERIFY_IDENTITYand names the CA file the application's container already has mounted.field: tls-ca-pathdelivers 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: webis 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(UTCwhen 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
| Field | Means | Allowed |
|---|---|---|
enabled | Whether this application is served through the cache. Required — a block always states the switch | true or false |
freshSeconds | How long a stored response is reused before it is fetched again | 0–300 |
backgroundSeconds | How long an expired response may still be served while one request refreshes it | 0–60 |
browserMaxAgeSeconds | The browser's own reuse window, sent as Cache-Control on a response the cache stored | 0–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-Controlon 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. Acache: {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:
| Reference | Means |
|---|---|
{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,storageandredisreference 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.4a database names an owner, or the applications granted access to it, or neither; - every declared
routenames 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
requiredhave a value before the document is applied. - every
cachebound 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
- What the applications in your environment are: Applications.
- Give an application an address you own: Web addresses.
- Read or change its database: Databases.
- Change what the cache stores, path by path: Cache your site.