.iec.yaml — Builder Config

An optional file placed at the repo root that tells iec-builder how to locate and build your service. Most services don't need it. You need it when your service is in a subdirectory (monorepo pattern), uses a non-standard Dockerfile, or needs a custom Helm chart.

NOTE: .iec.yaml lives at the repo root — not inside your service subdirectory. For the monorepo pattern, catalog-info.yaml lives inside the service subdirectory.

All Fields

# .iec.yaml (repo root)
appPath: web           # service root relative to repo root (monorepo)
dockerfile: Dockerfile # Dockerfile path relative to appPath (default: Dockerfile)
buildContext: ../..    # Docker build context relative to appPath (default: appPath itself)
helmChart: helm/       # Custom Helm chart path relative to appPath

All fields are optional. An empty .iec.yaml (or no file at all) means: service root = repo root, auto-generate Dockerfile, use repo root as build context, use platform default Helm chart.

Monorepo Pattern

The most common use case. You have one repo with multiple services in subdirectories, or a service lives in a subdirectory (e.g., web/):

my-repo/
  .iec.yaml              ← tells builder: service is in web/
  web/
    .tawa.yaml           ← written by tawa link
    catalog-info.yaml    ← your service declaration
    package.json
    src/

.iec.yaml:

appPath: web

With appPath: web, the builder:

• Reads catalog-info.yaml from web/catalog-info.yaml
• Uses web/ as the Docker build context
• Looks for web/Dockerfile (or auto-generates one)
• Resolves Helm chart relative to web/

Setup Workflow

# From the service subdirectory
cd web/
tawa link          # registers service, writes web/.tawa.yaml

# Deploy (also from service subdirectory)
tawa deploy

TIP: You run tawa link and tawa deploy from the service subdirectory — the builder reads .iec.yaml from the repo root automatically.

Custom Dockerfile

If your Dockerfile is not at {appPath}/Dockerfile:

# .iec.yaml
appPath: web
dockerfile: docker/Dockerfile.prod

The path is relative to appPath (or repo root if no appPath).

Custom Build Context

If your Docker build context needs to reach outside the service directory (e.g., shared packages at the repo root):

# .iec.yaml
appPath: apps/my-service
buildContext: ../..     # relative to appPath — resolves to repo root

WARNING: Build context paths are evaluated relative to appPath, not the repo root. ../.. from apps/my-service means the repo root.

Custom Helm Chart

Use your own Helm chart instead of the platform default:

# .iec.yaml
appPath: web
helmChart: helm/       # relative to appPath

Most services should use the platform default Helm chart. Custom charts are only needed for advanced K8s configurations.

Relationship to .tawa.yaml

.iec.yaml and .tawa.yaml serve different purposes:

Don't put builder config in .tawa.yaml — the builder only reads .iec.yaml for these settings.

Key Facts

• Builder auto-discovers .iec.yaml from the repo root on every build — no CLI flags needed
• appPath shifts ALL of: catalog-info.yaml lookup, Docker build context, Dockerfile path, Helm chart resolution
• If both .iec.yaml appPath and service.appPath (from DB) are set, .iec.yaml wins
• For single-service repos with service at root: no .iec.yaml needed at all
• For multi-service repos: each service needs its own .iec.yaml with different appPath values — but this requires separate .tawa.yaml registrations too (one per service)

Common Mistakes

• Putting .iec.yaml inside the service subdirectory — it must be at the repo root
• Setting buildContext thinking it's relative to the repo root — it's relative to appPath
• Confusing .iec.yaml with .tawa.yaml — they are separate files with different purposes
• Using buildContext: web when appPath: web already sets the build context — don't set both unless you need the context to differ from appPath