Skip to content
Phero Lang
Menu

.deploy

Deployment

Components, profiles and targets

Validated

No in-tree backend — the artifact is validated and committed, not consumed.

Deployment projections: application components, target capabilities and engines, profiles, settings, and type-checked placement policies.

Why it exists

What .deploy is for

A .deploy file is a projection, not a new architecture: it declares a logical application of named components and their connects, reusable profiles (a target plus defaults, policies and resource mappings), and deployments that project one application through one profile with configure overrides.

Targets are implementation-provided, never authored: a profile names one of the closed targets, and the driver’s capability, engine and setting tables define what each can host. Incompatibility is a compile error, not a generated artifact — validate before generating. The effective configuration is component baselines ⊕ profile defaults ⊕ overrides, later levels winning.

Vocabulary

What it models

The concepts .deploy declares, and what each one means to the compiler.

application
The logical architecture: components and connects. Nothing here says where anything runs.
component
A named unit with a kind (api, frontend, database), settings, environment and bindings.
design / flow
A component bound to a .ddd module or an .ifml flow by the import path as written plus the entry name.
connects
A directed relationship between two components (connects web -> api).
profile
target, defaults, mappings, and require / prohibit policies. Profiles are reusable across applications.
target
One of the closed targets: standalone, dockerCompose, kubernetes, cloudflareWorkers.
deployment
use <profile> plus configure overrides: the concrete projection.
settings
Typed values addressed by path (api.replicas: 3), checked against the target’s setting table.
policies
phero-expr conditions over the effective settings, evaluated against baselines, defaults and overrides.

Source

A working example

Quoted from the example this page's artifact was compiled from — not a snippet written for the website.

Lines 10–30 of examples/support/support.deploy, reproduced byte for byte, read from the file at build time:

examples/support/support.deploy · lines 10–30
application SupportDesk {
    component api: api {
        design "support.ddd#desk"
        scaling: autoscaled
        port: 18082
        env {
            LOG_LEVEL = "info"
        }
    }
    component web: frontend {
        flow "support.ifml"
        entrypoint: "src/inbox.ts"
    }
    component db: database {
        storage: managed
    }
    component refund_approval_service: api {}
    component analytics_service: api {}
    connects web -> api
    connects api -> db
}

The logical application: an `api` component bound to the `desk` design module, a `frontend` bound to the flow, a managed database, and the `connects` that wire them.

The whole file is CI-tested: pherolang check examples/ checks every surface in the tree, and the example harness compiles each one on every run. What you see above is the input to the artifact below.

Neighbours

How it relates to the other surfaces

A deployment model composes the other artifacts: it imports pre-compiled .ddd designs and .ifml flows and binds components to them by path. The .mox domain and .actor policy reach it only through the design it projects — the model carries authored intent only, never containers, manifests or clouds.

Read alongside

Commands

How to compile and validate

Three commands, one file. They run from the repository root against the example on this page.

bash
pherolang check examples/support/support.deploy
pherolang ir examples/support/support.deploy -o site/data/artifacts/deploy.json
pherolang artifact check site/data/artifacts/deploy.json

check parses, resolves, validates and type-checks the file and printsOK examples/support/support.deploy. ir writes the artifact and prints nothing on success. artifact check then validates the serialized JSON on its own — no model, no import resolution, no compiler — and prints OK site/data/artifacts/deploy.json.

Directories work too: pherolang check examples/ enters project mode and checks every supported surface under the tree, each file's imports resolving from the snapshot.

Artifact

What it produces

One versioned JSON artifact, emitted by the compiler and consumed by whatever reads this surface.

One DeployModel: applications with their components and connections, the profiles, and the deployments that project them.

The artifact is site/data/artifacts/deploy.json, and it is committed here exactly as the released pherolang binary emits it. Its top-level shape:

  • applications1 entry
  • profiles2 entries
  • deployments2 entries

Jump to the compiled artifact

Provenance

formatVersion = 2
The compatibility gate. A reader accepts this number or refuses the file.
pheroVersion — not present
This standalone surface artifact is versioned on its ownformatVersion; only the domain model artifact carries the compiler-version stamp.
4,133 bytes
206 lines, two-space indented, in the file's own key order.

The compiled artifact

The first 56 of 206 lines, verbatim — the exact bytes pherolang ir writes, not a hand-written sample. The slice stops at a JSON boundary; the ellipsis marker is outside the JSON, and the full file is site/data/artifacts/deploy.json.

artifacts/deploy.json · lines 1–56
{
  "formatVersion": 2,
  "applications": [
    {
      "name": "SupportDesk",
      "components": [
        {
          "name": "api",
          "kind": "api",
          "settings": [
            {
              "path": "scaling",
              "value": {
                "type": "word",
                "value": "autoscaled"
              }
            },
            {
              "path": "port",
              "value": {
                "type": "int",
                "value": 18082
              }
            }
          ],
          "designs": [
            {
              "source": "support.ddd",
              "module": "desk"
            }
          ],
          "env": [
            {
              "name": "LOG_LEVEL",
              "value": "info"
            }
          ]
        },
        {
          "name": "web",
          "kind": "frontend",
          "settings": [
            {
              "path": "entrypoint",
              "value": {
                "type": "text",
                "value": "src/inbox.ts"
              }
            }
          ],
          "flows": [
            {
              "source": "support.ifml"
            }
          ]
        },

… 150 more lines in site/data/artifacts/deploy.json

Regenerate it from the repository root — the second command validates the serialized bytes with no compiler in the loop:

bash
pherolang ir examples/support/support.deploy -o site/data/artifacts/deploy.json
pherolang artifact check site/data/artifacts/deploy.json

The whole data directory is regenerated by node scripts/sync-model.mjs (run from site/) with the released binary; CI fails on a one-byte difference.

Reference

Documentation

The normative reference for this surface, rendered from the repository's own documentation.

docs.pherolang.com

Deployment reference

The complete .deploy reference — vocabulary, grammar, validation rules, artifact wire format, and the CLI contract.

Generated from docs/DEPLOY.md in the repository. The page above summarises it; the reference is normative.