[pbs-devel] [PATCH proxmox-backup] docs: installation: several small fixes/improvements

Tue Nov 26 17:22:46 CET 2024

On Tue Nov 26, 2024 at 4:57 PM CET, Alexander Zeidler wrote:
> * consistently use "medium" (singular), as only one is needed for
>   installation (installation-media.rst not renamed)
> * add short introduction to recently added chapter "Installation Media"
> * update minimum required flash drive storage space to 2 GB
> * remove CD-ROM (too less storage space available) but keep DVD

this would be too little, too less is grammatically incorrect

> * mention explicitly that data get overwritten on installation media /
>   installation target disks
> * mention that using `dd` requires to be the root user or use `sudo`
> * add accidentally cut off text when copying from PVE docs
> * add reference labels to currently needed section titles
> * reword some paragraphs for completeness and readability
> * mention all installation methods in the intro of "Server Installation"
> * add the boot order as possible boot issue
> * remove recently added redundant product website hyperlinks (as earlier
>   with commit 34407477e2)
> * fix broken heading level of APT-based PBC repo
>
> * slightly reorder sub-chapters of "Installation":
>
> After adding the chapter "Installation Media" (d363818641), the chapter
> order under "Installation" is:
>
> 1. System Requirements
> 2. Installation Media
> 3. Debian Package Repositories
> 4. Server Installation
> 5. Client Installation
>
> But repos are more likely to be configured after installation, and for
> other installation methods chapter links exist anyway. So to keep the
> chapter order more logical, "Debian Package Repositories" is now moved
> after "Client Installation".
>
> Signed-off-by: Alexander Zeidler <a.zeidler at proxmox.com>
> ---
>  docs/installation-media.rst   | 56 +++++++++++++++++++++--------------
>  docs/installation.rst         | 41 +++++++++++++++++--------
>  docs/package-repositories.rst |  2 +-
>  docs/using-the-installer.rst  | 25 ++++++++--------
>  4 files changed, 75 insertions(+), 49 deletions(-)
>
> diff --git a/docs/installation-media.rst b/docs/installation-media.rst
> index e109f2ba..ce293e4c 100644
> --- a/docs/installation-media.rst
> +++ b/docs/installation-media.rst
> @@ -1,44 +1,53 @@
> -.. _installation_media:
> +.. _installation_medium:
>
> -Installation Media
> -------------------
> +Installation Medium
> +-------------------
>
> -Prepare Installation Media
> -~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Proxmox Backup Server can be installed via
> +:ref:`different methods <install_pbs>`. The recommended method is the
> +usage of a installation medium, to simply boot the interactive

of *an* installation medium

> +installer.
> +
> +
> +Prepare Installation Medium
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
>  Download the installer ISO image from |DOWNLOADS|.
>
> -The `Proxmox Backup`_ Server installation media is a hybrid ISO image. It works
> -in two ways:
> +The Proxmox Backup Server installation medium is a hybrid ISO image.
> +It works in two ways:
>
> -- An ISO image file ready to burn to a CD or DVD.
> +- An ISO image file ready to burn to a DVD.
>
>  - A raw sector (IMG) image file ready to copy to a USB flash drive (USB stick).
>
> -Using a USB flash drive to install `Proxmox Backup`_ Server is the recommended
> -way since it is the faster option.
> +Using a USB flash drive to install Proxmox Backup Server is the
> +recommended way since it is the faster and more frequently available
> +option these days.
>
>  Prepare a USB Flash Drive as Installation Medium
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> -The flash drive needs to have at least 1 GB of storage available.
> +The flash drive needs to have at least 2 GB of storage space.
>
>  .. note::
>
> -   Do not use *UNetbootin*. It does not work with the `Proxmox Backup`_ Server
> -   installation image.
> +   Do not use *UNetbootin*. It does not work with the Proxmox Backup
> +   Server installation image.
>
>  .. important::
>
> -   Make sure that the USB flash drive is not mounted and does not
> -   contain any important data.
> +   Existing data on the USB flash drive will be overwritten. Therefore

comma missing after `Therefore`

> +   make sure that it does not contain any still needed data and
> +   unmount it afterwards again before proceeding.
>
>  Instructions for GNU/Linux
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> -On Unix-like operating system use the ``dd`` command to copy the ISO
> +On Unix-like operating systems use the ``dd`` command to copy the ISO
>  image to the USB flash drive. First find the correct device name of the
> -USB flash drive (see below). Then run the ``dd`` command.
> +USB flash drive (see below). Then run the ``dd`` command when logged
> +in as root user, or use ``sudo dd <…>`` otherwise.

sudo isn't available on all Unix-like operating system, it isn't on
proxmox backup server, for example.

if you want to keep this, maybe a more general "Depending on your
environment, you will need to have root privileges to execute ``dd``."
would be better.

>
>  .. code-block:: console
>
> @@ -132,16 +141,17 @@ Using Rufus
>
>  Rufus is a more lightweight alternative, but you need to use the **DD
>  mode** to make it work. Download Rufus from https://rufus.ie/. Either
> -install it or use
> +install it or use the portable version. Select the destination drive
> +and the downloaded Proxmox ISO file.
>
>  .. important::
>
>     Once you click *Start*, you have to click *No* on the dialog asking to
>     download a different version of Grub. In the next dialog select **DD mode**.
>
> -Boot your Server from the USB Flash Drive
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Use the Installation Medium
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> -Connect the USB flash drive to your server and make sure that booting from USB
> -is enabled (check your servers firmware settings). Then follow the steps of the
> -:ref:`installation wizard <using_the_installer>`.
> +Insert the created USB flash drive (or DVD) into your server. Continue
> +by reading the :ref:`installer <using_the_installer>` chapter, which
> +also describes possible boot issues.
> diff --git a/docs/installation.rst b/docs/installation.rst
> index 79cba840..2e93713a 100644
> --- a/docs/installation.rst
> +++ b/docs/installation.rst
> @@ -9,7 +9,7 @@ Debian_ from the provided package repository.
>
>  .. include:: installation-media.rst
>
> -.. include:: package-repositories.rst
> +.. _install_pbs:
>
>  Server Installation
>  -------------------
> @@ -20,24 +20,34 @@ for various management tasks such as disk management.
>  .. note:: You always need a backup server. It is not possible to use
>     Proxmox Backup without the server part.
>
> -The disk image (ISO file) provided by Proxmox includes a complete Debian system
> -as well as all necessary packages for the Proxmox Backup Server.
> +Using our provided disk image (ISO file) is the recommended
> +installation method, as it includes a convenient installer, a complete
> +Debian system as well as all necessary packages for the Proxmox Backup
> +Server.
> +
> +Once you created a :ref:`installation_medium`, the booted
> +:ref:`installer <using_the_installer>` will guide you through the
> +setup process. Thereby you partition the local disks, apply basic

imo there is an "a" missing here:

Thereby you partition the local disks, apply a basic...

> +system configuration like the timezone, language and network, and

imo settings after network would make this sound better, like this it
feels like something is missing. you don't really "apply the network",
you "apply network settings". or you do "apply a basic configuration for
the timezone, language and network".

> +finally install all required packages within minutes.
>
> -The installer will guide you through the setup process and allow
> -you to partition the local disk(s), apply basic system configuration
> -(for example timezone, language, network), and install all required packages.
> -The provided ISO will get you started in just a few minutes, and is the
> -recommended method for new and existing users.
> +As an alternative to the interactive installer, advanced users may
> +wish to install Proxmox Backup Server
> +:ref:`unattended <install_pbs_unattended>`.
>
> -Alternatively, Proxmox Backup Server can be installed on top of an
> -existing Debian system. This option is only recommended for advanced users
> -because detailed knowledge about Proxmox Backup Server is required.
> +With sufficient Debian knowledge, you can also install Proxmox Backup
> +Server :ref:`on top of Debian <install_pbs_on_debian>` yourself.
> +
> +While not recommended, Proxmox Backup Server could also be installed
> +:ref:`on Proxmox VE <install_pbs_on_pve>`.
>
>  .. include:: using-the-installer.rst
>
> +.. _install_pbs_unattended:
> +
>  Install `Proxmox Backup`_ Server Unattended
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> -It is possible to install `Proxmox Backup`_ Server automatically in an
> +It is possible to install Proxmox Backup Server automatically in an
>  unattended manner. This enables you to fully automate the setup process on
>  bare-metal. Once the installation is complete and the host has booted up,
>  automation tools like Ansible can be used to further configure the installation.
> @@ -51,6 +61,7 @@ installation ISO.  For more details and information on the unattended
>  installation see `our wiki
>  <https://pve.proxmox.com/wiki/Automated_Installation>`_.
>
> +.. _install_pbs_on_debian:
>
>  Install `Proxmox Backup`_ Server on Debian
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> @@ -88,6 +99,8 @@ support, and a set of common and useful packages.
>     your web browser, using HTTPS on port 8007. For example at
>     ``https://<ip-or-dns-name>:8007``
>
> +.. _install_pbs_on_pve:
> +
>  Install Proxmox Backup Server on `Proxmox VE`_
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>
> @@ -108,6 +121,8 @@ After configuring the
>     your web browser, using HTTPS on port 8007. For example at
>     ``https://<ip-or-dns-name>:8007``
>
> +.. _install_pbc:
> +
>  Client Installation
>  -------------------
>
> @@ -123,7 +138,7 @@ you need to run:
>    # apt update
>    # apt install proxmox-backup-client
>
> -
>  .. note:: The client-only repository should be usable by most recent Debian and
>     Ubuntu derivatives.
>
> +.. include:: package-repositories.rst
> diff --git a/docs/package-repositories.rst b/docs/package-repositories.rst
> index b429b4b4..aecd6c64 100644
> --- a/docs/package-repositories.rst
> +++ b/docs/package-repositories.rst
> @@ -149,7 +149,7 @@ Currently there's only a client-repository for APT based systems.
>  .. _package_repositories_client_only_apt:
>
>  APT-based Proxmox Backup Client Repository
> -++++++++++++++++++++++++++++++++++++++++++
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
>  For modern Linux distributions using `apt` as package manager, like all Debian
>  and Ubuntu Derivative do, you may be able to use the APT-based repository.
> diff --git a/docs/using-the-installer.rst b/docs/using-the-installer.rst
> index cec640c5..85d7c75b 100644
> --- a/docs/using-the-installer.rst
> +++ b/docs/using-the-installer.rst
> @@ -17,26 +17,27 @@ It includes the following:
>
>  * Web-based management interface
>
> -.. note:: All existing data on the selected drives will be removed during the
> -   installation process. The installer does not add boot menu entries for other
> -   operating systems.
> +.. note:: Any existing data on the selected drives will be overwritten
> +   during the installation process. The installer does not add boot
> +   menu entries for other operating systems.
>
> -Please insert the :ref:`installation_media` (for example, USB flash drive or
> -CD-ROM) and boot from it.
> +Please insert the :ref:`installation_medium` (for example, USB flash
> +drive or DVD) and boot from it.
>
> -.. note:: Make sure that booting from the installation medium (for example, USB)
> -   is enabled in your server's firmware settings. Secure boot needs to be
> -   disabled when booting an installer prior to `Proxmox Backup`_ Server version
> -   3.1.
> +.. note:: You may need to go into your server's firmware settings, to
> +   enable booting from your installation medium (for example, USB) and
> +   set the desired boot order. When booting an installer prior to
> +   `Proxmox Backup`_ Server version 3.1, Secure Boot needs to be
> +   disabled.
>
>  .. image:: images/screenshots/pbs-installer-grub-menu.png
>    :target: _images/pbs-installer-grub-menu.png
>    :align: right
>    :alt: Proxmox Backup Server Installer GRUB Menu
>
> -After choosing the correct entry (for example, *Boot from USB*) the `Proxmox
> -Backup`_ Server menu will be displayed, and one of the following options can be
> -selected:
> +After choosing the correct entry (for example, *Boot from USB*) the
> +Proxmox Backup Server menu will be displayed, and one of the following
> +options can be selected:
>
>  **Install Proxmox Backup Server (Graphical)**
>