Please write basic documentation for your dependencies

[jerkstorecaller]

Put some info in the README please so that users don't waste their time with untested configurations, all of which seem to fail.

1. What host OS is supported? More importantly, what host OS is actively used by the devs on the daily?
2. What version of Go do you require (I had to learn more about Go than I ever wanted to, by reading your commit messages, and going back a year to learn that you require Go 1.15+, though even that might be out of date)
3. Are there any known virtualization solutions that allow running debos? (for example I consistently failed with VirtualBox, even after enabling Nested VT-x, on both Intel and AMD)

I'll take just a simple "Tested on Debian 12, using a manually-installed Go 1.3562.32. We cannot vouch for any other configurations.". And when you change to a new distro/tools, update this sentence.

I'm not demanding you go the extra mile to keep debos compatible with older (but still maintained) distros like Buster, but at least document what DOES work so people can stick to that. 1 minute of writing to a README by a dev would save hours to an outsider, and if you multiply that by the number of outsiders, it becomes really important.

It's extremely frustrating to realize I lost my entire day for nothing. (which isn't your fault, most of my time was wasted on dealing with the debos in the Buster repo, but I did waste an hour on trying to get v.1.1.2 to work on Debian 10 and now I'm done.)

[obbardc]

Are the two entries in the README not enough?

• Docker: https://github.com/go-debos/debos#installation-docker-container
• Debian host: https://github.com/go-debos/debos#installation-under-debian

For reference I run debian unstable systems and install debos from the package or run it from a git checkout with go run .

I am very happy to accept documentation pull requests if anything is unclear.

[jerkstorecaller]

No that doc is not enough. I have Windows and run Linux in a Virtualbox virtual machine, with nested virtualization enabled.

• Attempt 1 on Intel PC in Buster VM with Buster's debos: qemu-system just spins CPU endlessly with no disk or network usage, zero output

• Attempt 2 on Intel PC using Docker tag 1.1.2 in a Ubuntu 20.04 VM: progresses until it fails after a few minutes during a step where the YAML wants to install grub on the partition. "grub-install /dev/loop0 && update-grub | grub-install: error: cannot find a GRUB drive for /dev/loop0. Check your device.map." tbh this was just a one-shot, I wasn't interested in the extra debugging complexity of using docker, I was just curious what would happen.

• Attempt 3 on AMD PC in new Buster VM with Buster's debos: progresses a lot but eventually fails with "Container root terminated by signal KILL"

• Attempt 4 on AMD PC in Buster VM to build latest debos from source: fails to build properly due to your README failing to specify your Go version requirements. You'd think I'd get an error message or something but no. It's just the absence of a binary that shows it.

• Attempt 5 on AMD PC in Buster VM: I install the latest Go in /usr/local and manage to build latest debos. Progresses a few minutes but also fails, forgot to log what the error was because I was fed up by then, I think it might have been a kvm-related error (but long after the fakemachine was running successfully and installing packages).

• Attempt 6 on AMD PC with new Bookworm VM and Bookworm's debos: progresses for many minutes but eventually fails with "open /tmp/fakemachine-1444676352/result: no such file or directory"

At this point I created the post. It's not just me. I have a collaborator who called it the most fragile tool he's ever used and told me to drop it and move on. Although, after starting with the latest versions of both Debian and debos and working his way back he ended up getting it to work in a Debian 10 VM on a Windows host.

Your "Installation under Debian" instructions literally don't work under Buster (supported until June 2024), so can we agree there's version/tool requirements for your tool? Where's the harm in mentioning them?

Look, this isn't one of those things where you ask for PRs for improved doc. This is not end-user doc to teach people how to use the tool, I struggled a lot to progress in learning how to create a YAML file (and a lot of that was due to how obtuse the tool is about communicating invalid usage, see the other tickets I created). I pause for a year or so and at this point I can't even get the thing to run!

What I'm asking for is very basic doc only the dev can write, AND it's just a single sentence so writing that comment takes the same amount of time as editing the README with your known-to-work configuration. Only you know what distro you're developing/testing on, only you know what your minimum Go version requirement is (which you haven't mentioned yet btw), and whatever else custom requirement you may have.

Tomorrow I will do attempt 7 with Debian unstable. Please specify which version of Go you use with it. The one from unstable? One you manually installed?

[obbardc]

Yeah, I use go from unstable & the instructions in the README under the Install from source bit.

Also I do use apt install debos on unstable as well.

[jerkstorecaller]

Well, it didn't work on sid ("Container root terminated by signal KILL."), so at this point I can only assume that running debos on Virtualbox is the issue. I give up.

1. Out of curiosity, why does your Docker doc say to pass /dev/kvm to the container? Isn't Docker enough for the purpose of a clean, reproducible environment? Shouldn't the examples be disabling fakemachine?

2. Also out of curiosity, what are some similar projects to debos?

[jerkstorecaller]

I've tried every conceivable combination of debos: Buster, Bookworm, docker, not docker, UML, host build (don't do that!), KVM.

The only thing that worked for me is a native Debian install with /dev/kvm available, using the native (non-docker) binary. It's impossible for me to virtualize or dockerize (or at least, dockerize while trying to install a bootloader. I assume it requires advanced knowledge of debos, Linux, docker AND grub). Even then, installing the bootloader was like pulling teeth due to zero examples on doing it (if you don't already install bootloaders on the daily).

When I'm done with this I'll be sending a pull request eventually with some sorely-needed documentation improvements to make life easier for people who are casual users.