Blueprint reference

A blueprint is one YAML file that describes your env groups, your datastores and your services. Ferry reads the render.yaml format of Render, with its camelCase keys, and adds a few keys of its own.

An apply creates what is not there and updates what changed. It never deletes.

An exampleCopy Anchor Link

envVarGroups:
  - name: shared-settings
    envVars:
      - key: APP_ENV
        value: production

databases:
  - name: app-db
    postgresMajorVersion: "16"
    databaseName: app
    user: app
    plan: basic-256mb        # 256 MiB of memory

services:
  - type: redis
    name: cache
    plan: starter            # 256 MiB of memory

  - type: web
    name: hello
    runtime: image
    image:
      url: nginx:alpine
    port: 80
    healthCheckPath: /
    numInstances: 2
    plan: starter            # 512 MiB / 0.5 CPU per instance
    envVars:
      - fromGroup: shared-settings
      - key: DATABASE_URL
        fromDatabase:
          name: app-db
          property: connectionString
      - key: REDIS_URL
        fromService:
          type: redis
          name: cache
          property: connectionString
      - key: SESSION_SECRET
        generateValue: true

  - type: cron
    name: nightly
    runtime: image
    image:
      url: busybox:stable
    schedule: "0 3 * * *"
    startCommand: echo "nightly job ran at $(date)"
    memoryLimit: 64M         # per run
    cpuLimit: 250m

This file describes one env group, one Postgres database, one Redis datastore, one web service with two instances and one cron job. The web service gets the URLs of the two datastores and a random secret.

Apply a blueprintCopy Anchor Link

Do a dry run first. It shows the changes and writes nothing.

ferry blueprint apply --dry-run   # show what would change
ferry blueprint apply             # apply ./ferry.yaml, else ./render.yaml
ferry blueprint apply infra/render.yaml

The first apply of the example creates each resource. Then it puts a deploy in the queue for each service that has a source:

Applied blueprint examples/blueprint/ferry.yaml

Created:
  + env group shared-settings
  + datastore app-db
  + datastore cache
  + service hello
  + service nightly

Queued deploys:
  dep-3271cdfd1415400d9a5e  hello (blueprint, queued)
  dep-0fe672f0b3a4486991a9  nightly (blueprint, queued)

Follow a deploy with: ferry logs --deploy <id> -f

What an apply changesCopy Anchor Link

• Ferry checks the full file before it writes. If one entry is not valid, the apply stops with an error and the server does not change.
• Ferry writes the env groups, then the datastores, then the services.
• Ferry deletes nothing. A resource or a variable that you remove from the file stays on the server.
• A second apply of the same file changes nothing. Ferry keeps each generated secret.
• Ferry runs one apply at a time. An apply continues to its end when the client disconnects.

A service that is not in the file restarts too when it links to an env group that the apply changed. Ferry does not deploy or restart a suspended service. The apply gives a warning: resume the service to apply the changes.

Top-level keysCopy Anchor Link

Ferry ignores each other top-level key with a warning. This includes the x- keys that hold a YAML anchor. The anchor continues to work.

Ferry keeps each value as you wrote it: 3.10 stays 3.10 and 0123 stays 0123. A boolean is true, false, yes, no, on, off, 1 or 0. The same key two times in one block is an error.

ServicesCopy Anchor Link

Each entry of services needs a type and a name. All other keys are optional.

Keys of a serviceCopy Anchor Link

The default runtime is image when the entry has an image, and static for a static site. For other entries, Ferry finds the runtime from your files. If the CLI runs on the server, repo can also be a path relative to the blueprint file, such as ./api. The CLI changes it into an absolute path.

Some keys work only on some types:

• healthCheckPath: web services, private services and static sites.
• schedule: cron jobs only.
• disk: web services, private services and workers, with 1 instance. Ferry accepts disk.name and disk.sizeGB and does not use them.
• domains: web services and static sites.

DatastoresCopy Anchor Link

PostgresCopy Anchor Link

Each entry of databases creates one Postgres datastore with the image postgres:<version>-alpine.

RedisCopy Anchor Link

An entry of services with type: redis or type: keyvalue creates a Redis datastore. Render calls it a key value store. Ferry reads only type, name, plan, memoryLimit and cpuLimit.

Ferry runs redis:7-alpine with a password, append-only persistence and a maxmemory of 3/4 of the memory limit.

A datastore that existsCopy Anchor Link

After the first apply, an apply changes only the limits of a datastore. If postgresMajorVersion, databaseName or user is different, the apply continues with a warning:

database 'app-db': postgresMajorVersion '17' differs from the existing '16'; datastores are not changed in place (ignored)

Plans and limitsCopy Anchor Link

Each container gets a memory limit and a CPU limit. A plan gives them. The Ferry keys memoryLimit and cpuLimit replace the values of the plan, one key at a time.

The limits apply to each instance and to each run of a cron job. A static site has no plans: Ferry ignores its plan with no warning, but memoryLimit and cpuLimit apply.

The plan of a datastore sets the memory only:

Ferry ignores the case and the separator of a plan name: pro plus, Pro_Plus and pro-plus are the same plan. An unknown plan sets nothing and gives a warning.

The value 0 gives the server default. A value that Ferry cannot read, or a value out of the range, stops the apply.

With no plan and no key, a new resource gets the server defaults: --default-memory-limit and --default-cpu-limit of ferryd. A resource that exists keeps its limits.

Env vars and env groupsCopy Anchor Link

envVars is a list. Each entry has one form only:

An entry with two sources is an error. If a key is two times in the list, the last entry wins, with a warning. One value has 32 KiB at most. The variables of one service or group have 256 KiB at most together. Without a type, fromService looks for the name in the services and in the datastores.

Reference propertiesCopy Anchor Link

Web services, private services and static sites have a port.

envVarGroupsCopy Anchor Link

Each entry of envVarGroups creates one env group. A service links to it with fromGroup.

The own variables of a service win over the variables of its groups. A group with a later link wins over a group with an earlier link.

Differences from render.yamlCopy Anchor Link

Most render.yaml files apply with no change. A key that Ferry does not support is never an error: Ferry ignores it with a warning, such as service 'api': ignoring unsupported key 'region'.