Enhance documentation about installation procedure

[PixelJonas]

Is your feature request related to a problem? Please describe. I'm currently frustrated when trying to install toolbox on my system. The current documentation states:

Installation
Toolbox is installed by default on Fedora Silverblue. On other operating systems it's just a matter of installing the toolbox package.

I'm currently running a MacOS and Ubuntu 20.04 (in WSL2) and both of these systems do not have a toolbox package which got me lost in trying to figure out how to install toolbox.

❯ sudo apt install toolbox
Reading package lists... Done
Building dependency tree
Reading state information... Done
E: Unable to locate package toolbox

❯ brew install toolbox
==> Searching for similarly named formulae...
Error: No similarly named formulae found.
Error: No available formula or cask with the name "toolbox".
==> Searching for a previously deleted formula (in the last month)...
Error: No previously deleted formula found.
==> Searching taps on GitHub...
Error: No formulae found in taps.

Since toolbox is a very generic name, searching the internet for installation instructions is a pain.

Downloading a GitHub release left me with the POSIX toolbox at the root of the project which immediately prompts me with a deprecation notice. The notice states, I shall install the GO version of the toolbox but I don't see any documentation about how I can install that, or where to find it.

Describe the solution you'd like A clear and concise description of the installation process including error messages that point to the next step.

Additional context I came to this project since it's a dependency of another project.

[HarryMichal]

Hi @PixelJonas! I see two separae issues here:

1. The info about installing Toolbox via a package manager is too vague.
2. Having the toolbox POSIX script in the root is confusing for new users

I agree with the first point and we should address that. I do not really understand the second point since in our README we have instructions for building the Go version that specifically talks about Go, Meson and such. These steps also include an installation step.

[PixelJonas]

Hey @HarryMichal,

so when I was trying to install the toolbox I did not read further to the chapter USAGE because I wasn't finishing Installing. I'd suggest moving Dependencies and Building to Installation and call it building from source which would probably be a thing I do when the package method fails.

Since toolbox will most likely be a dependency of another project this is starting a dependency-hell (which toolbox tries to solve) when I'm coming from Project A needing to install toolbox and then have to install meson, go-md2man, systems, go, ninja on my system as well to be able to get toolbox going.

I'm not that deep into go, but it would be possible to create compiled binary artifacts for "common" OSes, right? So adding these to release artifacts may be a solution for the "I just want it to work" guys like me :D

If this would be a possible solution I'm happy to look into contributing this to the projects CI/CD Pipeline

[HarryMichal]

so when I was trying to install the toolbox I did not read further to the chapter USAGE because I wasn't finishing Installing. I'd suggest moving Dependencies and Building to Installation and call it building from source which would probably be a thing I do when the package method fails.

While I understand the fact that the README is not perfectly clear, the first thing you should do in any project before requesting some change is to read at least the whole README and not stop midway :).

I don't agree with moving the Dependencies and Building section since, as you said yourself, your priority was to install and not build from source. It makes more sense to me to keep the structure as it is now. I'm just thinking about taking the whole Dependencies and Building section into our CONTRIBUTING file and just leave a mention of it in the README but that is currently just a thought.

Since toolbox will most likely be a dependency of another project this is starting a dependency-hell (which toolbox tries to solve) when I'm coming from Project A needing to install toolbox and then have to install meson, go-md2man, systems, go, ninja on my system as well to be able to get toolbox going.

I dare say this is a bit of a speculation on your part. I'm not entirely sure how to react here.

I'm not that deep into go, but it would be possible to create compiled binary artifacts for "common" OSes, right? So adding these to release artifacts may be a solution for the "I just want it to work" guys like me :D

The answer is a bit more complicated because while Toolbox is written in Go which generally compiles into static binaries, it uses some features that cause the binary to dynamically link to libc. There is a discussion about this topic in https://github.com/containers/toolbox/issues/772.

Bear in mind that Toolbox is meant primarily for Fedora and while it works on other distros (like Arch Linux) or is being prepared for other (like RHEL) we don't support any other distributions meaning you're more-or-less on your if you run the tool on other distros.

You mention a dependency hell but I dare say Toolbox does not have that many dependencies in the first place (even though we have the overhead of Meson + Ninja for the build system). I personally don't find it too hard to build from source.

To get back to the original topic, I see a few actionable items:

1. Elaborate more on installation steps
2. Make section Dependencies and Building more clear

[debarshiray]

I'm currently running a MacOS

It says loud and clear:

• Tool for containerized command line environments on Linux
• Toolbox is a tool for Linux operating systems ...

So, no, Toolbox won't work on macOS, unless you are running it remotely on an actual Linux system.

and Ubuntu 20.04 (in WSL2) and both of these systems do not have a toolbox package which got me lost in trying to figure out how to install toolbox.

It's really not possible for an upstream project to track the names of all its downstream packages in its main README.md page. It's prime real estate and the number of downstream distributors is potentially infinite.

I came to this project since it's a dependency of another project.

Out of curiosity, which project is that?

[PixelJonas]

I came here while onboarding to Operate First. It's part of their access to the cluster documentation.

I was just describing my experience as a new user who did not manage to get the project running on his MacOS and Linux environment.