Configuration

Complete reference for fuku.yaml — services, tiers, profiles, and more.

Generate a config template with fuku init, or create fuku.yaml manually in your project root.

Services

Each service is defined with a name, directory, and optional settings:

services:
  backend:
    dir: backend               # Path to service directory
    tier: platform              # Startup tier (optional)
    readiness:                  # Health check (optional)
      type: http
      url: http://localhost:8080/health
      timeout: 30s
      interval: 500ms
    logs:                       # Log output filter (optional)
      output: [stdout, stderr]
    watch:                      # Hot-reload config (optional)
      include: ["**/*.go"]
      ignore: ["**/*_test.go"]
      shared: ["pkg/common"]
      debounce: 1s

Field	Description
`dir`	Path to the service directory (must contain a Makefile with a `run` target)
`tier`	Startup tier for ordering. Services without a tier go to the `default` tier (runs last)
`readiness`	Health check configuration (see Features)
`logs.output`	Output streams to capture: `stdout`, `stderr`, or both (default: both)
`watch`	Hot-reload file watching configuration (see Features)

Tiers

Tiers control startup ordering. Services in earlier tiers start (and become ready) before later tiers begin. The order is determined by the first occurrence of each tier name in your config.

Common tier naming pattern:

foundation — base infrastructure (databases, message queues)
platform — business logic services
edge — client-facing services

Key points:

Tier order is defined by first appearance in the YAML file
Services within each tier are sorted alphabetically by name
Services without a tier are placed in a default tier that runs last
Tier names are case-insensitive and whitespace is trimmed
You can use any tier names you want — infrastructure, middleware, api, frontend, etc.

Profiles

Profiles group services for batch operations:

defaults:
  profiles: [default]           # Profiles used when no profile is specified

profiles:
  default: "*"                  # All services
  backend: [postgres, backend]      # Named list of services

"*" — selects all defined services
A list of service names — selects only those services
The defaults.profiles array controls which profiles run when you just type fuku

Concurrency

concurrency:
  workers: 5                    # Max concurrent service starts (default: 5)

Controls how many services can start in parallel within a single tier.

Retry

retry:
  attempts: 3                   # Max retry attempts (default: 3)
  backoff: 500ms                # Initial backoff duration (default: 500ms)

Log Streaming Buffer

logs:
  buffer: 100                   # Socket log streaming buffer size (default: 100)

Logging

logging:
  format: console               # "console" or "json"
  level: info                   # debug, info, warn, error

YAML Anchors

Use YAML anchors (&) and merge keys (<<: *) to avoid repeating common configuration. Top-level keys prefixed with x- are ignored by fuku and serve as anchor definitions.

x-readiness-http: &readiness-http
  type: http
  timeout: 30s
  interval: 500ms

x-watch: &watch
  include: ["**/*.go"]
  ignore: ["**/*_test.go"]
  debounce: 1s

services:
  api:
    dir: ./api
    readiness:
      <<: *readiness-http
      url: http://localhost:8080/health
    watch:
      <<: *watch

Full Example

version: 1

x-readiness-http: &readiness-http
  type: http
  timeout: 30s
  interval: 500ms

x-readiness-tcp: &readiness-tcp
  type: tcp
  timeout: 30s
  interval: 500ms

x-readiness-log: &readiness-log
  type: log
  pattern: "Service ready"
  timeout: 30s

x-logs: &logs
  output: [stdout, stderr]

x-watch: &watch
  include: ["**/*.go"]
  ignore: ["**/*_test.go"]
  shared: ["pkg/common"]
  debounce: 1s

services:
  postgres:
    dir: infrastructure/postgres
    tier: foundation
    readiness:
      <<: *readiness-tcp
      address: localhost:5432

  backend:
    dir: backend
    tier: platform
    readiness:
      <<: *readiness-http
      url: http://localhost:8080/health
    logs:
      <<: *logs
    watch:
      <<: *watch

  web:
    dir: frontend
    tier: edge
    readiness:
      <<: *readiness-http
      url: http://localhost:3000/health

defaults:
  profiles: [default]

profiles:
  default: "*"
  backend: [postgres, backend]

concurrency:
  workers: 5

retry:
  attempts: 3
  backoff: 500ms

logs:
  buffer: 100

logging:
  format: console
  level: info