doc/tutorial: add a UI tutorial (#13876)

This commit also includes some small updates to the existing tutorial/UI instructions to make sure they are up-to-date.
canonical · Aug 7, 2024 · bab88c5 · bab88c5
2 parents f020857 + 605c36f
commit bab88c5
Show file tree

Hide file tree

Showing 23 changed files with 469 additions and 15 deletions.
diff --git a/doc/.sphinx/.markdownlint/exceptions.txt b/doc/.sphinx/.markdownlint/exceptions.txt
@@ -1,3 +1,4 @@
+.tmp/doc/howto/access_ui.md:31: MD029 Ordered list item prefix
 .tmp/doc/howto/import_machines_to_instances.md:114: MD034 Bare URL used
 .tmp/doc/howto/import_machines_to_instances.md:218: MD034 Bare URL used
 .tmp/doc/howto/network_forwards.md:66: MD004 Unordered list style

diff --git a/doc/custom_conf.py b/doc/custom_conf.py
@@ -387,7 +387,6 @@
     custom_excludes.extend(['security.md','external_resources.md','reference/network_external.md','migration.md'])
     redirects['security/index'] = '../explanation/security/'
     redirects['migration/index'] = '../howto/import_machines_to_instances/'
-    redirects['tutorial/index'] = 'first_steps/'
     custom_tags.append('diataxis')
     toc_filter_exclude = ['topical']
 

diff --git a/doc/howto/access_ui.md b/doc/howto/access_ui.md
@@ -25,7 +25,9 @@ Complete the following steps to access the LXD web UI:
 1. Make sure that your LXD server is {ref}`exposed to the network <server-expose>`.
    You can expose the server during {ref}`initialization <initialize>`, or afterwards by setting the {config:option}`server-core:core.https_address` server configuration option.
 
-1. Access the UI in your browser by entering the server address (for example, `https://192.0.2.10:8443`).
+<!-- Include start access UI -->
+
+2. Access the UI in your browser by entering the server address (for example, `https://127.0.0.1:8443` for a local server, or `https://192.0.2.10:8443`).
 
    If you have not set up a secure {ref}`authentication-server-certificate`, LXD uses a self-signed certificate, which will cause a security warning in your browser.
    Use your browser's mechanism to continue despite the security warning.
@@ -36,14 +38,26 @@ Complete the following steps to access the LXD web UI:
    ```
 
 1. Set up the certificates that are required for the UI client to authenticate with the LXD server by following the steps presented in the UI.
-   These steps include creating a set of certificates, adding the private key to your browser, and adding the public key to the server's trust store.
+
+   You have two options, depending on whether you already have a client certificate selected in your browser:
+
+   - If you don't have a certificate yet, click {guilabel}`Create a new certificate` to get instructions for creating a set of certificates, adding the public key to the server's trust store, and adding the private key to your browser.
+
+     ```{figure} /images/ui_set_up_certificates.png
+     :width: 100%
+     :alt: Instructions for setting up certificates for the UI
+     ```
+
+   - If you already have a client certificate in your browser, select "use an existing certificate" to authorize the certificate with the server and re-use it.
+
+     ```{figure} /images/ui_set_up_existing_cert.png
+     :width: 100%
+     :alt: Instructions for re-using an existing certificate for the UI
+     ```
 
    See {ref}`authentication` for more information.
 
-   ```{figure} /images/ui_set_up_certificates.png
-   :width: 80%
-   :alt: Instructions for setting up certificates for the UI
-   ```
+<!-- Include end access UI -->
 
 After setting up the certificates, you can start creating instances, editing profiles, or configuring your server.
 

diff --git a/doc/images/tutorial/add_disk_device.png b/doc/images/tutorial/add_disk_device.png
diff --git a/doc/images/tutorial/broken_terminal.png b/doc/images/tutorial/broken_terminal.png
diff --git a/doc/images/tutorial/create_desktop_vm.png b/doc/images/tutorial/create_desktop_vm.png
diff --git a/doc/images/tutorial/create_instance.png b/doc/images/tutorial/create_instance.png
diff --git a/doc/images/tutorial/create_project.png b/doc/images/tutorial/create_project.png
diff --git a/doc/images/tutorial/create_vm.png b/doc/images/tutorial/create_vm.png
diff --git a/doc/images/tutorial/desktop_console.png b/doc/images/tutorial/desktop_console.png
diff --git a/doc/images/tutorial/hello_world_desktop.png b/doc/images/tutorial/hello_world_desktop.png
diff --git a/doc/images/tutorial/instance_summary.png b/doc/images/tutorial/instance_summary.png
diff --git a/doc/images/tutorial/instances.png b/doc/images/tutorial/instances.png
diff --git a/doc/images/tutorial/resource_limits.png b/doc/images/tutorial/resource_limits.png
diff --git a/doc/images/tutorial/root_disk_size.png b/doc/images/tutorial/root_disk_size.png
diff --git a/doc/images/tutorial/yaml_configuration.png b/doc/images/tutorial/yaml_configuration.png
diff --git a/doc/images/ui_set_up_certificates.png b/doc/images/ui_set_up_certificates.png
diff --git a/doc/images/ui_set_up_existing_cert.png b/doc/images/ui_set_up_existing_cert.png
diff --git a/doc/index.md b/doc/index.md
@@ -22,9 +22,11 @@ LXD (<a href="#" title="Listen" onclick="document.getElementById('player').play(
 
 ````{grid} 1 1 2 2
 
-```{grid-item-card} [Tutorial](tutorial/first_steps)
+```{grid-item-card} [Tutorials](tutorial/index)
 
-**Start here**: a hands-on introduction to LXD for new users, guiding you through your {ref}`first-steps`
+**Start here**: a hands-on introduction to LXD for new users, guiding you through your first steps using the CLI or the UI
+- {ref}`first-steps`
+- {ref}`tutorial-ui`
 ```
 
 ```{grid-item-card} [How-to guides](howto/index)
@@ -108,7 +110,7 @@ The LXD project is sponsored by [Canonical Ltd](https://canonical.com/).
 :titlesonly:
 
 :diataxis:self
-:diataxis:Tutorial <tutorial/first_steps>
+:diataxis:tutorial/index
 :diataxis:howto/index
 :diataxis:explanation/index
 :diataxis:reference/index

diff --git a/doc/substitutions.yaml b/doc/substitutions.yaml
@@ -6,6 +6,7 @@ enable_ID_shifting: "Enable ID shifting overlay (allows attach by multiple isola
 must_start_new_session: "If your user was not already a member of the `lxd` group, you need to log out and back in or use `newgrp lxd` for the change to take effect."
 note_ip_addresses_CIDR: "LXD uses the [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) where network subnet information is required, for example, `192.0.2.0/24` or `2001:db8::/32`. This does not apply to cases where a single address is required, for example, local/remote addresses of tunnels, NAT addresses or specific addresses to apply to an instance."
 restore_button: "<svg width='16' height='16' xmlns='http://www.w3.org/2000/svg'><path d='M5.948 9.012v1.5l-2.458.001A5.163 5.163 0 0012.76 10h1.596a6.665 6.665 0 01-11.839 1.785v2.158h-1.5v-4.93h4.93zM8 1.338a6.655 6.655 0 015.516 2.925V2.11h1.5v4.93h-4.93v-1.5h2.453A5.163 5.163 0 003.24 6H1.643A6.665 6.665 0 018 1.338z' fill='%23000'  fill-rule='evenodd'/></svg>"
+restart_button: "<svg width='16' height='16' xmlns='http://www.w3.org/2000/svg'><path d='M6.197 1.15v4.931h-1.5l-.001-2.478a5.5 5.5 0 106.302-.215l.75-1.3a7 7 0 11-8.263.562H1.268v-1.5h4.93z' fill='%23000'  fill-rule='evenodd'/></svg>"
 snapshot_expiry_format: "Controls when snapshots are to be deleted (expects an expression like `1M 2H 3d 4w 5m 6y`)"
 snapshot_pattern_detail: "The `snapshots.pattern` option takes a Pongo2 template string to format the snapshot name.\n\nTo add a time stamp to the snapshot name, use the Pongo2 context variable `creation_date`.\nMake sure to format the date in your template string to avoid forbidden characters in the snapshot name.\nFor example, set `snapshots.pattern` to `{{ creation_date|date:'2006-01-02_15-04-05' }}` to name the snapshots after their time of creation, down to the precision of a second.\n\nAnother way to avoid name collisions is to use the placeholder `%d` in the pattern.\nFor the first snapshot, the placeholder is replaced with `0`.\nFor subsequent snapshots, the existing snapshot names are taken into account to find the highest number at the placeholder's position.\nThis number is then incremented by one for the new name."
 snapshot_pattern_format: "Pongo2 template string that represents the snapshot name (used for scheduled snapshots and unnamed snapshots)"

diff --git a/doc/tutorial/first_steps.md b/doc/tutorial/first_steps.md
@@ -10,6 +10,8 @@ After going through these steps, you will have a general idea of how to use LXD,
 Ensure that you have 20 GiB free disk space before starting this tutorial.
 ```
 
+<!-- Include start tutorial installation -->
+
 ## Install and initialize LXD
 
 The easiest way to install LXD is to install the snap package.
@@ -22,11 +24,11 @@ If you prefer a different installation method, or use a Linux distribution that
       ```{terminal}
       :input: snap version
 
-      snap    2.59.4
-      snapd   2.59.4
+      snap    2.63+24.04ubuntu0.1
+      snapd   2.63+24.04ubuntu0.1
       series  16
-      ubuntu  22.04
-      kernel  5.15.0-73-generic
+      ubuntu  24.04
+      kernel  5.15.0-117-generic
       ```
 
       If you see a table of version numbers, snap is installed and you can continue with the next step of installing LXD.
@@ -65,6 +67,8 @@ If you prefer a different installation method, or use a Linux distribution that
    This will create a minimal setup with default options.
    If you want to tune the initialization options, see {ref}`initialize` for more information.
 
+<!-- Include end tutorial installation -->
+
 ## Launch and inspect instances
 
 LXD is image based and can load images from different image servers.
@@ -345,6 +349,10 @@ You can create a snapshot of your instance, which makes it easy to restore the i
 
 See {ref}`instances-snapshots` for more information.
 
+<!-- Include start tutorial next steps -->
+
 ## Next steps
 
-Now that you've done your first experiments with LXD, check out the information in the {ref}`getting-started` section!
+Now that you've done your first experiments with LXD, you should read up on important concepts in the {ref}`explanation` section and check out the {ref}`howtos` to start working with LXD!
+
+<!-- Include end tutorial next steps -->
diff --git a/doc/tutorial/index.md b/doc/tutorial/index.md
@@ -0,0 +1,11 @@
+(tutorials)=
+# Tutorials
+
+The following tutorial guides you through installing and initializing LXD, creating and configuring some instances, interacting with the instances, and creating snapshots:
+
+```{toctree}
+:titlesonly:
+
+first_steps
+ui
+```