podlet-compose 0.2.2

A thin wrapper around podlet that acts as a drop-in for docker/podman-compose

podlet-compose

A thin wrapper around podlet that acts as a drop-in replacement for docker-compose / podman-compose. It uses podlet to generate systemd quadlet service files from a compose.yaml and manages them via systemctl.

Disclaimer - This is currently only a PROOF OF CONCEPT. It has not been used in production and I do not recommend doing so.

Quick Start

Install latest release from PyPi (recommended)

pip install podlet-compose

See Installation for more installation options.

Usage

Usage: podlet-compose [OPTIONS] COMMAND

Generate systemd quadlet files from compose.yaml and manage services via systemctl.

Options:
      --dry-run        Print commands without executing
  -f, --file           Compose configuration files
  -h, --help           Print help information
  -p, --project-name   Specify an alternate project name

Commands:
  up                   Create and start containers
  down                 Stop and remove containers
  restart              Restart service containers
  start                Start services
  stop                 Stop services
  build                Build or rebuild services
  pull                 Pull service images
  ps                   List containers
  logs                 View output from containers
  top                  Display running processes
  images               List images
  port                 Print the public port for a port binding
  config               Validate and view compose config
  convert              Preview quadlet files
  version              Show version information

Requirements

• podlet — generates quadlet files from compose configs
• podman — container runtime
• Python 3.10+
• rich
• ruamel.yaml

Hacks (Optional Workarounds)

All compose file transformations are disabled by default. Enable them via PODLET_COMPOSE_HACKS:

# Enable specific hacks
PODLET_COMPOSE_HACKS=interpolate,name_inject podlet-compose up

# Enable all hacks
PODLET_COMPOSE_HACKS=all podlet-compose up

Available hacks: interpolate, name_inject, normalize, expand, strip_extensions. See the Hacks wiki page for details.

Documentation

Full documentation is available in the GitHub Wiki:

• Installation — Pip, PyInstaller binary, Nix, and podman compose provider setup
• Commands — Full command reference
• How It Works — Technical architecture and internals
• Hacks — Optional workarounds for podlet limitations
• Limitations — Known limitations

License

GNU General Public License v3.0