StealthOS/subiquity
StealthOS
/
subiquity
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #1858 from rkratky/FR-5770_review-tutorials 

Review and fixes of doc tutorials
This commit is contained in:
Dan Bungert 2023-10-26 10:07:42 -06:00 committed by GitHub
parent 0700be2e6f 07f404b404
commit a52839f8ae
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 93 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
doc/tutorial/basic-server-installation.rst
View File

@ -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 <operate-server-installer>` for more
information on using the installer, and to this
:doc:`screen-by-screen reference guide <screen-by-screen>` 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 <operate-server-installer>` for more information on using the installer, and the :doc:`screen-by-screen guide <screen-by-screen>` 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 <https://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 <https://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 <https://discourse.ubuntu.com/t/using-a-virtual-cdrom-and-petitboot-to-start-a-live-server-installation-on-ibm-power-ppc64el/16694>`_
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 <https://ubuntu.com/tutorials/create-a-usb-stick-on-ubuntu>`_
to boot the system to be installed with
(`tutorials for other operating systems <https://ubuntu.com/search?q=%22create+a+bootable+USB+stick%22>`_
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 <https://ubuntu.com/tutorials/create-a-usb-stick-on-ubuntu>`_ (`tutorials for other operating systems <https://ubuntu.com/search?q=%22create+a+bootable+USB+stick%22>`_ 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 <https://help.ubuntu.com/community/BootFromCD>`_.
If you are still having problems, see the
`Ubuntu Community documentation on booting from CD/DVD <https://help.ubuntu.com/community/BootFromCD>`_.
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.

13
doc/tutorial/index.rst
View File

@ -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

136
doc/tutorial/screen-by-screen.rst
View File

@ -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 <https://discourse.ubuntu.com/t/how-to-operate-the-server-installer/16689#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 <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 <configure-storage>`.
Storage configuration is a complex topic and :ref:`has its own page for documentation <configure-storage>`.
.. 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