From 07f404b404eefedf1b57e691b4db3d2575bae63e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Kr=C3=A1tk=C3=BD?= Date: Thu, 26 Oct 2023 17:53:31 +0200 Subject: [PATCH] Review and fixes of doc tutorials. --- doc/tutorial/basic-server-installation.rst | 111 ++++++----------- doc/tutorial/index.rst | 13 +- doc/tutorial/screen-by-screen.rst | 136 ++++++++------------- 3 files changed, 93 insertions(+), 167 deletions(-) diff --git a/doc/tutorial/basic-server-installation.rst b/doc/tutorial/basic-server-installation.rst index 0065308e..e60b5b49 100644 --- a/doc/tutorial/basic-server-installation.rst +++ b/doc/tutorial/basic-server-installation.rst @@ -1,58 +1,40 @@ Basic server installation -************************* +========================= -This chapter provides an overview of how to install Ubuntu Server Edition. You -can also refer to this guide on -:ref:`how to operate the installer ` for more -information on using the installer, and to this -:doc:`screen-by-screen reference guide ` for more -information about each of the installer screens. +This chapter provides an overview of how to install Ubuntu Server Edition. See also the guide on :ref:`how to operate the installer ` for more information on using the installer, and the :doc:`screen-by-screen guide ` for more information about each of the installer screens. Preparing to install -==================== +-------------------- -This section explains various aspects to consider before starting the -installation. +This section explains various aspects to consider before starting the installation. System requirements -------------------- +~~~~~~~~~~~~~~~~~~~ -Ubuntu Server Edition provides a common, minimalist base for a variety of -server applications, such as file or print services, web hosting, email hosting, -etc. This version supports four 64-bit architectures: +Ubuntu Server Edition provides a common, minimalist base for a variety of server applications, such as file or print services, web hosting, email hosting, etc. This version supports four 64-bit architectures: * amd64 (Intel/AMD 64-bit) * arm64 (64-bit ARM) * ppc64el (POWER8 and POWER9) * s390x (IBM Z and LinuxONE) -The recommended system requirements are: +Recommended system requirements: -* CPU: 1 gigahertz or better -* RAM: 1 gigabyte or more -* Disk: a minimum of 2.5 gigabytes +* CPU: 1 GHz or better +* RAM: 1 GB or more +* Disk: 2.5 GB or more Perform a system backup ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ -Before installing Ubuntu Server Edition you should make sure all data on the -system is backed up. +Before installing Ubuntu Server Edition, back up all system data. -If this is not the first time an operating system has been installed on your -computer, it is likely you will need to re-partition your disk to make room -for Ubuntu. +.. warning:: Power failures, configuration mistakes, and other problems occurring during disk (re-)partitioning can result in complete data loss. Always back up your data before performing an installation of a new system. -Any time you partition your disk, you should be prepared to lose everything on -the disk should you make a mistake or something goes wrong during partitioning. -The programs used in installation are quite reliable, most have seen years of -use, but they also perform destructive actions. +Download the Server ISO +~~~~~~~~~~~~~~~~~~~~~~~ -Download the server ISO ------------------------ - -You can obtain the amd64 server download from `releases.ubuntu.com `_. -Select the version you wish to install and select the "Server install image" -download. Note that the server download includes the installer. +Download the amd64 Server Edition from `releases.ubuntu.com `_. Choose the version to install and select the :guilabel:`Server install image` download. Note that the Server download includes the installer. There are platform-specific how-to guides for installations on: @@ -61,61 +43,42 @@ There are platform-specific how-to guides for installations on: * `ppc64el `_ Create a bootable USB ---------------------- +~~~~~~~~~~~~~~~~~~~~~ -There are many ways to boot the installer but the simplest and most common way -is to -`create a bootable USB stick `_ -to boot the system to be installed with -(`tutorials for other operating systems `_ -are also available). +There are many ways to boot the installer but the simplest and most common way is to `create a bootable USB stick `_ (`tutorials for other operating systems `_ are also available). Perform the installation -======================== +------------------------ Now that you have prepared your installation medium, you are ready to install. Boot the installer ------------------- +~~~~~~~~~~~~~~~~~~ -Plug the USB stick into the system to be installed and start it. +Plug the USB stick into the system to be installed and (re)start it. -Most computers will automatically boot from USB or DVD, though in some cases -this is disabled to improve boot times. If you don't see the boot message and -the "Welcome" screen which should appear after it, you will need to set your -computer to boot from the installation media. +Many computers automatically boot from available USB or DVD media. If you don't see the boot message and +the :guilabel:`Welcome` screen, set your computer to boot from the installation media. -There should be an on-screen message when the computer starts, telling you what -key to press for settings or a boot menu. Depending on the manufacturer, this -could be :kbd:`Escape`, :kbd:`F2`, :kbd:`F10` or :kbd:`F12`. Restart your -computer and hold down this key until the boot menu appears, then select the -drive with the Ubuntu installation media. +.. note:: See your computer manual for instructions on how to select the boot source. You can also watch the screen during computer (re)start for a message with what key to press to access settings or a boot menu. Depending on the manufacturer, this can be :kbd:`Escape`, :kbd:`Enter`, :kbd:`F2`, :kbd:`F10` or :kbd:`F12`. Restart your computer and hold down this key until the boot menu appears, then select the drive with the Ubuntu installation medium. See also `Ubuntu Community documentation on booting from CD/DVD `_. -If you are still having problems, see the -`Ubuntu Community documentation on booting from CD/DVD `_. - -After a few moments, the installer will start in its language selection screen. +After a few moments, the installer starts in its language selection screen. .. image:: figures/basic-installation-start-screen.png :alt: Welcome screen of the Server installer showing the language selection options Using the installer -------------------- +~~~~~~~~~~~~~~~~~~~ -The installer is designed to be easy to use and have sensible defaults, so for -a first installation you can accept the defaults: +The installer is designed to be easy to use and have sensible default settings. For a first installation, you can accept the defaults: -* Choose your language. -* Update the installer (if offered). -* Select your keyboard layout. -* Do not configure networking (the installer attempts to configure wired - network interfaces via DHCP, but you can continue without networking if this - fails). -* Do not configure a proxy or custom mirror unless you have to in your network. -* For storage, leave "use an entire disk" checked, and choose a disk to install - to, then select "Done" on the configuration screen and confirm the installation. -* Enter a username, hostname and password. -* On the SSH and snap screens, select "Done". -* You now see log messages as the installation is completed. -* Select restart when this is complete, and log in using the username and - password provided. +#. Choose your language. +#. Update the installer (if offered). +#. Select your keyboard layout. +#. Do not configure networking (the installer attempts to configure wired network interfaces via DHCP, but you can continue without networking if this fails). +#. Do not configure a proxy or custom mirror unless you have to in your network. +#. For storage, leave :guilabel:`Use an entire disk` checked, and choose a disk to install to, then select :guilabel:`Done` on the configuration screen and confirm the installation. +#. Enter a username, hostname and password. +#. On the :guilabel:`SSH Setup` and :guilabel:`Featured Server Snaps` screens, select :guilabel:`Done`. +#. You now see log messages as the installation is completed. +#. Select :guilabel:`Reboot` when this is complete, and log in using the username and password provided. diff --git a/doc/tutorial/index.rst b/doc/tutorial/index.rst index 08cd5074..473e5efb 100644 --- a/doc/tutorial/index.rst +++ b/doc/tutorial/index.rst @@ -1,21 +1,16 @@ .. _tutorial_index: Tutorials -********* +========= -This section contains step-by-step tutorials to help you get started with -Subiquity. We hope our tutorials make as few assumptions as possible and -are accessible to anyone with an interest in Subiquity. They should be a -great place to start learning about Subiquity, how it works, and what it's -capable of. +This section contains step-by-step tutorials to help you get started with Subiquity. The tutorials make as few assumptions as possible in order to be accessible to anyone with an interest in Subiquity. This is the place to start learning about Subiquity: how it works, and what it's capable of. ----- For Ubuntu Server -================= +----------------- -This tutorial introduces the core concepts of autoinstall and is recommended as -the first step. +This tutorial introduces the core concepts of autoinstall and is recommended as the first step. .. toctree:: :maxdepth: 1 diff --git a/doc/tutorial/screen-by-screen.rst b/doc/tutorial/screen-by-screen.rst index 07b70ee6..5e3743a1 100644 --- a/doc/tutorial/screen-by-screen.rst +++ b/doc/tutorial/screen-by-screen.rst @@ -1,46 +1,36 @@ Screen-by-screen installer -************************** +========================== -The installer is designed to be easy to use without documentation. However, -this guide provides more information on each of the screens of the installer to -help walk you through an installation. +The installer is designed to be easy to use without documentation. This guide provides more information on each of the screens of the installer to guide you through an installation. Language selection -================== +------------------ .. image:: figures/sbs-language.png - :alt: + :alt: Welcome! -This screen selects the language for the installer and the default language -for the installed system. - -More languages can be displayed if you -`connect via SSH `_. +This screen lets you select the language for the installer and the default language for the installed system. In case only a basic terminal with limited language support is available for the installation, an alternative is to :ref:`connect via SSH `. Refresh -======= +------- .. image:: figures/sbs-refresh.png - :alt: + :alt: Installer update available -This screen is shown if there is an update available for the installer. This -allows you to get any improvements and bug fixes made since release. +This screen is shown if there is an update available for the installer. Update the installer to get any improvements and bug fixes made since the release. -If you choose to update, the new version will be downloaded and the installer -will restart at the same point of the installation. +If you choose to update, the new version is downloaded, and the installer will restart at the same point of the installation. Keyboard -======== +-------- .. image:: figures/sbs-keyboard.png - :alt: + :alt: Keyboard configuration -Choose the layout and variant of keyboard attached to the system, if any. When -running in a virtual terminal, it is possible to guess the layout and variant -by answering questions about the keyboard. +Choose the layout and variant of keyboard attached to the system, if any. When running in a virtual terminal, it is possible to guess the layout and variant by answering questions about the keyboard. Select :guilabel:`Identify keyboard` to use this feature. Zdev (s390x only) -================= +----------------- .. code-block:: @@ -48,7 +38,7 @@ Zdev (s390x only) Zdev setup ==================================================================== ID ONLINE NAMES ^ - │ + │ generic-ccw │ 0.0.0009 > │ 0.0.000c > │ @@ -59,116 +49,94 @@ Zdev (s390x only) 0.0.0190 > │ 0.0.0191 > │ 0.0.019d > │ - 0.0.019e >┌────────────┐ - 0.0.0200 >│< (close) │ - 0.0.0300 >│ Enable │ - 0.0.0400 >│ Disable │ + 0.0.019e >┌────────────┐ + 0.0.0200 >│< (close) │ + 0.0.0300 >│ Enable │ + 0.0.0400 >│ Disable │ 0.0.0592 >└────────────┘ v - - [ Continue ] - [ Back ] - -This screen is only shown on s390x and allows z-specific configuration of -devices. + [ Continue ] + [ Back ] -The list of devices can be long. :kbd:`Home` / :kbd:`End` / :kbd:`PgUp` -/ :kbd:`PgDn` can be used to navigate through the list more quickly. +This screen is only shown on the s390x architecture and allows z-specific configuration of devices. + +The list of devices can be long. Use the :kbd:`Home`, :kbd:`End`, :kbd:`PgUp` and :kbd:`PgDn` keys navigate through the list quickly. Network -======= +------- .. image:: figures/sbs-network.png - :alt: + :alt: Network connections -This screen allows the configuration of the network. Ubuntu Server uses Netplan -to configure networking and the UI of the installer can configure a subset of -Netplan capabilities. In particular, it can configure DHCP or static +This screen allows the configuration of the network. Ubuntu Server uses Netplan to configure networking and the installer can configure a subset of Netplan capabilities. In particular, it can configure DHCP or static addressing, VLAN and bonds. -If networking is present (defined as "at least one interface has a default -route") then the installer will install updates from the archive at the end of -installation. +If networking is present (defined as "at least one interface has a default route"), then the installer installs updates from the repository at the end of installation. Proxy -===== +----- .. image:: figures/sbs-proxy.png - :alt: + :alt: Configure proxy -The proxy configured on this screen is used for accessing the package -repository and the snap store both in the installer environment and in the -installed system. +Use this screen to configure proxy for accessing the package repository and the snap store both in the installer environment and in the installed system. Mirror -====== +------ .. image:: figures/sbs-mirror.png - :alt: + :alt: Configure Ubuntu archive mirror -The installer will attempt to use ``geoip`` to look up an appropriate default -package mirror for your location. If you want or need to use a different -mirror, enter its URL here. +The installer attempts to use geolocation to find an appropriate default package mirror for your location. To use a different mirror, enter its URL here. Storage -======= +------- .. image:: figures/sbs-storage.png - :alt: + :alt: Storage configuration -Storage configuration is a complicated topic and :ref:`has its own page for documentation `. +Storage configuration is a complex topic and :ref:`has its own page for documentation `. .. image:: figures/sbs-confirm-storage.png - :alt: + :alt: Storage configuration -Once the storage configuration is confirmed, the installation begins in the -background. +Once the storage configuration is confirmed, the installation begins in the background. Identity -======== +-------- .. image:: figures/sbs-identity.png - :alt: + :alt: Profile setup -The default user will be an administrator, able to use ``sudo`` (this is why a -password is needed, even if SSH public key access is enabled on the next -screen). +The default user will be an administrator who can use ``sudo`` (this is why a password is needed, even if SSH public-key access is enabled on the next screen). SSH -=== +--- .. image:: figures/sbs-ssh.png - :alt: + :alt: SSH Setup -A default Ubuntu installation has no open ports. It is very common to administer -servers via SSH so the installer allows it to be installed with the click of a -button. +A default Ubuntu installation has no open ports. As it is very common to administer servers via SSH, the installer allows it to be installed. You can import keys for the default user from GitHub or Launchpad. -If you import a key, then password authentication is disabled by default but it -can be re-enabled again at a later time if you wish. +If you import a key, then password authentication is disabled by default. It can be re-enabled later. Snaps -===== +----- .. image:: figures/sbs-snaps.png - :alt: + :alt: Featured Server Snaps -If a network connection is enabled, a selection of snaps that are useful in a -server environment are presented and can be selected for installation. +If a network connection is enabled, a selection of snaps that are useful in a server environment is presented and can be selected for installation. Installation logs -================= +----------------- .. image:: figures/sbs-logs.png - :alt: + :alt: Installing system -The final screen of the installer shows the progress of the installer and -allows viewing of the full log file. Once the installation has completed and -security updates installed, the installer waits for confirmation before -restarting. +The final screen of the installer shows the progress of the installer and allows viewing of the full log file. Once the installation has completed and security updates have been installed, the installer waits for a confirmation before restarting. .. image:: figures/sbs-complete.png - :alt: - + :alt: Installation complete