docs: add troubleshooting steps for Ubuntu minion Salt version mismatch

[YatesMold]

Hello! 👋

While setting up my development environment for the GSoC 2026 project "AI-Powered Intelligent Monitoring and Root Cause Analysis for Uyuni" (#251), I encountered a critical edge case when bootstrapping an Ubuntu 22.04 minion.

The bootstrap script defaults to downloading Salt 3007+, which breaks the cryptographic handshake with a 3006 Uyuni Server (The Salt Master server's public key did not authenticate). Attempting to force a downgrade directly via the bootstrap script fails due to apt downgrade protections and missing dependencies (dctrl-tools, net-tools) on minimal Ubuntu instances.

As suggested by @srbarrios in the GSoC issue regarding initial contributions during the environment setup phase, I have documented the complete "Nuke & Pave" resolution path. By using {productname} tags, I ensured the docs remain compatible across builds. This ensures future contributors or users facing this version parity issue can resolve it quickly without getting stuck on ZMQ logs or package manager blockers.

Let me know if any format changes or structural adjustments are needed for the AsciiDoc!

[agraul]

Thank you for your pull request and interest in improving our documentation! I think these changes go a bit in the wrong direction. They describe how to use https://github.com/saltstack/salt-bootstrap, but that's not what we mean with "bootstrap script". In Uyuni, a bootstrap script is generated on the Uyuni server. Clients can download it from the Uyuni Server, or the server can push it to the clients over SSH.

Your experience raises a good point, the term "bootstrap script" is somewhat overloaded and can easily be confused with Salt's upstream bootstrap script. Maybe it's worth point that out in our documentation.

[agraul]

salt-bootstrap is unsupported. All minions must run our Salt Bundle package from the Client Tools repository for the given distribution (venv-salt-minion-xyz.deb). This script installs an incompatible Salt version, Uyuni expects patches from openSUSE/salt to be present on all minions.

[YatesMold]

Hi @agraul, thank you so much for the detailed explanation and the review.

You are right. I fell exactly into the trap of confusing the upstream SaltStack bootstrap script with the Uyuni-generated one. This completely explains the version mismatch and the missing patches I was experiencing during my local setup.
I will pivot this PR right now to add a clear [WARNING] block in the documentation. I will explicitly clarify the terminology overload and state that the upstream salt-bootstrap is unsupported and the venv-salt-minion bundle from the Client Tools must be used instead.

I'll push the updated commit shortly.

[0rnela]

Status: Outstanding feedback needs addressing.