Devfile

Orchard supports the Devfile specification as an alternative to devcontainers. If your repository contains a devfile.yaml, Orchard can use it to define the development environment inside each grove.

How It Works

When you plant a grove with --spec devfile (or when no devcontainer.json is present), Orchard:

Discovers devfile.yaml in your repository (devfile.yaml, devfile.yml, .devfile.yaml, or .devfile.yml)
Provisions a VM (seedling) with Docker installed
Parses the Devfile and maps container components to seeds
Starts the containers and runs lifecycle commands

Discovery Order

Orchard searches for Devfile in this order:

devfile.yaml
devfile.yml
.devfile.yaml
.devfile.yml

What's Supported

Schema Version

Devfile schema version 2.x is supported.

Container Components

Orchard maps Devfile containerComponents to grove seeds:

Devfile Field	Orchard Mapping
`image`	Container image
`name`	Component name
`env[]`	Container environment variables
`endpoints[].targetPort`	Forwarded ports
`memoryLimit` / `memoryRequest`	Memory limits
`cpuLimit` / `cpuRequest`	CPU limits

Lifecycle Commands

Orchard supports exec-type lifecycle commands via Devfile events:

Event	When It Runs
`preStart`	Over SSH on the seedling host, before containers start
`postStart`	Via `docker exec` inside the container, after it starts

Multiple command IDs for a single event are composed into a sequential shell line with &&.

Example devfile.yaml:

code

schemaVersion: 2.2.0
metadata:
  name: my-project
components:
  - name: app
    container:
      image: node:20
      endpoints:
        - name: app
          targetPort: 3000
      env:
        - name: NODE_ENV
          value: development
commands:
  - id: install
    exec:
      component: app
      commandLine: npm install
      group:
        kind: build
  - id: start-app
    exec:
      component: app
      commandLine: npm start
      group:
        kind: run
events:
  postStart:
    - install

What's Not Supported

kubernetes / openshift component types (tracked in orchard#86)
apply / composite command types

Precedence

When a repository contains both devcontainer.json and devfile.yaml, Orchard prefers devcontainer.json by default. Override with --spec:

code

# Force devfile spec
trowel grove plant https://github.com/your-org/your-repo --spec devfile

Next Steps

See the Devcontainer docs for the primary environment spec
Browse the Devfile spec for the full configuration reference

Devcontainers

REST API Reference