diff --git a/docs/docsite/rst/installation_guide/installation_distros.rst b/docs/docsite/rst/installation_guide/installation_distros.rst index da4b4b94a9..47da35975d 100644 --- a/docs/docsite/rst/installation_guide/installation_distros.rst +++ b/docs/docsite/rst/installation_guide/installation_distros.rst @@ -3,17 +3,25 @@ Installing Ansible on specific operating systems ================================================ -.. note:: These instructions are provided by their respective communities. Any bugs/issues should be filed with that community to update these instructions. Ansible maintains only the ``pip install`` instructions. +.. note:: + These instructions come from their respective communities. + If you encounter bugs or issues, file them with that community to update these instructions. + Ansible maintains only the ``pip install`` instructions. -The ``ansible`` package can always be :ref:`installed from PyPI using pip ` on most systems but it is also packaged and maintained by the community for a variety of Linux distributions. +You can always :ref:`install the ansible package from PyPI using pip ` on most systems. +The community also packages and maintains Ansible for various Linux distributions. -This document guides you through installing Ansible from different distribution's package repositories. +This guide shows you how to install Ansible from different distribution package repositories. -To add instructions for another distribution to this guide, package maintainers **must** do the following: +Requirements for adding new distributions +----------------------------------------- - * Ensure the distribution provides a reasonably up-to-date version of ``ansible``. - * Ensure that ``ansible-core`` and ``ansible`` versions are kept in sync to the extent that the build system allows. - * Provide a way to contact the distribution maintainers as part of the instructions. Distribution maintainers are also encouraged to join the `Ansible Packaging `_ Matrix room. +Package maintainers who want to add instructions for another distribution to this guide must meet the following requirements: + +* Ensure the distribution provides a reasonably up-to-date version of ``ansible``. +* Keep ``ansible-core`` and ``ansible`` versions synchronized to the extent that the build system allows. +* Provide a way to contact the distribution maintainers as part of the instructions. +* Distribution maintainers are also encouraged to join and monitor the `Ansible Packaging `_ Matrix room. .. contents:: :local: @@ -21,64 +29,64 @@ To add instructions for another distribution to this guide, package maintainers Installing Ansible on Fedora Linux ---------------------------------- -To install the full ``ansible`` package run: +Fedora Linux provides both the full Ansible package and the minimal ansible-core package through the standard repositories. + +Install the full ``ansible`` package: .. code-block:: bash $ sudo dnf install ansible -To install the minimal ``ansible-core`` package run: +Install the minimal ``ansible-core`` package: .. code-block:: bash $ sudo dnf install ansible-core -Several Ansible collections are also available from the Fedora repositories as -standalone packages that users can install alongside ``ansible-core``. -For example, to install the ``community.general`` collection run: +Fedora repositories include several Ansible collections as standalone packages that you can install alongside ``ansible-core``. +For example, install the ``community.general`` collection: .. code-block:: bash $ sudo dnf install ansible-collection-community-general See the `Fedora Packages index `_ -for a full list of Ansible collections packaged in Fedora. +for a complete list of Ansible collections packaged in Fedora. -Please `file a bug `_ against the -``Fedora`` product in Red Hat Bugzilla to reach the package maintainers. +Contact the package maintainers by `filing a bug `_ against the ``Fedora`` product in Red Hat Bugzilla. Installing Ansible from EPEL ---------------------------- -Users of CentOS Stream, Almalinux, Rocky Linux, and related distributions -can install ``ansible`` or Ansible collections from the community maintained -`EPEL `_ -(Extra Packages for Enterprise Linux) repository. -After `enabling the EPEL repository `_, -users can use the same ``dnf`` commands as for Fedora Linux. +If you use CentOS Stream, Almalinux, Rocky Linux, or related distributions, you can install ``ansible`` or Ansible collections from the community-maintained `EPEL `_ (Extra Packages for Enterprise Linux) repository: -Please `file a bug `_ against the -``Fedora EPEL`` product in Red Hat Bugzilla to reach the package maintainers. +1. `Enable the EPEL repository `_. +2. Use the same ``dnf`` commands as for Fedora Linux. +Contact the package maintainers by `filing a bug `_ against the ``Fedora EPEL`` product in Red Hat Bugzilla. Installing Ansible on OpenSUSE Tumbleweed/Leap ---------------------------------------------- +OpenSUSE provides Ansible packages through the standard package manager. + .. code-block:: bash $ sudo zypper install ansible -See `OpenSUSE Support Portal `_ for additional help with Ansible on OpenSUSE. +See the `OpenSUSE Support Portal `_ for additional help with Ansible on OpenSUSE. .. _from_apt: Installing Ansible on Ubuntu ---------------------------- +Ubuntu provides Ansible packages through a Personal Package Archive (PPA) that contains more recent versions than the standard repositories. + Ubuntu builds are available `in a PPA here `_. -To configure the PPA on your system and install Ansible run these commands: +Configure the PPA on your system and install Ansible: .. code-block:: bash @@ -87,17 +95,22 @@ To configure the PPA on your system and install Ansible run these commands: $ sudo add-apt-repository --yes --update ppa:ansible/ansible $ sudo apt install ansible -.. note:: On older Ubuntu distributions, "software-properties-common" is called "python-software-properties". You may want to use ``apt-get`` rather than ``apt`` in older versions. Also, be aware that only newer distributions (that is, 18.04, 18.10, and later) have a ``-u`` or ``--update`` flag. Adjust your script as needed. +.. note:: + On older Ubuntu distributions, "software-properties-common" is called "python-software-properties". + You may want to use ``apt-get`` rather than ``apt`` in older versions. + Also, only newer distributions (18.04, 18.10, and later) have a ``-u`` or ``--update`` flag. + Adjust your script as needed. File any issues in `the PPA's issue tracker `_. - Installing Ansible on Debian ---------------------------- -While Ansible is available from the `main Debian repository `_, it can be out of date. +Debian users can choose between the standard repository or the Ubuntu PPA for more recent versions. -To get a more recent version, Debian users can use the Ubuntu PPA according to the following table: +While Ansible is available from the `main Debian repository `_, this version can be outdated. + +For a more recent version, Debian users can use the Ubuntu PPA according to the following table: .. list-table:: :header-rows: 1 @@ -119,10 +132,10 @@ To get a more recent version, Debian users can use the Ubuntu PPA according to t - Ubuntu 18.04 (Bionic) - ``bionic`` -In the following example, we assume that you have wget and gpg already installed (``sudo apt install wget gpg``). +The following example assumes that you already have ``wget`` and ``gpg`` installed. -Run the following commands to add the repository and install Ansible. -Set ``UBUNTU_CODENAME=...`` based on the table above (we use ``jammy`` in this example). +Add the repository and install Ansible. +Set ``UBUNTU_CODENAME=...`` based on the table above (we use ``jammy`` in this example): .. code-block:: bash @@ -131,39 +144,37 @@ Set ``UBUNTU_CODENAME=...`` based on the table above (we use ``jammy`` in this e $ echo "deb [signed-by=/usr/share/keyrings/ansible-archive-keyring.gpg] http://ppa.launchpad.net/ansible/ansible/ubuntu $UBUNTU_CODENAME main" | sudo tee /etc/apt/sources.list.d/ansible.list $ sudo apt update && sudo apt install ansible -Note: the " " around the keyserver URL are important. -Around the "echo deb" it is important to use " " rather than ' '. +.. note:: + Use double quotes around the keyserver URL and in the "echo deb" command like in the example above. These commands download the signing key and add an entry to apt's sources pointing to the PPA. Previously, you may have used ``apt-key add``. -This is now `deprecated `_ -for security reasons (on Debian, Ubuntu, and elsewhere). -For more details, see `this AskUbuntu post `_. -Also note that, for security reasons, we do NOT add the key to ``/etc/apt/trusted.gpg.d/`` -nor to ``/etc/apt/trusted.gpg`` where it would be allowed to sign releases from ANY repository. +The ``apt-key add`` approach is now `deprecated `_ for security reasons (on Debian, Ubuntu, and elsewhere). + +As such, we do NOT add the key to ``/etc/apt/trusted.gpg.d/`` or to ``/etc/apt/trusted.gpg`` where the key would be allowed to sign releases from ANY repository. Installing Ansible on Arch Linux -------------------------------- -To install the full ``ansible`` package run: +Arch Linux provides both the full Ansible package and ansible-core through the standard package repositories. + +Install the full ``ansible`` package: .. code-block:: bash $ sudo pacman -S ansible -To install the minimal ``ansible-core`` package run: +Install the minimal ``ansible-core`` package: .. code-block:: bash $ sudo pacman -S ansible-core -Several Ansible ecosystem packages are also available from the Arch Linux repositories as -standalone packages that users can install alongside ``ansible-core``. -See the `Arch Linux Packages index `_ -for a full list of Ansible packages in Arch Linux. +Arch Linux repositories include several Ansible ecosystem packages as standalone packages that you can install alongside ``ansible-core``. +See the `Arch Linux Packages index `_ for a complete list of Ansible packages in Arch Linux. -Please `open an issue `_ in the related package GitLab repository to reach the package maintainers. +Contact the package maintainers by `opening an issue `_ in the related package GitLab repository. .. _from_windows: