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

* [pbs-devel] [PATCH v2 proxmox-backup] docs: installation: several small fixes/improvements
@ 2024-11-27 10:49 Alexander Zeidler
  2024-11-27 11:57 ` [pbs-devel] applied: " Thomas Lamprecht
  0 siblings, 1 reply; 2+ messages in thread
From: Alexander Zeidler @ 2024-11-27 10:49 UTC (permalink / raw)
  To: pbs-devel

* 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 little storage space) but keep DVD
* mention explicitly that data get overwritten on installation media /
  installation target disks
* mention that using `dd` will require root privileges
* 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@proxmox.com>
---
v2:
 * implement all suggestions from Shannon


 docs/installation-media.rst   | 57 +++++++++++++++++++++--------------
 docs/installation.rst         | 41 +++++++++++++++++--------
 docs/package-repositories.rst |  2 +-
 docs/using-the-installer.rst  | 25 +++++++--------
 4 files changed, 76 insertions(+), 49 deletions(-)

diff --git a/docs/installation-media.rst b/docs/installation-media.rst
index e109f2ba..dbcb2078 100644
--- a/docs/installation-media.rst
+++ b/docs/installation-media.rst
@@ -1,44 +1,54 @@
-.. _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 an installation medium, to simply boot the interactive
+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, 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. Depending on
+your environment, you will need to have root privileges to execute
+``dd``.
 
 .. code-block:: console
 
@@ -132,16 +142,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..dd09a1e9 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 have created an :ref:`installation_medium`, the booted
+:ref:`installer <using_the_installer>` will guide you through the
+setup process. It will help you to partition your disks, apply basic
+settings such as the language, time zone and network configuration,
+and 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)**
 
-- 
2.39.5



_______________________________________________
pbs-devel mailing list
pbs-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pbs-devel


^ permalink raw reply	[flat|nested] 2+ messages in thread