Wrapper and troubleshooting update

source/community/maintainers.rst

@@ -16,9 +16,6 @@ Wrapper release
 Preparation
 -----------
 
-1. Git updates
-~~~~~~~~~~~~~~
-
 The first step is to update the project and sub-modules, meaning pointing the exegol-images and exegol-resources sub-modules to the latest master version.
 Even if the wrapper is able to auto-update itself, it is always better to keep the base reference at least up to date.
 
@@ -52,17 +49,9 @@ Even if the wrapper is able to auto-update itself, it is always better to keep t
 .. important::
     Don't forget to **reload and commit** any **submodule update** at this step !
 
-2. Config reviews
-~~~~~~~~~~~~~~~~~
-
-* Review exegol.utils.ConstantConfig variables
-
-    * Change version number ! (remove the alpha or beta tag at the end of the version number)
-* Review documentation
-* Review README.md
 
-Tests & build
--------------
+Local tests & build
+~~~~~~~~~~~~~~~~~~~
 
 First, test the code with mypy:
 
@@ -84,48 +73,63 @@ You can execute this one-liner to check the project and build it.
        (rm -rf Exegol.egg-info && python3 -m build --sdist) || \
        echo "Some tests failed, check your code and requirements before publishing!"
 
+Config reviews
+~~~~~~~~~~~~~~
 
-Post build
-----------
-
-* Upgrade tests.test_exegol.py version number to the next version build to avoid future mistake
-* Commit updates
-* Publish PR
-* Wait for review and merge
+* Review exegol.config.ConstantConfig variables
 
-Manual Upload
--------------
+    * Change version number ! (remove the alpha or beta tag at the end of the version number)
+* Review exegol.utils.imgsync.spawn.sh version
 
-.. important::
-    PyPi packaging and upload is now handle by **GitHub action**. It will be triggered with the creation of the **new tag** in the next-step with the release creation.
+    * Must contain a line with the script current version in the following format: ``# Spawn Version:2`` (without alpha or beta letter)
+* Review documentation on Exegol-docs/dev-wrapper
+* Review README.md
 
-    **This step is no longer needed.**
+* Create PR (or put it out of draft mode)
 
-After validation of the PR, we can upload the new version package to pypi.
+.. important::
+    The Pull-Request must be **already** created and **NOT** be in draft state before pushing the latest stable version.
 
-.. warning::
-    **Require** `twine <https://packaging.python.org/en/latest/tutorials/packaging-projects/#uploading-the-distribution-archives>`__ package installed and token configured on ``~/.pypirc``!
+* Commit and push stable latest config
 
-* Check package upload on the test repository (optional)
+Review and publish
+------------------
 
-.. code-block:: bash
+The PR is now ready to be peer-review and then merge on Github.
 
-    python3 -m twine upload --repository testpypi dist/* --verbose
+Once merged to master, a tag must be deploy to run the release pipeline. The github action pipeline will automatically build and publish:
 
-* Upload to the production repository
+Exemple to release version ``4.3.5``:
 
 .. code-block:: bash
 
-    python3 -m twine upload dist/*
+    git checkout master
+    git pull
+    git tag -s 4.3.5 -m '4.3.5'
+    git push --tags
 
+Check if the release pipeline works as expected: `Release pipeline <https://github.com/ThePorgs/Exegol/actions/workflows/entrypoint_release.yml>`_
 
-Post-Deploy
+Post deploy
 -----------
 
 * Create new github **release** with **new** version tag
-* Fast-forward dev branch to the latest master commit
+
+After releasing a new stable version on the wrapper, we must update the dev version to stay in a beta version
+
+* Fast-forward dev branch to the latest master commit:
+
+.. code-block:: bash
+
+    git checkout dev
+    git merge master --ff-only
+    git push
+
 * Change the wrapper version on the dev branch to ``x.y.zb1``
 
+* Upgrade tests.test_exegol.py version number to the next version build to avoid future mistake
+* Commit updates
+
 Images release
 ==============
 

source/getting-started/faq.rst

@@ -2,7 +2,7 @@
 Frequently asked questions
 ==========================
 
-Below are the frequently asked questions regarding either features, the overall project or troubleshooting matters.
+Below are the frequently asked questions regarding either features or the overall project.
 
 .. contents::
     :local:
@@ -13,57 +13,17 @@ Below are the frequently asked questions regarding either features, the overall
   Consider that the answer is best as a reference to another place in the documentation. (format of this FAQ taken from `RTD's own FAQ <https://docs.readthedocs.io/en/stable/faq.html>`_)
 
 What tools are installed in Exegol?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===================================
 
 The list of tools is dynamically generated for all Exegol images and available :doc:`here </exegol-image/tools>`.
 
-Unable to connect to Docker
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There are multiple checks to do to make sure Docker works properly.
-
-.. tabs::
-
-    .. tab:: Docker service
-
-        The Docker service must installed up and running.
-
-        - For Windows users: Docker Desktop for Windows must be up and running.
-        - For macOS users: Docker Desktop for Mac (or `OrbStack <https://orbstack.dev/>`_) must be up and running.
-
-    .. tab:: Docker permissions
-
-        Make sure the Docker permissions are consistent with the Exegol permissions. For instance, if you need ``sudo`` rights to use Docker, you'll most likely need ``sudo`` to run Exegol smoothly. See :doc:`the Exegol install guidance</getting-started/install>`.
-
-    .. tab:: Docker socket
-
-        The following command can be used to see the docker socket that is used by default: ``docker context ls``.
-
-        * For `OrbStack <https://orbstack.dev/>`_ users (on macOS), the "orb socket" must be used.
-        * For Docker Desktop users (macOS/Windows), the "Docker desktop socket" must be used.
-        * For Linux users, the default socket should work.
-
-        Switching context can be done with ``docker context use <context>``.
-        For instance, switching from a Docker Desktop to OrbStack could be done with ``docker context use orbstack``.
-
-    .. tab:: Symbolic link
-
-        The following symbolic link must exist ``/var/run/docker.sock`` and point to the correct socket. Below is an example of what it should look like.
-
-        .. code-block::
-
-            (Host) ~ $ ls -la /var/run/docker.sock
-            lrwxr-xr-x  1 root  daemon  38 Jul 28 09:02 /var/run/docker.sock -> /Users/someuser/.orbstack/run/docker.sock
-
-        If the link does not exist, it could be created with the following command ``ln -sf /Users/someuser/.orbstack/run/docker.sock /var/run/docker.sock``. This is an example for `OrbStack <https://orbstack.dev/>`_. The command must be adapted to the user's context.
-
 Can I contribute to the project?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+================================
 
 Yes, please refer to the :doc:`contributors section </community/contributors>`.
 
 Can I run Exegol on a macOS?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============================
 
 Yes. And both CPU architectures are supported (Intel X86_64 (AMD64) and Apple Silicon M1/M2 (ARM64).
 
@@ -73,7 +33,7 @@ Yes. And both CPU architectures are supported (Intel X86_64 (AMD64) and Apple Si
 
 
 Can I use a VPN with Exegol?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============================
 
 Yes. And you have multiple choices.
 
@@ -85,7 +45,7 @@ Yes. And you have multiple choices.
     Creating a **privileged** container (c.f. the "YOLO" choice) exposes you to higher security risks. This should be avoided.
 
 Can I customize Exegol?
-~~~~~~~~~~~~~~~~~~~~~~~
+=======================
 
 Yes, please refer to the :doc:`"my-resources" documentation </exegol-image/my-resources>` that explains how to automatically setup your changes to your Exegol containers.
 Also, see the :doc:`"wrapper's advanced-uses" documentation </exegol-wrapper/advanced-uses>` to see how to edit Exegol's conf among other things.
@@ -94,14 +54,14 @@ You could also want to :ref:`make your own Exegol image <custom_image>`
 .. _custom_image:
 
 Can I make my own Exegol image?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===============================
 
 Yes. You will need to create a dockerfile (e.g. ``CUSTOM.dockerfile``) at the root of the exegol-images module next to the other dockerfiles (i.e. ``/path/to/Exegol/exegol-docker-build/``) containing the instructions you want the build process to follow.
 
 Then, run something like ``exegol install "myimagename" "CUSTOM"`` to build the image locally. See the ``install`` documentation: :doc:`install action </exegol-wrapper/install>`.
 
 How to install Exegol on an external drive?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===========================================
 
 Exegol's wrapper is lightweight, but it's Docker images can take up some space, and users may not have enough room in their internal HDD/SSD, hence the question. This usually comes down to "how can I install Docker on an external drive?", and the answer depends on the host.
 
@@ -116,7 +76,7 @@ For macOS and Windows users, this can be configured in the Docker Desktop dashbo
     :alt: Disk Image Location Setting (Docker Desktop)
 
 How to add a new tool?
-~~~~~~~~~~~~~~~~~~~~~~
+======================
 
 "Adding a tool" can mean many things. Depending on that, you'll get a different answer. So let's answer most of them.
 
@@ -127,21 +87,8 @@ If you want to add a tool:
 * **in a live container**: that's your container, you can do whatever you whish in it ;)
 * **automatically in all containers at their creation**: refer to the :doc:`"my-resources" documentation </exegol-image/my-resources>`.
 
-How do I get X11 to work on a non-Linux host?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-X11, or X Window System, is a graphical windowing system that provides a framework for creating and managing graphical user interfaces (GUIs) in Unix-like operating systems.
-
-X11 sharing between an Exegol container and a host allows a graphical application running within the container to display its GUI on the host's X11 server. This means you can run graphical applications in Exegol containers and have them appear as if they were running directly on the host machine. It enables the execution of GUI-based applications in isolated containers while interacting with them through the host's graphical interface.
-
-For macOS users, XQuartz is needed. It's listed in the :ref:`install requirements <install_requirements>`.
-
-.. note::
-
-    Exegol's wrapper automatically starts XQuartz on macOS hosts when needed. But if for some reason it gets manually closed by the users while a container is running, X11 sharing will not work. Restarting the container with ``exegol restart <container>`` will restart XQuartz automatically if needed.
-
 Can I install docker directly on my WSL2 distro instead of Docker Desktop ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===========================================================================
 
 Yes, it's possible to install docker directly on WSL2 rather than using Docker Desktop, but you'll be restricted to your WSL2 environment and its constraints.
 
@@ -151,7 +98,7 @@ We therefore recommend **Docker Desktop as the official support** for Exegol.
 We do **not** guarantee wrapper stability with a directly installed WSL docker.
 
 How to retrieve your desktop login details ?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============================================
 
 The container's root password can be obtained with ``exegol info <container>`` (i.e. this is needed when using the :doc:`desktop </the-exegol-project/python-wrapper>` feature)
 

source/getting-started/install.rst

@@ -281,6 +281,7 @@ The installation of Exegol on Linux, macOS and Windows are very similar. It can
         If not, remember that pip installs binaries in a **dedicated** local folder, which then **must** be in the ``PATH`` environment variable.
         Try to fix your pip installation: `Linux <https://stackoverflow.com/a/62823029>`__ | `MacOS <https://stackoverflow.com/a/43368894>`__ | `Windows <https://builtin.com/software-engineering-perspectives/pip-command-not-found>`__
 
+.. _install_exegol_privileges:
 
 3. Run Exegol with appropriate privileges
 -----------------------------------------
@@ -340,7 +341,7 @@ The installation of Exegol on Linux, macOS and Windows are very similar. It can
 
     ..  group-tab:: Windows
 
-        Exegol should **NOT** be used as admin on Windows. Docker Desktop doesn't require administrator privileges.
+        Exegol should **NOT** be used as admin on Windows and **NOT** as root in a WSL instance. Docker Desktop doesn't require administrator privileges.
 
 
 4. Installation of the first Exegol image
@@ -415,12 +416,12 @@ Exegol (wrapper) supports auto-completion in many shell environments but there i
 
         .. group-tab:: Zsh
 
-            To activate completions for zsh you need to have ``bashcompinit`` enabled in zsh:
+            To activate completions for zsh you need to have ``compinit`` enabled in zsh:
 
             .. code-block:: bash
 
-                autoload -U bashcompinit
-                bashcompinit
+                autoload -U compinit
+                compinit
 
             Afterwards you can enable completion by adding the following command in your ``~/.zshrc`` config:
 

source/getting-started/troubleshooting.rst

@@ -0,0 +1,95 @@
+===============
+Troubleshooting
+===============
+
+Here are the most common problems encountered when installing and using Exegol.
+
+.. contents::
+    :local:
+
+Unable to connect to Docker
+===========================
+
+There are multiple checks to do to make sure Docker works properly.
+
+.. tabs::
+
+    .. tab:: Docker service
+
+        The Docker service must installed up and running.
+
+        - For Windows users: Docker Desktop for Windows must be up and running.
+        - For macOS users: Docker Desktop for Mac (or `OrbStack <https://orbstack.dev/>`_) must be up and running.
+
+    .. tab:: Docker permissions
+
+        Make sure the Docker permissions are consistent with the Exegol permissions.
+        For instance, if you need ``sudo`` rights to use Docker, you'll most likely need ``sudo`` to run Exegol smoothly.
+
+        See :ref:`the Exegol install guidance<install_exegol_privileges>` to use exegol correctly with sudo.
+
+    .. tab:: Docker socket
+
+        The following command can be used to see the docker socket that is used by default: ``docker context ls``.
+
+        * For `OrbStack <https://orbstack.dev/>`_ users (on macOS), the "orb socket" must be used.
+        * For Docker Desktop users (macOS/Windows), the "Docker desktop socket" must be used.
+        * For Linux users, the default socket should work.
+
+        Switching context can be done with ``docker context use <context>``.
+        For instance, switching from a Docker Desktop to OrbStack could be done with ``docker context use orbstack``.
+
+    .. tab:: Symbolic link
+
+        The following symbolic link must exist ``/var/run/docker.sock`` and point to the correct socket. Below is an example of what it should look like.
+
+        .. code-block::
+
+            (Host) ~ $ ls -la /var/run/docker.sock
+            lrwxr-xr-x  1 root  daemon  38 Jul 28 09:02 /var/run/docker.sock -> /Users/someuser/.orbstack/run/docker.sock
+
+        If the link does not exist, it could be created with the following command ``ln -sf /Users/someuser/.orbstack/run/docker.sock /var/run/docker.sock``. This is an example for `OrbStack <https://orbstack.dev/>`_. The command must be adapted to the user's context.
+
+How do I get X11 to work on a non-Linux host?
+=============================================
+
+X11, or X Window System, is a graphical windowing system that provides a framework for creating and managing graphical user interfaces (GUIs) in Unix-like operating systems.
+
+X11 sharing between an Exegol container and a host allows a graphical application running within the container to display its GUI on the host's X11 server. This means you can run graphical applications in Exegol containers and have them appear as if they were running directly on the host machine. It enables the execution of GUI-based applications in isolated containers while interacting with them through the host's graphical interface.
+
+For macOS users, XQuartz is needed. It's listed in the :ref:`install requirements <install_requirements>`.
+
+.. note::
+
+    Exegol's wrapper automatically starts XQuartz on macOS hosts when needed. But if for some reason it gets manually closed by the users while a container is running, X11 sharing will not work. Restarting the container with ``exegol restart <container>`` will restart XQuartz automatically if needed.
+
+How to fix ``Docker download error: unauthorized: authentication required``
+===========================================================================
+
+Docker image downloads may be time-sensitive. In the case of dual-boot systems, it is common to experience time lags of a few hours.
+
+To correct the problem, check that your computer's date and time are correct.
+
+How to fix CRLF errors on Windows
+=================================
+
+If you have cloned the Exegol repository on Windows, you may encounter errors when launching your container, for example:
+
+.. code-block::
+
+    /.exegol/entrypoint.sh: line 3: trap: SIGTERM
+    : invalid signal specification
+    /.exegol/entrypoint.sh: line 4: $'\r': command not found
+    /.exegol/entrypoint.sh: line 5: syntax error near unexpected token $'{\r''
+    /.exegol/entrypoint.sh: line 5: function exegol_init() {
+
+This is caused by the automatic addition of CRLF linefeed by Windows to ensure compatibility.
+To correct this problem, simply disable this feature on the Exegol repository and reload the file of the repository:
+
+.. code-block:: bash
+
+    cd ./Exegol
+    git config core.autocrlf false
+    git rm -rf --cached .
+    git reset --hard HEAD
+

source/index.rst

@@ -93,6 +93,7 @@ Wanna chat? Need help? Join us on the `Exegol discord`_!
    :caption: Getting started
 
    getting-started/install.rst
+   getting-started/troubleshooting.rst
    getting-started/updates.rst
    getting-started/faq.rst
    getting-started/tips-and-tricks.rst