Skip to content

Configuration Overview

imglife is driven by a single YAML configuration file. By default it looks for imglife.yaml in the current directory. Override this with --config:

imglife --config /etc/imglife/config.yaml sync
imglife --check   # validate without running

The environment variable IMGLIFE_CONFIG is also supported:

export IMGLIFE_CONFIG=/etc/imglife/config.yaml

Top-level structure

registry: {} # Package Registry connection (required)
sync: {} # Mirror images to sync (optional)
build: {} # Base images to build (optional)
retention: {} # Cleanup policy (optional, has defaults)
lifecycle: {} # EOL data source (optional, has defaults)
status: {} # Status report options (optional)

All sections except registry are optional. A minimal config that only syncs mirrors only needs registry and sync.

Annotated example

Below is a complete configuration demonstrating all features. Each subsection links to its detailed reference.

# ─── Package Registry ──────────────────────────────────────────────────────────
# Stores build records for applicative images.
# Credentials via environment variables — never in YAML.
registry:
  url: https://gitlab.example.com # GitLab self-hosted instance
  project_id: 42 # Settings > General > Project ID

# ─── Sync ──────────────────────────────────────────────────────────────────────
# Copies upstream public images to your private registry.
sync:
  hooks:
    post_sync:
      - cmd: echo "Sync complete"

  entries:
    - source: docker.io/library/alpine
      tag_regex: '^3\.\d+\.\d+$' # sync all 3.x.y tags
      keep_last: 3 # retain only the 3 most recent
      target: registry.example.com/mirrors/alpine
      lifecycle:
        product: alpine # EOL product key on endoflife.date
        extract: minor # "3.21.3" → cycle "3.21"

    - source: docker.io/library/golang
      tag_regex: '^1\.\d+\.\d+-alpine3\.\d+$'
      keep_last: 2
      target: registry.example.com/mirrors/golang

# ─── Build ─────────────────────────────────────────────────────────────────────
# Generates Dockerfiles from templates and pushes base images.
build:
  core_version: "1.2.0" # bumped when org config changes
  registry: registry.example.com/bases # push destination
  platforms: [linux/amd64, linux/arm64] # default for all images
  sbom: true # SBOM attestation via buildx
  tag_format: "{{.Version}}-core{{.CoreVersion}}" # default tag format

  images:
    - name: alpine
      folder: images/alpine
      type: core
      mirror_image: registry.example.com/mirrors/alpine
      mirror_tag: "3.21.3"
      version: "3.21.3"

    - name: alpine-dev
      folder: images/alpine-dev
      type: spe-dev # dev variant — not EOL-checked
      mirror_image: registry.example.com/mirrors/alpine
      mirror_tag: "3.21.3"
      version: "3.21.3"

    - name: golang
      folder: images/golang
      type: core
      mirror_image: registry.example.com/mirrors/golang
      mirror_tag: "1.22.3-alpine3.21"
      version: "1.22.3-alpine3.21"
      platforms: [linux/amd64] # override: single arch

# ─── Retention ─────────────────────────────────────────────────────────────────
# Cleanup policy applied by `imglife cleanup`.
retention:
  keep_last: 5 # keep 5 most recent tags per image
  max_age_days: 90 # delete tags older than 90 days
  exclude_tags:
    - latest
    - stable

  archive:
    enabled: true
    registry: registry.example.com/archive # separate registry path
    keep_days: 180 # keep archived tags for 180 days

# ─── Lifecycle ─────────────────────────────────────────────────────────────────
# EOL data source configuration.
lifecycle:
  eol_provider: endoflife # fetch from endoflife.date (default)
  eol_target: git # store cache in eol-data.yaml in git
  eol_data_file: eol-data.yaml

# ─── Status ────────────────────────────────────────────────────────────────────
# Options for the generated Markdown README.
status:
  client_zone: |
    ## Additional info
    Updated daily at 06:00 UTC by the base-images CI pipeline.
    Questions? Contact the platform team in #platform-images.

Provider-specific `registry` configs

registry:
  url: https://gitlab.example.com
  project_id: 42

registry:
  url: https://registry.gitlab.com # OCI registry
  api_url: https://gitlab.com # API (Package Registry)
  project_id: 42

registry:
  provider: gitea
  url: https://gitea.example.com
  owner: myorg
  repo: base-images

registry:
  provider: s3
  url: http://garage.internal:3900 # omit for AWS S3 standard
  bucket: imglife-builds
  region: garage
  prefix: builds

Section references

Section	Purpose	Required
`registry`	Package Registry backend	Yes
`sync`	Mirror images	No
`build`	Base image builds	No
`retention`	Cleanup policy	No (has defaults)
`lifecycle`	EOL data source	No (has defaults)
`status`	README generation	No