Skip to content
imglife

Quick Start

This guide walks you through a minimal but real-world configuration: mirror one public image, build one base image, and generate a status report.

What you need

Section titled “What you need”
  • imglife installed
  • A private OCI registry (e.g. registry.example.com)
  • A GitLab project or Gitea organisation to store build metadata (the Package Registry)
  • A GITLAB_TOKEN or GITEA_TOKEN exported in your shell

Step 1 — Create the config file

Section titled “Step 1 — Create the config file”

Create imglife.yaml in your base-images repository:

# imglife.yaml — base images project (GitLab)


registry:
  url: https://gitlab.example.com # your GitLab instance
  project_id: 42 # Settings > General > Project ID


sync:
  entries:
    - source: docker.io/library/alpine
      tag_regex: '^3\.\d+\.\d+$' # match all 3.x.y tags
      keep_last: 3 # keep the 3 most recent
      target: registry.example.com/mirrors/alpine


build:
  core_version: "1.0.0"
  registry: registry.example.com/bases
  images:
    - name: alpine
      folder: images/alpine
      type: core
      mirror_image: registry.example.com/mirrors/alpine
      mirror_tag: "3.21.3" # pinned mirror tag to use as FROM
      version: "3.21.3"


retention:
  keep_last: 5
  max_age_days: 90


status: {}

Step 2 — Create the Dockerfile template

Section titled “Step 2 — Create the Dockerfile template”

imglife uses Go templates to generate Dockerfiles. Create the folder referenced in the config:

Terminal window
mkdir -p images/alpine

Create images/alpine/Dockerfile.tmpl:

ARG MIRROR_IMAGE
FROM ${MIRROR_IMAGE}


# Org-standard packages and configuration
RUN apk add --no-cache ca-certificates tzdata curl


# OCI labels are injected automatically by imglife build

Step 3 — Export credentials

Section titled “Step 3 — Export credentials”
Terminal window
# Package Registry (GitLab or Gitea)
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx


# OCI registry (if not using Docker CLI login)
export IMGLIFE_REGISTRY_EXAMPLE_COM_USERNAME=myuser
export IMGLIFE_REGISTRY_EXAMPLE_COM_PASSWORD=mypassword

See Credentials for the full naming convention.

Step 4 — Sync mirrors

Section titled “Step 4 — Sync mirrors”
Terminal window
imglife sync

imglife queries Docker Hub for all 3.x.y tags of alpine, resolves the 3 most recent, and copies them to your private registry.

Preview without writing anything:

Terminal window
imglife sync --dry-run
imglife sync --list   # show what would be synced

Step 5 — Build the base image

Section titled “Step 5 — Build the base image”
Terminal window
imglife build

imglife renders images/alpine/Dockerfile.tmpl, injects OCI labels (build date, git revision, base image reference), and pushes the resulting image as registry.example.com/bases/alpine:3.21.3-core1.0.0.

The tag format is <mirror_tag>-core<core_version> by default.

Preview:

Terminal window
imglife build --list    # show what would be built
imglife build --dry-run # render Dockerfiles without pushing

Step 6 — Generate the status report

Section titled “Step 6 — Generate the status report”
Terminal window
imglife status --output README.md

This produces a Markdown file listing all your images with their EOL dates. Commit it to your repository so it’s visible in GitLab/Gitea.

Step 7 — Clean up stale tags

Section titled “Step 7 — Clean up stale tags”
Terminal window
imglife cleanup --dry-run   # preview what would be deleted
imglife cleanup             # apply retention policy

Automate with CI/CD

Section titled “Automate with CI/CD”

Once you’ve verified each step locally, wire them into a CI pipeline. See the complete pipeline guides:

What’s next

Section titled “What’s next”