Configuration reference

A repository’s environments live in one file, replicator.config.ts, which also declares the secrets it reads. This page lists every option of it. Environments is the guide with the reasoning; Examples has complete files; The command line has the verbs that run them.

import { replicator } from "@clankernet/replicator";

export default replicator.app({
  name: "acme",
  stages: { staging: {}, production: {} },
  run(ctx) {
    return { stage: ctx.stage };
  },
});

The file imports the framework and nothing underneath it; the engine reads it with its own copy of the framework, so the repository installs nothing.

replicator.app({ … })

Stages

stages maps a stage name to its options:

Previews

A preview is never protected and holds nothing that outlives it. The pattern may not be named like production or a protected stage, and no listed stage may match it. Each refusal names its rule: preview-pattern, preview-ttl, preview-protected or preview-collision.

dependsOn

Each entry names one plain output of another app, so the engine can read it before the stage runs:

The context: ctx

run(ctx) receives:

run may return the reserved key __env, a flat record of environment names to strings: it is written to the file infra deploy --env-out names and is never an output.

replicator.hostnames(zone, stage, rules?)

Returns a function host(sub?) that gives each stage its names inside one zone.

host() is the apex or the stage’s own name; host("api") adds one DNS label.

Presets

Plain functions you call at the top of run(ctx); each applies to every resource declared after it.

replicator.transform(type, edit) is the primitive underneath: type is a provider’s type token or a regular expression, and edit({ type, name, props, opts }) returns the props or opts to use instead, or nothing. A rule lives for one stage’s run only.

Components

Every component takes a logical name first: new replicator.Bucket("uploads", { … }). The logical name keys the resource in the stage’s state, so renaming it replaces the resource.

StaticSite

Output: url. The site’s content is published from the config’s static block, not by this component.

Worker

bindings, each as binding name: what it points at:

A migration is { tag, newClasses?, newSqliteClasses?, deletedClasses?, renamedClasses?: { from, to }[] }. Add one to the end whenever the exported classes change; never edit or reorder the ones already there. A binding name used twice is an error. Output: scriptName.

Bucket

Output: name.

DnsRecord

GeneratedSecret

Member: value, a secret other components may read. It is never an output.

SecretsStore

Outputs: storeId, secretName.

Hyperdrive

Outputs: id, name.

Database

The Postgres component: one project with its first database and role, protected by default.

Plain members: host, pooledHost, database, user. Secret members, never to be returned from run: password, uri.

Server

Output: ip.

The secrets block

secrets in replicator.app declares the stored values the environments read. replicator infra secrets check lists the required names a stage lacks; replicator infra secrets ensure stores them; infra diff and infra deploy refuse a stage that lacks one; replicator doctor checks the block against what the config reads, and ctx.secret of a name outside the block is an error. An app without a secrets block is not checked up front, and any name may be read.

export default replicator.app({
  name: "acme",
  stages: { staging: {}, production: {} },
  secrets: {
    sessionKey: { description: "Signs sessions", generate: "random-hex-32" },
    zoneId: { description: "The DNS zone's id" },
    analyticsKey: { required: false },
  },
  run(ctx) {
    /* … */
  },
});

An unknown key is an error (a typo would otherwise be ignored), and a generated value cannot also be optional.

An older repository may declare the same list in secrets.schema.json (a JSON Schema with required, x-generate and x-optional) beside its config. It is still read when the config has no secrets block; with a block, replicator doctor says the file is ignored. Move the names into the block and delete the file.

The values file for ensure --values-file <file> holds NAME=value lines (blank lines and lines starting with # are skipped). The file must be readable by its owner only: a file that group or others can read, or a link, is refused before any of it is read. A name the block does not declare, a repeated name and an empty value are errors, reported by line number and never by value. A name the stage already holds is kept, so running ensure again never rotates a key.

The host owner’s policy

The host owner’s fleet file may carry a policy: block, checked on every infra diff, infra deploy and infra drift that is given --policy <fleet file>. Each refusal names its rule.

Without the block only the built-in rules apply: no data resource or DNS record is deleted or replaced unless named with --allow-destroy, and on a protected stage nothing is deleted at all.