Update install, new alias tips and desktop

source/exegol-image/my-resources.rst

@@ -91,7 +91,7 @@ To automatically:
 
 
 :code:`firefox` (addons, CA)
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .. seealso::
     Available from version ``3.0.2`` of any exegol image.
 

source/getting-started/faq.rst

@@ -150,4 +150,9 @@ 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)
+
 .. TODO: add a note, when the Desktop feature is in prod, that explains the ups and dows of X11 vs. Desktop mode.

source/getting-started/install.rst

@@ -31,7 +31,7 @@ Additional dependencies may be required depending on the host OS.
 
 ..  tabs::
 
-    ..  tab:: Linux
+    ..  group-tab:: Linux
 
         No additional dependencies for Linux environments.
 
@@ -41,8 +41,7 @@ Additional dependencies may be required depending on the host OS.
 
            .. code-block:: bash
 
-              curl -fsSL "https://get.docker.com/" -o get-docker.sh
-              sh get-docker.sh
+              curl -fsSL "https://get.docker.com/" | sh
 
         .. warning::
 
@@ -62,7 +61,7 @@ Additional dependencies may be required depending on the host OS.
 
             `Docker "Rootless mode" <https://docs.docker.com/engine/security/rootless/>`_ is not supported by Exegol as of yet. Please follow the install procedure mentionned above.
 
-    ..  tab:: macOS
+    ..  group-tab:: macOS
 
         To support graphical applications (:ref:`display sharing functionality <feature_x11_sharing>`, e.g. Bloodhound, Wireshark, Burp, etc.), additional dependencies and configuration are required:
 
@@ -86,6 +85,14 @@ Additional dependencies may be required depending on the host OS.
 
             macOS Docker Desktop resources requirement
 
+        .. warning::
+
+            You'll also need to add the exegol source folder (or, more precisely, the folder ``[...]/exegol/utils/imgsync``).
+
+            If you install Exegol from the python pip package, this folder is located where the python packages are installed.
+            The path to this folder depends on how you installed python. When creating your first container, you may get an error disclosing the exegol installation folder, which will have to be added as an authorized resource.
+
+
         .. tip::
 
             `OrbStack <https://orbstack.dev/>`__ for **Mac** is supported by Exegol wrapper from ``v4.2.0``.
@@ -117,6 +124,13 @@ Additional dependencies may be required depending on the host OS.
 
             Please note that it is **not** advisable to use Exegol from both environments at the same time, as this could lead to conflicts and Exegol does not officially support this configuration.
 
+        .. warning::
+
+            You may want to disable Windows Defender during the installation, as Exegol will download pre-built remote shells (or temporarily exclude ``C:\Users\<username>\AppData\Local\Temp`` or the source file directory).
+
+            You should also add the folder ``C:\Users\<user>\.exegol\exegol-resources`` to the exclusion list.
+
+
 .. _exegol_install:
 
 Installation
@@ -129,84 +143,93 @@ The installation of Exegol on Linux, macOS and Windows are very similar. It can
 -------------------------
 
 ..  tabs::
+    ..  group-tab:: Installing with pipx (preferred)
 
-    ..  group-tab:: Installing with pip
+        The pre-compiled Exegol’s wrapper can be installed from the PyPI repository.
+        While this is the easiest and most user-friendly technique, it is advised to install from sources, as it allows to switch from release to dev branches easily and it supports the auto-update feature.
 
-        Exegol's wrapper can be installed from pip.
-        While this is the easiest and most user-friendly technique, for more advanced users it is advised to install from sources, as it allows to switch from release to dev branches easily and the auto-update feature is supported.
+        Using ``pipx`` allows you to install Exegol in an **isolated** virtual environment **dedicated** to it.
+
+        First, ``pipx`` must be installed on your host system:
 
         .. code-block:: bash
 
-           python3 -m pip install exegol
+            # install pipx if not already installed, from system package:
+            sudo apt update && sudo apt install pipx
+            # OR from pip
+            python3 -m pip install pipx
 
-        .. warning::
+        Exegol's wrapper can be installed with ``pipx`` either from **sources** or pre-compiled from **PyPI**:
 
-            You may want to disable Windows Defender during the installation, as Exegol will download pre-built remote shells (or temporarily exclude ``C:\Users\<username>\AppData\Local\Temp``).
+        .. code-block:: bash
 
-            You should also add the folder ``C:\Users\<user>\.exegol\exegol-resources`` to the exclution list.
+            # You can now install Exegol package from PyPI
+            pipx install exegol
+
+            # Or from sources directly
+            pipx install git+https://github.com/ThePorgs/Exegol
 
     ..  group-tab:: Installing from sources
 
-        Exegol's wrapper can also be installed from sources (with Git). The wrapper then knows how to self-update, and switching from release and development branches is possible and very easy.
+        Exegol's wrapper can be installed from sources (with Git). The wrapper then knows how to self-update, and switching from release and development branches is possible and very easy.
 
         .. code-block:: bash
 
-           git clone "https://github.com/ThePorgs/Exegol"
+            git clone "https://github.com/ThePorgs/Exegol"
 
         .. tip::
 
-            If you want a **light** clone of Exegol (and **never** use the **dev** branch), you can use the following command:
+           If you want a **light** clone of Exegol (and **never** use the **dev** branch), you can use the following command:
 
-            .. code-block:: bash
+           .. code-block:: bash
 
-                git clone --shallow-since="2023/05/08" "https://github.com/ThePorgs/Exegol"
+               git clone --shallow-since="2023/05/08" "https://github.com/ThePorgs/Exegol"
 
         If you have access to docker directly as a user, you can install the requirements only for your current user
         otherwise the requirements must be installed as root to run Exegol with sudo.
 
         .. tabs::
 
-            .. tab:: With sudo
+           .. tab:: With sudo
 
-                .. code-block:: bash
+               .. code-block:: bash
 
-                   sudo python3 -m pip install --requirement "Exegol/requirements.txt"
+                  sudo python3 -m pip install --requirement "Exegol/requirements.txt"
 
-            .. tab:: Directly as user
+           .. tab:: Directly as user
 
-                .. code-block:: bash
+               .. code-block:: bash
 
-                   python3 -m pip install --user --requirement "Exegol/requirements.txt"
+                  python3 -m pip install --user --requirement "Exegol/requirements.txt"
 
-    ..  tab:: Installing with pipx
+    ..  group-tab:: Installing with pip
 
-        Exegol's wrapper can also be installed with pipx either from sources or PyPI, which allows to install Exegol in a virtual environment of its own.
+        The pre-compiled Exegol’s wrapper can be installed from the PyPI repository.
+        While this is the easiest and most user-friendly technique, it is advised to install from sources, as it allows to switch from release to dev branches easily and it supports the auto-update feature.
 
         .. code-block:: bash
 
-            # install pipx if not already installed
-            python3 -m pip install pipx
-
-            # from sources
-            pipx install git+https://github.com/ThePorgs/Exegol
+           python3 -m pip install exegol
 
-            # packaged from PyPI
-            pipx install exegol
+        .. warning::
 
+            In some cases, it is no longer possible to add a pip package system-wide (PEP 668). In such cases, it is preferable to use ``pipx``.
 
 
 2. Adding Exegol to the ``PATH``
 --------------------------------
 
 ..  tabs::
 
-    ..  group-tab:: Installing with pip
+    ..  group-tab:: Installing with pipx (preferred)
 
-        If your pip installation is correct and functional, you have nothing more to do and you can already use the command ``exegol``.
+        In order to use pipx applications, the pipx environment must be set in your PATH:
 
-        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>`__
+        .. code-block:: bash
+
+            pipx ensurepath
 
+        Dont forget to open a **new terminal** to reload your PATH before continuing.
 
     ..  group-tab:: Installing from sources
 
@@ -232,7 +255,7 @@ The installation of Exegol on Linux, macOS and Windows are very similar. It can
                     if (!(Test-Path -Path $PROFILE)) {
                         New-Item -ItemType File -Path $PROFILE -Force
                     }
-                
+
                 Create alias for Exegol in `$PROFILE`:
 
                 .. code-block:: powershell
@@ -254,22 +277,112 @@ The installation of Exegol on Linux, macOS and Windows are very similar. It can
 
                     It is possible to disable this behavior in the Windows settings: ``Apps > Apps & features > App execution aliases`` and disable aliases for ``python.exe`` and ``python3.exe``.
 
-3. (Optional) Using Exegol auto-completion
+    ..  group-tab:: Installing with pip
+
+        If your pip installation is correct and functional, you have nothing more to do and you can already use the command ``exegol``.
+
+        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>`__
+
+
+3. Run Exegol with appropriate privileges
+-----------------------------------------
+
+
+..  tabs::
+
+    ..  group-tab:: Linux
+
+        Exegol does not support rootless docker. To interact with docker, you must either have your user be a member of the docker group to use exegol as a user, or run Exegol with root privileges using sudo.
+
+        ..  tabs::
+
+            .. tab:: Run as root (preferred)
+
+                To run Exegol as root with sudo, you must use a specific sudo command. For a better user experience, we recommend using an alias:
+
+                ..  tabs::
+
+                    .. group-tab:: Bash
+
+                        .. code-block:: bash
+
+                            echo "alias exegol='sudo -E $(which exegol)'" >> ~/.bash_aliases
+                            source ~/.bashrc
+
+                    .. group-tab:: Zsh
+
+                        .. code-block:: bash
+
+                            echo "alias exegol='sudo -E $(which exegol)'" >> ~/.zshrc
+                            source ~/.zshrc
+
+            .. tab:: Run as user
+
+                .. warning::
+
+                    By giving the user direct access to docker, this allows the user to compromise the host and become **root** on the machine with full access to the file system.
+
+                    For more information, official Docker documentation shows `how to manage docker as a non root user <https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-userm>`_.
+
+                If you accept this risk because the environment is not critical and you prefer ease of use without the security control provided by sudo, you can apply the following method to use exegol directly as a user:
+
+               .. code-block:: bash
+
+                    # add the sudo group to the user
+                    sudo usermod -aG docker $(id -u -n)
+
+                    # To apply the new group you must open a new shell
+                    exit
+                    # OR "reload" the user groups with the newly added docker group
+                    newgrp docker
+
+    ..  group-tab:: macOS
+
+        Exegol should **NOT** be used as root on macOS. Docker Desktop (or Orbstack) do not require root privileges.
+
+    ..  group-tab:: Windows
+
+        Exegol should **NOT** be used as admin on Windows. Docker Desktop doesn't require administrator privileges.
+
+
+4. Installation of the first Exegol image
+-----------------------------------------
+
+Once the exegol wrapper is installed, you can download your first docker image with the following command:
+
+.. code-block:: bash
+
+   exegol install
+
+
+5. (Optional) Using Exegol auto-completion
 ------------------------------------------
 
 Exegol (wrapper) supports auto-completion in many shell environments but there is a configuration to add (on the host) for this feature to work.
 
+.. important::
+
+    The following configurations must be made in your **host** environment.
+
 .. tip::
 
-    If you have a source installation, make sure you have installed (or updated) the ``requirements.txt`` packages before using the completer.
+    If the command ``register-python-argcomplete`` is not found on your host, you have to install it:
 
-.. important::
+    .. code-block:: bash
 
-    The following configurations must be made in your **host** environment.
+        # Using the system package manager
+        sudo apt install python3-argcomplete
+
+        # Or using pip (check if pip packages are included in your $PATH)
+        pip3 install --user argcomplete
+
+        # Or using pipx (check if pipx packages are included in your $PATH)
+        pipx install argcomplete
 
 ..  tabs::
     ..  tabs::
-        .. tab:: Bash
+        .. group-tab:: Bash
 
             You can enable Exegol auto-completion for your **current user** with your ``.bashrc`` or you can enable the auto-completion **system-wide** with ``bash-completion``.
 
@@ -303,7 +416,7 @@ Exegol (wrapper) supports auto-completion in many shell environments but there i
             .. tip::
                 If you have multiple tools using ``argcomplete`` you can also use the `global completion <https://kislyuk.github.io/argcomplete/#global-completion>`__ method (need bash >= 4.2).
 
-        .. tab:: Zsh
+        .. group-tab:: Zsh
 
             To activate completions for zsh you need to have ``bashcompinit`` enabled in zsh:
 
@@ -318,7 +431,7 @@ Exegol (wrapper) supports auto-completion in many shell environments but there i
 
                 eval "$(register-python-argcomplete --no-defaults exegol)"
 
-        .. tab:: Fish
+        .. group-tab:: Fish
 
             To activate completions for fish use:
 
@@ -332,7 +445,7 @@ Exegol (wrapper) supports auto-completion in many shell environments but there i
 
                 register-python-argcomplete --no-defaults --shell fish exegol > ~/.config/fish/completions/exegol.fish
 
-        .. tab:: Tcsh
+        .. group-tab:: Tcsh
 
             To activate completions for tcsh use:
 
@@ -367,13 +480,3 @@ Exegol (wrapper) supports auto-completion in many shell environments but there i
                 .. code-block:: powershell
 
                     echo "Set-PSReadlineKeyHandler -Key Tab -Function MenuComplete" >> $PROFILE
-
-4. Installation of the first Exegol image
------------------------------------------
-
-Once the exegol wrapper is installed, you can download your first docker image with the following command:
-
-.. code-block:: bash
-
-   exegol install
-