documents/CUSTOM-IMAGES.md

Rama main · réplica de lectura del repositorio original.

# Custom container images

[Documentation](README.md)

GitHub Actions builds the images in `.github/custom-images.json` and publishes
them to GHCR after changes reach `main`. Pull requests build the same matrix
without publishing it.

Each image has two tags:

- `ghcr.io/bolens/homelab-<name>:latest`
- `ghcr.io/bolens/homelab-<name>:sha-<commit>`

Use the commit tag for reproducible deployments. The workflow attaches build
provenance and an SBOM to each published image.

Most listed stacks use GHCR by default. Their Compose images have a stack-specific
`*_IMAGE` override. Set that variable to
`harbor.bolens.dev/homelab/<name>:latest` in `stack.env` or Portainer when
GHCR is unavailable. Compose cannot automatically try a second registry.

Nodepad CI runs `stacks/nodepad/clone-repo.sh` before building. That script
fetches a pinned upstream revision and applies the tracked patches. Its image is
`ghcr.io/bolens/homelab-nodepad`. The patched Readarr metadata service is
`ghcr.io/bolens/homelab-rreading-glasses`. These two stacks retain their existing
local build defaults; operators can select the published image explicitly.

The experimental Kavita override also retains local build defaults. CI publishes
`ghcr.io/bolens/homelab-kavita-independent` and
`ghcr.io/bolens/homelab-kavita-providers` for Linux amd64. Select matching commit
tags explicitly through the [Kavita instructions](../stacks/kavita/README.md).
Image publication does not establish genuine provider-account acceptance or
full feature parity.

The matrix excludes images whose required source is unavailable in CI:

- AIL Framework's application build requires its local vendor checkout.
- The SearxNG 4get images require operator-verified source directories.

Those images remain local builds until their source preparation is made
reproducible in CI. The optional Woodpecker publisher credential broker is also
an explicit local-only build; it is excluded from automatic registry publication.
Its allowlisted context contains source and notices, never runtime credentials.
See its [owning contract](../stacks/woodpecker-ci/publisher-broker/README.md). Paperclip’s optional `codex-git.Dockerfile` is also excluded:
it is an explicitly selected operator-local workaround for one upstream release,
not the default stack image. Its base-image updates remain monitored.

## Comic automation

- `ghcr.io/bolens/homelab-mylar3` includes DDL recovery, import problems,
  post-processing monitoring, worker health, and the desktop navigation/layout.
  Select it with `MYLAR3_IMAGE` in the Mylar stack.
- `ghcr.io/bolens/homelab-comic-normalizer` includes archive conversion,
  verified duplicate cleanup, corrupt-file quarantine, opt-in import recovery and
  release naming with native ownership and reader restoration checks.
  Select it with `COMIC_NORMALIZER_IMAGE` in Komga's normalizer override.
- `ghcr.io/bolens/homelab-komga` replaces the pinned server's next-UI assets
  with readable import notifications. Select it explicitly with `KOMGA_IMAGE`;
  the default remains the upstream image. The build verifies the UI types and
  labels and preserves unrelated application-JAR entries byte-for-byte.

These images run regression gates during their multi-stage builds and exclude test
code from their final stages. Their allowlisted build contexts exclude runtime
configuration and media. Linux amd64 is verified; other architectures are not
currently published by this workflow. Existing application data and worker recovery
state remain in external volumes or bind mounts. Follow each stack's verified
backup, update, and rollback procedure when changing an image.

The openai-oauth image builds the version-pinned community npm package with a checked-in lockfile and a minimal allowlisted build context. Account credentials remain in a private runtime volume. The Compose example builds locally until an operator explicitly selects a published image.

The Vane image builds from a pinned upstream image and guards repeated empty
streamed tool-call arguments. Its native streaming regression runs during the
build, and its allowlisted context excludes runtime settings. The Compose example
builds locally; select a published commit tag explicitly for registry-only deployments.