Skip to content

docs: document Podman support on Linux - #924

Merged
slayerjain merged 1 commit into
mainfrom
docs/podman-support
Oct 7, 2026
Merged

slayerjain merged 1 commit into
mainfrom
docs/podman-support

Conversation

@slayerjain

Copy link
Copy Markdown
Member

Keploy records and tests apps that run in Podman on Linux from v3.8.60, but the docs only mentioned Docker. This adds Podman where a user would look for it.

  • Platform requirements: a new Podman section covering:
    • rootful only, because the agent loads eBPF;
    • build or pull the image, and start any other container the app needs, with sudo podman, since keploy uses the rootful Podman;
    • keploy uses the rootful podman.socket if it's enabled, and otherwise starts Podman's API service for the run;
    • podman compose needs docker-compose as its provider, Podman 4.7+, and systemd for healthchecks; podman-compose isn't supported;
    • podman-remote, and Podman on macOS/Windows, are refused;
    • it's the keploy that install.sh installs. A keploy built from the open-source repository refuses Podman and says where to get it.
  • Installation: a Podman tab next to Docker on Linux (and in the closing "Congratulations" tabs). It has the record and test commands and the podman compose form. The older concepts installation page now links there.
  • CLI reference and common errors: the CLI reference mentions Podman. Common errors gets one entry covering:
    • the refusals from an open-source build, from macOS/Windows, and from a podman-remote client;
    • a Keploy older than v3.8.60, which runs a Podman command as a host process and records nothing, without an error;
    • Podman's error when the compose provider is podman-compose;
    • compose on a host without systemd, where the agent's healthcheck never runs and the app never starts;
    • an image that is only in the rootless store.

Tested:

  • podman run record, auto-replay and replay on mocks are covered by Keploy's automated tests, with Podman 5.4.2.
  • podman compose was checked by hand, with Podman 5.8.7 and docker-compose as its provider. Podman 4.7–4.9 hasn't been run with Keploy; the docs give 4.7 as the floor (where podman compose appeared) and say Keploy is tested with Podman 5.
  • podman-compose isn't supported, and the docs now say so.

Keploy records and tests applications that run in rootful Podman on
Linux, from v3.8.60, and nothing in the docs said so.

- Platform requirements gets a Podman section: rootful Podman and why;
  building images and starting every other container with sudo podman;
  the rootful podman.socket keploy uses or the API service it starts;
  what podman compose needs (docker-compose as its provider, Podman
  4.7+, systemd for healthchecks) and that podman-compose isn't
  supported; podman-remote and macOS/Windows refused; and that it is
  the keploy install.sh installs, as an open-source keploy refuses
  Podman and says where to get it.
- Installation gets a Podman tab beside Docker on Linux, with the
  record and test commands and the compose form; the older concepts
  installation page points to it.
- The CLI reference mentions it, and common errors covers the refusals,
  a keploy older than v3.8.60 that records nothing without an error,
  Podman's error under podman-compose, compose on a host without
  systemd, and an image left in the rootless store.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
@slayerjain
slayerjain merged commit 1a6d326 into main Oct 7, 2026
6 checks passed
@slayerjain
slayerjain deleted the docs/podman-support branch October 7, 2026 20:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant