Skip to content

Add how to develop with Podman instead of Docker #2927

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
+20 −0
Open

Add how to develop with Podman instead of Docker #2927

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ff921ae
Add guide for developing with Podman instead of Docker
teresaromero Sep 18, 2025
c741992
Refactor Podman usage guide to streamline instructions and enhance cl…
teresaromero Sep 18, 2025
2920a2c
Update docs/howto/use_podman.md
teresaromero Sep 19, 2025
bcee060
Update documentation to include Podman as an alternative to Docker
teresaromero Sep 19, 2025
bd4f593
Add note about Docker and Podman compatibility in README
teresaromero Sep 19, 2025
f044127
Fix links to podman docs and getting started
teresaromero Sep 22, 2025
3ad1122
Merge branch 'main' into how-to-podman
teresaromero Oct 7, 2025
5428508
docs: emphasize Podman Desktop configuration in usage guide
teresaromero Oct 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@ Run the `help` command and see available commands:
elastic-package help
```

Some sub-commands are Docker-based, check you also have Docker installed. In case you are using Podman, check [this guide](./docs/howto/use_podman.md) to make it compatible.

## Development

Even though the project is "go-gettable", there is the [`Makefile`](./Makefile) present, which can be used to build,
Expand Down Expand Up @@ -490,6 +492,8 @@ You can run your own custom images for Elasticsearch, Kibana or Elastic Agent, s

Be aware that a common issue while trying to boot up the stack is that your Docker environments settings are too low in terms of memory threshold.

You can use Podman instead of Docker, see [this document](./docs/howto/use_podman.md)

For details on how to connect the service with the Elastic stack, see the [service command](https://github.com/elastic/elastic-package/blob/main/README.md#elastic-package-service).

### `elastic-package stack down`
Expand Down Expand Up @@ -542,6 +546,8 @@ You can run your own custom images for Elasticsearch, Kibana or Elastic Agent, s

Be aware that a common issue while trying to boot up the stack is that your Docker environments settings are too low in terms of memory threshold.

You can use Podman instead of Docker, see [this document](./docs/howto/use_podman.md)

To expose local packages in the Package Registry, build them first and boot up the stack from inside of the Git repository containing the package (e.g. elastic/integrations). They will be copied to the development stack (~/.elastic-package/stack/development) and used to build a custom Docker image of the Package Registry. Starting with Elastic stack version >= 8.7.0, it is not mandatory to be available local packages in the Package Registry to run the tests.

For details on how to connect the service with the Elastic stack, see the [service command](https://github.com/elastic/elastic-package/blob/main/README.md#elastic-package-service).
Expand Down
4 changes: 4 additions & 0 deletions cmd/stack.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,8 @@ You can run your own custom images for Elasticsearch, Kibana or Elastic Agent, s

Be aware that a common issue while trying to boot up the stack is that your Docker environments settings are too low in terms of memory threshold.

You can use Podman instead of Docker, see [this document](./docs/howto/use_podman.md)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can use Podman instead of Docker, see [this document](./docs/howto/use_podman.md)
You can use Podman Desktop instead of Docker, see [this document](./docs/howto/use_podman.md)


For details on how to connect the service with the Elastic stack, see the [service command](https://github.com/elastic/elastic-package/blob/main/README.md#elastic-package-service).`

const stackUpLongDescription = `Use this command to boot up the stack locally.
Expand All @@ -45,6 +47,8 @@ You can run your own custom images for Elasticsearch, Kibana or Elastic Agent, s

Be aware that a common issue while trying to boot up the stack is that your Docker environments settings are too low in terms of memory threshold.

You can use Podman instead of Docker, see [this document](./docs/howto/use_podman.md)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can use Podman instead of Docker, see [this document](./docs/howto/use_podman.md)
You can use Podman Desktop instead of Docker, see [this document](./docs/howto/use_podman.md)


To expose local packages in the Package Registry, build them first and boot up the stack from inside of the Git repository containing the package (e.g. elastic/integrations). They will be copied to the development stack (~/.elastic-package/stack/development) and used to build a custom Docker image of the Package Registry. Starting with Elastic stack version >= 8.7.0, it is not mandatory to be available local packages in the Package Registry to run the tests.

For details on how to connect the service with the Elastic stack, see the [service command](https://github.com/elastic/elastic-package/blob/main/README.md#elastic-package-service).
Expand Down
8 changes: 8 additions & 0 deletions docs/howto/use_podman.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# How to Develop Using Podman Instead of Docker
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could it be linked this document from the main README?
https://github.com/elastic/elastic-package/blob/a4dc5bfc8e2e7d8bee92dca953ff4d533646f5ed/tools/readme/readme.md.tmpl

I don't see any reference that elastic-package required docker, but maybe it could be added in the Getting started section, WDYT?

As an example, this is done in the integrations repo: https://github.com/elastic/integrations/blob/30cbfa897b15730214495befe29929e9d218c122/docs/extend/quick-start.md?plain=1#L33

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i see it in the stack command is mentioned that is a "docker-based" command https://github.com/elastic/elastic-package/blob/a4dc5bfc8e2e7d8bee92dca953ff4d533646f5ed/README.md#elastic-package-stack perhaps here we could add a line just in case you dont use docker ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i see it in the stack command is mentioned that is a "docker-based" command https://github.com/elastic/elastic-package/blob/a4dc5bfc8e2e7d8bee92dca953ff4d533646f5ed/README.md#elastic-package-stack perhaps here we could add a line just in case you dont use docker ?

Maybe the line you added to elastic-package stack up could be removed in favor of the one in elastic-package stack.

But a part from the stack sub-command, other sub-commands also require docker commands:

  • elastic-package test system
  • elastic-package service

So, I'm wondering if it would make sense to just add it to a section in the main README.md as Requirements, Pre-Requisites or under "Getting started". WDYT @jsoriano ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add it to getting started section, although adding it to the command description might be useful in case of error, looking for help of the command can be a way to discover this content too

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it would be enough with the mention in the getting started section, but I don't see a problem with the line added to command descriptions, so as you prefer.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's be more specific about using Podman Desktop. Podman CLI doens't seem to be enough for the calls to the API as the socket is not exposed.

Suggested change
# How to Develop Using Podman Instead of Docker
# How to Develop Using Podman Desktop Instead of Docker


`elastic-package` Docker-based commands should work out of the box using Podman instead of Docker.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It'd be great to add a test to prove this 🙂 but we can add it if at some point we see users having problems with Podman.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`elastic-package` Docker-based commands should work out of the box using Podman instead of Docker.
`elastic-package` Docker-based commands should work out of the box using Podman Desktop instead of Docker.


Check you have **Podman Desktop** configured [following the migration guide](https://podman-desktop.io/docs/migrating-from-docker/managing-docker-compatibility)

- [Podman Getting Started](https://podman.io/get-started)
- [Podman Docs](https://podman.io/docs)
2 changes: 2 additions & 0 deletions tools/readme/readme.md.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,8 @@ Run the `help` command and see available commands:
elastic-package help
```

Some sub-commands are Docker-based, check you also have Docker installed. In case you are using Podman, check [this guide](./docs/howto/use_podman.md) to make it compatible.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Some sub-commands are Docker-based, check you also have Docker installed. In case you are using Podman, check [this guide](./docs/howto/use_podman.md) to make it compatible.
Some sub-commands are Docker-based, check you also have Docker installed. In case you are using Podman Desktop, check [this guide](./docs/howto/use_podman.md) to make it compatible.


## Development

Even though the project is "go-gettable", there is the [`Makefile`](./Makefile) present, which can be used to build,
Expand Down