Replace Docker with Kiri or Podman and validate Woodpecker #70

Open
opened 2026-11-21 19:13:12 +00:00 by martin · 1 comment
Owner

Summary

Replace Docker with Kiri if it is a viable fit; otherwise use Podman. Update the related Woodpecker configuration so CI continues to work correctly with the selected runtime.

Context

The repository defines Woodpecker services and workflows under shared/base/modules/services/woodpecker. The requested runtime choice is not yet confirmed; Kiri is preferred if it can support the required host and Woodpecker use cases.

Scope

  • Assess whether Kiri can support the current container workloads and Woodpecker setup; use Podman if it cannot.
  • Replace Docker configuration and dependencies with the selected runtime where applicable.
  • Adapt Woodpecker server, agents, and workflow execution configuration to the selected runtime.
  • Verify relevant workloads and representative Woodpecker pipelines after the change.

Acceptance criteria

  • The selected runtime is Kiri when it meets the required use cases; otherwise Podman is selected and the reason is recorded.
  • Required workloads run with the selected runtime and Docker is no longer required by the migrated configuration.
  • Woodpecker server and agents are correctly configured for the selected runtime.
  • Representative Woodpecker pipelines execute successfully using that configuration.
  • The migration and verification results, including any remaining runtime-specific limitations, are documented.

Out of scope

  • Unrelated changes to Woodpecker workflow behavior or CI design.
## Summary Replace Docker with Kiri if it is a viable fit; otherwise use Podman. Update the related Woodpecker configuration so CI continues to work correctly with the selected runtime. ## Context The repository defines Woodpecker services and workflows under `shared/base/modules/services/woodpecker`. The requested runtime choice is not yet confirmed; Kiri is preferred if it can support the required host and Woodpecker use cases. ## Scope - Assess whether Kiri can support the current container workloads and Woodpecker setup; use Podman if it cannot. - Replace Docker configuration and dependencies with the selected runtime where applicable. - Adapt Woodpecker server, agents, and workflow execution configuration to the selected runtime. - Verify relevant workloads and representative Woodpecker pipelines after the change. ## Acceptance criteria - [ ] The selected runtime is Kiri when it meets the required use cases; otherwise Podman is selected and the reason is recorded. - [ ] Required workloads run with the selected runtime and Docker is no longer required by the migrated configuration. - [ ] Woodpecker server and agents are correctly configured for the selected runtime. - [ ] Representative Woodpecker pipelines execute successfully using that configuration. - [ ] The migration and verification results, including any remaining runtime-specific limitations, are documented. ## Out of scope - Unrelated changes to Woodpecker workflow behavior or CI design.
Author
Owner

Progress

Initial research points to Podman as the lower-friction NixOS option, while Kiri merits a small compatibility/package feasibility check before deciding:

  • This repository already has Podman enabled on desktop. Nidaros explicitly enables Docker and has a TODO to replace it. The shared development virtualization module already has a Podman/Docker selector and defaults to Podman.
  • The Woodpecker agent currently uses the Docker backend, joins the docker group, and points DOCKER_HOST at /run/docker.sock. Woodpecker's current docs say Podman is not officially supported, though they suggest trying its Docker-compatible API socket via DOCKER_HOST. So a Podman switch needs a real pipeline smoke test; changing NixOS's virtualisation.oci-containers.backend alone would not switch the Woodpecker agent backend.
  • NixOS exposes Podman and a Docker-compatible socket option; Podman's API grants full control as the service user (rootful socket access is effectively root-equivalent). Decide deliberately whether the agent uses a restricted rootless socket or a rootful one.
  • Kiri's upstream project describes Linux support and a Docker Engine API, so it may be compatible in principle. Its install instructions currently show .deb/.rpm releases, and I could not find a Nixpkgs package; packaging, systemd integration, and API behavior with Woodpecker remain to be validated. This makes Kiri possible but less turnkey than Podman.

Decisions

  • Preliminary recommendation: prefer Podman unless a short Kiri packaging/API proof-of-concept demonstrates a maintainable NixOS service and successful Woodpecker pipelines.
  • Keep the distinction clear: NixOS's OCI-containers backend manages host-declared containers; Woodpecker's agent separately chooses its pipeline backend and API socket.

Blockers

  • No runtime has been tested against the existing Woodpecker workflows yet. The agent socket path, service-user/group permissions, and representative pipeline behavior need verification before the migration choice is final.

References

This repository

NixOS / nixpkgs

Runtime / CI documentation

## Progress Initial research points to Podman as the lower-friction NixOS option, while Kiri merits a small compatibility/package feasibility check before deciding: - This repository already has Podman enabled on desktop. Nidaros explicitly enables Docker and has a TODO to replace it. The shared development virtualization module already has a Podman/Docker selector and defaults to Podman. - The Woodpecker agent currently uses the Docker backend, joins the **docker** group, and points **DOCKER_HOST** at **/run/docker.sock**. Woodpecker's current docs say Podman is not officially supported, though they suggest trying its Docker-compatible API socket via **DOCKER_HOST**. So a Podman switch needs a real pipeline smoke test; changing NixOS's **virtualisation.oci-containers.backend** alone would not switch the Woodpecker agent backend. - NixOS exposes Podman and a Docker-compatible socket option; Podman's API grants full control as the service user (rootful socket access is effectively root-equivalent). Decide deliberately whether the agent uses a restricted rootless socket or a rootful one. - Kiri's upstream project describes Linux support and a Docker Engine API, so it may be compatible in principle. Its install instructions currently show .deb/.rpm releases, and I could not find a Nixpkgs package; packaging, systemd integration, and API behavior with Woodpecker remain to be validated. This makes Kiri possible but less turnkey than Podman. ## Decisions - Preliminary recommendation: prefer Podman unless a short Kiri packaging/API proof-of-concept demonstrates a maintainable NixOS service and successful Woodpecker pipelines. - Keep the distinction clear: NixOS's OCI-containers backend manages host-declared containers; Woodpecker's agent separately chooses its pipeline backend and API socket. ## Blockers - No runtime has been tested against the existing Woodpecker workflows yet. The agent socket path, service-user/group permissions, and representative pipeline behavior need verification before the migration choice is final. ## References **This repository** - [Nidaros Docker enablement / replacement TODO](https://code.martials.no/Personal/nixos-configuration/src/branch/main/hosts/nidaros/virtualisation.nix) - [Existing desktop Podman configuration](https://code.martials.no/Personal/nixos-configuration/src/branch/main/hosts/desktop/virtualisation.nix) - [Shared virtualization backend module](https://code.martials.no/Personal/nixos-configuration/src/branch/main/shared/base/modules/development/virtualisation.nix) - [Woodpecker agent configuration](https://code.martials.no/Personal/nixos-configuration/src/branch/main/shared/base/modules/services/woodpecker/woodpecker-agent.nix) **NixOS / nixpkgs** - [Podman package in nixpkgs](https://mynixos.com/nixpkgs/package/podman) - [NixOS option: virtualisation.podman.enable](https://mynixos.com/nixpkgs/option/virtualisation.podman.enable) - [NixOS option: Podman Docker-compatible socket](https://mynixos.com/nixpkgs/option/virtualisation.podman.dockerSocket.enable) - [NixOS option: virtualisation.oci-containers.backend](https://mynixos.com/nixpkgs/option/virtualisation.oci-containers.backend) - [Official NixOS Podman guide](https://wiki.nixos.org/wiki/Podman) - [NixOS package search for Kiri](https://search.nixos.org/packages?channel=unstable&query=kiri) **Runtime / CI documentation** - [Kiri upstream repository and Linux install notes](https://github.com/libracoder/kiri) - [Woodpecker Docker backend and Podman caveat](https://woodpecker-ci.org/docs/administration/configuration/backends/docker) - [Podman API service, socket paths, and security warning](https://docs.podman.io/en/latest/markdown/podman-system-service.1.html)
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
Personal/nixos-configuration#70
No description provided.