Please document requirements for Toolbx-friendly container images

[smcv]

Is your feature request related to a problem? Please describe. The Steam Runtime provides SDK images intended for compiling Steam games, and Platform images intended for running dedicated servers. We would like to ensure that our images are Toolbx-friendly, so they can be passed to toolbox create -i without needing additional packages added.

Describe the solution you'd like Some document linked in an obvious way from the Toolbx website should document what's required in a Toolbx-friendly image.

https://containertoolbx.org/distros/ used to document this, but it was removed in containers/containertoolbx.org@d1f48731 and wasn't subsequently reinstated.

https://github.com/containers/toolbox/blob/main/README.md also used to document this, but it was replaced by a link to https://containertoolbx.org/distros/ in f0dfb8f3, which at the time was fine, but is no longer enough because of the above change.

I don't really mind where this information is kept, but I feel as though it should be somewhere, and linked from at least one of those two places.

There used to be metapackages in https://src.fedoraproject.org/rpms/toolbox//blob/rawhide/f/toolbox.spec which encapsulated what's needed, but they were removed in https://src.fedoraproject.org/rpms/toolbox/c/57ae69592c86bef5f8493cc68a04fb8a905f5719?branch=rawhide.

The information I would like to see is:

• the need to add the com.github.containers.toolbox="true" label
• essential setup/packages/executables required in order to legitimately have that label
  • empty ENTRYPOINT
  • coreutils: mkdir(1), test(1), touch(1)
  • libcap: capsh(1)
  • shadow: passwd(1), useradd(8), usermod(8)
  • util-linux: mount(1)
  • list of files that must not be a bind-mount
  • (others?)
• desirable packages/executables/files
  • flatpak-xdg-utils: flatpak-spawn(1), xdg-open(1) reimplementation, xdg-email(1) reimplementation added to PATH
  • sudo: sudo(8) configured for passwordless sudo for users in sudo and/or wheel group
  • systemd: libnss_myhostname present and configured in /etc/nsswitch.conf
  • vte2.91: /etc/profile.d/vte*
  • (others?)

I see that images/ installs a bunch of packages beyond that, to create a comfortable CLI environment - but if they aren't functionally required by Toolbx's integration with the host, and are only conveniences for the interactive user, then I would consider those to be out-of-scope for the documentation I'm asking for.

[hadmut]

Me too.

I just wanted to open that issue and saw, that by coincidence, someone else had opened a similar issue less than an hour ago.

What I'd like to do: Prepare Container with particular software and settings and let it run on different machines.

But when doing a test on Ubuntu 24.04 as a host (24.04 comes with Version: 0.0.99.3+git20230118+446d7bfdef6a-2)

toolbox create --image docker.io/library/ubuntu:24.04 toolbox enter ubuntu-24.04 Error: invalid entry point PID of container ubuntu-24.04

Doing the same on a latest Fedora Kinoite takes some time and issues Error: failed to initialize container ubuntu-24.04

Would be quite helpful if there was some description about what is required for a container to run with toolbox.

regards

[debarshiray]

My apologies that it took me so long to get to this! You are absolutely right that we must document the image requirements somewhere, and it's a pity that we lost it when the website was revamped in commit d1f48731ec76a3ae.

I have reintroduced some initial content at: https://containertoolbx.org/doc/#requirements

It's not complete yet, but I wanted to give you an update.

[silverhadch]

I would also like to add that there is way more toolbx images out there then you might document. Distrobox handels that by having a comp flag that list the images it has that outputs a hardcoded list of images that get extended when upstreams or users PR a new Image to that list. It also makes it easier for example developers (like me) that work on an UI for toolbx that when installing you can just call toolbox create -C and get the list of images. Currently i am doinc that downstream. https://invent.kde.org/system/kontainer/-/blob/master/include/toolboximages.h?ref_type=heads

[debarshiray]

I would also like to add that there is way more toolbx images out there then you might document.

This is about listing the requirements for images, not the list of available images.

[debarshiray]

list of files that must not be a bind-mount

I now realize that when I wrote the original version of the text in commit 44817691828207049da403d8201599f0cd49bd99 I was a bit dim to stress that the paths shouldn't be bind mounts. That concern had more to do with unexpected changes in or wrong use of Podman (eg., podman create --dns none is needed to prevent it from making /etc/resolv.conf a mount point), and less to do with how the images were created.

I changed the text to say more about what kind of files these paths must be, other than the bind mount aspect.

[debarshiray]

flatpak-xdg-utils: flatpak-spawn(1), xdg-open(1) reimplementation, xdg-email(1) reimplementation added to PATH

I left out the xdg-open(1) and xdg-email(1) reimplementations because none of the built-in images have them. They are supposed to be the most complete examples of Toolbx images, and if they don't have them then we shouldn't ask other images to do more. :)

That said, we should probably look into doing this.

[debarshiray]

I think we now have a reasonable documentation about the requirements for Toolbx-friendly images at https://containertoolbx.org/doc/#requirements

The text should be better than the version that we lost in commit d1f48731ec76a3ae. It better reflects the current realities of the code. Some new requirements were added to enable new Toolbx features, and some that are no longer needed were dropped.

Once again, my apologies that it took so long to get this done!

I am going to close this issue now. Please feel free to re-open or open a new one or submit a pull request if you spot any mistakes or think something is missing. Thanks for playing with Toolbx!

[smcv]

The text should be better than the version that we lost in commit d1f48731ec76a3ae. It better reflects the current realities of the code. Some new requirements were added to enable new Toolbx features, and some that are no longer needed were dropped.

Thanks, I agree the new version is much better! I'll revisit the package list in the Steam Runtime SDKs based on your new text when time permits, and feed back issues/PRs if anything seems to be missing.

[debarshiray]

The text should be better than the version that we lost in commit d1f48731ec76a3ae. It better reflects the current realities of the code. Some new requirements were added to enable new Toolbx features, and some that are no longer needed were dropped.

Thanks, I agree the new version is much better! I'll revisit the package list in the Steam Runtime SDKs based on your new text when time permits, and feed back issues/PRs if anything seems to be missing.

Thanks for the feedback and working on the Steam image!