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 two ways to write it, and both produce the same document:

• Form builds it from fields;
• YAML lets you write or paste the document itself.

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.

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.

Versions

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

• version 1.0: hosting.haak.co/api/v1/hosting/schemas/1.0
• version 1.1: hosting.haak.co/api/v1/hosting/schemas/1.1

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.

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

WordPress and Moodle are managed: their documents carry only the runtime, and Hosting owns their database, files, settings and layout. They are created for you during onboarding rather than written here — see Applications.

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 or url. The database must belong to that same application.
{redis: host}	The environment's cache: host, port or url.

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;
• in these versions an environment holds one application, one database and one volume, declared for that application;
• declared secrets that are required have a value before the document is applied.

A document that fails any check is refused with the field that failed. Nothing is applied, and nothing in your environment changes. MariaDB is the database engine in use today; the schema also names other engines, which are not available yet.

Next

• What the applications in your environment are: Applications.
• Give an application an address you own: Domains.
• Read or change its database: Databases.