Merge pull request #368 from John15321/master

Refactor Tutorial section for improved clarity and structure

Author: tormath1

content/docs/latest/contribute/_index.md

@@ -10,7 +10,7 @@ Submit fixes and additions in the form of [GitHub *Pull Requests* (PRs)][pull-re
 
 1. Fork this repository into your GitHub account
 2. Make changes in a topic branch or your fork's `master`
-3. Send a Pull Request from that topic branch to flatcar-linux/docs
+3. Send a Pull Request from that topic branch to flatcar/flatcar-website
 4. Maintainers will review the PR and either merge it or make comments
 
 Cognizance of the tribal customs described and linked to below will help get your contributions incorporated with the greatest of ease.

content/docs/latest/tutorial/_index.md

@@ -6,15 +6,15 @@ weight: 2
 
 # Introduction
 
-This tutorial is a deep dive into some Flatcar fundamental concepts, it is designed to give you the key elements and resources to become autonomous with Flatcar. If you want to have a quickstart, please have a look to the [quickstart guide][quickstart].
+This tutorial is a deep dive into some Flatcar fundamental concepts, it is designed to give you the key elements and resources to become autonomous with Flatcar. If you want to have a quickstart, please have a look to the [Quickstart Guide][quickstart].
 
 # Requirements
 
 * Linux VM with nested virtualization (or Linux host with KVM)
-* `qemu`
-* `terraform` (https://developer.hashicorp.com/terraform/downloads)
-* `butane` (can be used from the Docker image or directly from the binary: https://coreos.github.io/butane/getting-started/#getting-butane)
-* (OpenStack credentials for the "Hands-on 3")
+* `qemu` ([Installing QEMU Guide](https://www.qemu.org/download/))
+* `terraform` ([Installing Terraform Guide](https://developer.hashicorp.com/terraform/downloads))
+* `butane` (can be used from the Docker image or [directly from the binary](https://coreos.github.io/butane/getting-started/#getting-butane))
+* OpenStack credentials for the [Hands-on 3](https://www.flatcar.org/docs/latest/tutorial/hands-on-3/)
 
 For each covered item, there is a demo and a few lines to explain what's going on under the hood - each item is independent, but it's recommended to follow them in the given order, especially if it is your first time operating Flatcar.
 

content/docs/latest/tutorial/hands-on-1/_index.md

@@ -5,30 +5,57 @@ weight: 2
 ---
 
 The goal of this hands-on is to:
-* locally run a Flatcar instance
-* boot the instance and SSH into
-* run Nginx container on the instance
+
+* Locally run a Flatcar instance
+* Boot the instance and SSH into
+* Run Nginx container on the instance
 
 # Step-by-step
 
+Create a working directory:
+
 ```bash
-# create a working directory
 mkdir flatcar; cd flatcar
-# get the qemu helper
+```
+
+Get the qemu helper:
+
+```bash
 wget https://stable.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu.sh
-# get the latest stable release for qemu
+```
+
+Get the latest stable release for qemu:
+
+```bash
 wget https://stable.release.flatcar-linux.net/amd64-usr/current/flatcar_production_qemu_image.img
-# create a backup to always have a fresh image around
+```
+
+Create a backup to always have a fresh image around:
+
+```bash
 mv flatcar_production_qemu_image.img flatcar_production_qemu_image.img.fresh
-# make the qemu helper executable
+```
+
+Make the qemu helper executable:
+
+```bash
 chmod +x flatcar_production_qemu.sh
-# before starting, make sure you boot a fresh image
+```
+
+Before starting, make sure you boot a fresh image:
+
+```bash
 cp -i --reflink=auto flatcar_production_qemu_image.img.fresh flatcar_production_qemu_image.img
-# starts the flatcar image in console mode
+```
+
+Starts the flatcar image in console mode:
+
+```bash
 ./flatcar_production_qemu.sh -- -display curses
 ```
 
-NOTE: it's possible to connect to the instance via SSH:
+**_NOTE_**: it's possible to connect to the instance via SSH:
+
 ```bash
 $ cat ~/.ssh/config
 Host flatcar
@@ -41,18 +68,23 @@ $ ssh flatcar
 ```
 
 Once on the instance, you can try things and run a docker image:
-```
-# run an nginx docker image
+
+```bash
 docker run --rm -p 80:80 -d nginx
-# assert it works
+```
+
+Assert it works:
+
+```bash
 curl localhost
 ```
 
 # Resources
 
-* [documentation](../../installing/vms/qemu/#startup-flatcar-container-linux)
+* [Hands on 2](../../tutorial/hands-on-2/)
+* [Startup Flatcar Container Linux ](../../installing/vms/qemu/#startup-flatcar-container-linux)
 
 # Demo
 
-* Video with timestamp: https://youtu.be/woZlGiLsKp0?t=472
-* Asciinema: https://asciinema.org/a/591438
+* Video with timestamp: <https://youtu.be/woZlGiLsKp0?t=472>
+* Asciinema: <https://asciinema.org/a/591438>

content/docs/latest/tutorial/hands-on-2/_index.md

@@ -5,47 +5,77 @@ weight: 2
 ---
 
 The goal of this hands-on is to:
-* provision a local Flatcar instance
-* write Butane configuration
-* generate the Ignition configuration
-* boot the instance with the config
 
-This is what we've done in the previous hands-on but now it's done _as code_, we want to deploy an Nginx container serving a "hello world" static webpage. As a reminder, Ignition configuration is used to provision a Flatcar instance, it's JSON file generated from a Butane configuration (YAML).
+* Provision a local Flatcar instance
+* Write Butane configuration
+* Generate the Ignition configuration
+* Boot the instance with the config
+
+This is what we've done in the previous hands-on but now it's done _as code_, we want to deploy an Nginx container serving a "hello world" static webpage. As a reminder, Ignition configuration is used to provision a Flatcar instance, it's a JSON file generated from a Butane YAML configuration.
 
 # Step-by-step
 
-* Clone the tutorial repository and cd into it: `git clone https://github.com/flatcar/flatcar-tutorial ; cd flatcar-tutorial/hands-on-2`
-* Open `./config.yaml` and find the TODO section.
-* Add the following section (from https://coreos.github.io/butane/examples/#files):
+Clone the tutorial repository and cd into it:
+
+```bash
+git clone https://github.com/flatcar/flatcar-tutorial ; cd flatcar-tutorial/hands-on-2
 ```
+
+Open `./config.yaml`, find the TODO section, and add the following section:
+
+```bash
 storage:
   files:
     - path: /var/www/index.html
       contents:
         inline: Hello world
 ```
-* Transpile the Butane configuration (`config.yaml`) to Ignition configuration (`config.json`) - it is possible to use the Butane [binary](https://coreos.github.io/butane/getting-started/#standalone-binary) or the Docker image
-```
-$ docker run --rm -i quay.io/coreos/butane:latest < config.yaml > config.json
-```
-* Use a fresh Flatcar image from the previous hands-on (or download again). NOTE: Ignition runs at first boot, it won't work if you reuse your the previously booted image, always decompress again each time you change your Ignition config.
+
+**_NOTE_**: More [Butane Config Examples](https://www.flatcar.org/docs/latest/provisioning/config-transpiler/examples/) and [Common Setup, Operations and Customization](https://www.flatcar.org/docs/latest/setup).
+
+Transpile the Butane configuration (`config.yaml`) to Ignition configuration (`config.json`) - it is possible to use the Butane [binary](https://coreos.github.io/butane/getting-started/#standalone-binary) or the Docker image
+
+```bash
+docker run --rm -i quay.io/coreos/butane:latest < config.yaml > config.json
 ```
+
+Use a fresh Flatcar image from the previous hands-on (or download again). NOTE: Ignition runs at first boot, it won't work if you reuse the previously booted image, always start from a pristine image. 
+
+```bash
 cp -i --reflink=auto ../hands-on-1/flatcar_production_qemu_image.img.fresh flatcar_production_qemu_image.img
 chmod +x flatcar_production_qemu.sh
 ```
-* Start the image with Ignition configuration (`-i ./config.json`)
-```
+
+Start the image with Ignition configuration (`-i ./config.json`)
+
+```bash
 ./flatcar_production_qemu.sh -i ./config.json -- -display curses
 ```
-* Once on the instance, assert nginx works correctly (`curl localhost` or `systemctl status nginx.service`)
+
+Once on the instance, assert nginx works correctly:
+
+
+```bash
+curl localhost
+```
+
+or
+
+```bash
+systemctl status nginx.service
+```
 
 # Resources
 
-* https://coreos.github.io/butane/examples/
-* https://coreos.github.io/ignition/rationale/
-* https://www.flatcar.org/docs/latest/installing/#concepts-configuration-and-provisioning
+* [Hands on 3](../../tutorial/hands-on-3/)
+* [More Butane Config Examples](https://www.flatcar.org/docs/latest/provisioning/config-transpiler/examples/)
+* [Common Setup, Operations and Customization](https://www.flatcar.org/docs/latest/setup)
+* [More On Butane Config Transpiler](https://www.flatcar.org/docs/latest/provisioning/config-transpiler/)
+* [Concepts, Configuration, and Provisioning](https://www.flatcar.org/docs/latest/installing/#concepts-configuration-and-provisioning)
+* <https://coreos.github.io/butane/examples/>
+* <https://coreos.github.io/ignition/rationale/>
 
 # Demo
 
-* Video with timestamp: https://youtu.be/woZlGiLsKp0?t=676
-* Asciinema: https://asciinema.org/a/591440
+* Video with timestamp: <https://youtu.be/woZlGiLsKp0?t=676>
+* Asciinema: <https://asciinema.org/a/591440>

content/docs/latest/tutorial/hands-on-3/_index.md

@@ -5,53 +5,75 @@ weight: 2
 ---
 
 The goal of this hands-on is to:
-* deploy Flatcar instances with IaC (Terraform)
-* manipulate Terraform code
-* write Flatcar provisioning with Terraform
-* deploy Flatcar on OpenStack with Terraform
+
+* Deploy Flatcar instances with IaC (Terraform)
+* Manipulate Terraform code
+* Write Flatcar provisioning with Terraform
+* Deploy Flatcar on OpenStack with Terraform
 
 This is a bundle of hands-on-1 and hands-on-2 but it's not a local deployment and _everything_ is as code.
 
 # Step-by-step
 
+
+Clone the tutorial repository and cd into it:
+
 ```bash
 git clone https://github.com/flatcar/flatcar-tutorial; cd flatcar-tutorial/hands-on-3
-# go into the terraform directory
+```
+
+Go into the terraform directory
+
+```bash
 cd terraform
-# update the config for creating index.html from previous hands-on
+```
+
+Update the config for creating index.html from previous hands-on:
+
+```bash
 vim server-configs/server1.yaml
-# init the terraform project locally
+```
+
+Initialize the terraform project locally:
+
+```bash
 terraform init
-# get the credentials and update the `terraform.tfvars` consequently
-# generate the plan and inspect it
+```
+
+Get the credentials and update the `terraform.tfvars` consequently generate the plan and inspect it:
+
+```bash
 terraform plan
-# apply the plan
+```
+
+Apply the plan:
+
+```bash
 terraform apply
-# go on the horizon dashboard and connect with terraform credentials
-# find your instance
 ```
 
-One can assert that it works by accessing the console (click on the instance then "console")
+Go on the horizon dashboard and connect with terraform credentials find your instance.
+One can assert that it works by accessing the console (click on the instance then "console").
 
 _NOTE_: it's possible to SSH into the instance but at the moment, it takes a SSH jump through the openstack (devstack) instance.
-```
+
+```bash
 ssh -J user@[DEVSTACK-IP] -i ./.ssh/provisioning_private_key.pem -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null core@[SERVER-IP]
 ```
 
-To destroy the instance:
-```
-# if you are happy, destroy everything
+In order to destroy the instance:
+
+```bash
 terraform destroy
 ```
 
 # Resources
 
-* https://github.com/flatcar/flatcar-terraform/ (NOTE: the terraform code used here is based on this repository)
-* https://www.flatcar.org/docs/latest/installing/cloud/openstack/
+* [Hands on 4](../../tutorial/hands-on-4/)
+* [Running Flatcar Container Linux on OpenStack](https://www.flatcar.org/docs/latest/installing/cloud/openstack/)
+* <https://github.com/flatcar/flatcar-terraform/> (__NOTE__: the terraform code used here is based on this repository)
 
 # Demo
 
-* Video with timestamp: https://youtu.be/woZlGiLsKp0?t=1395
-* Asciinema: https://asciinema.org/a/591442
-
-
+* Video with timestamp: <https://youtu.be/woZlGiLsKp0?t=1395>
+* Asciinema: <https://asciinema.org/a/591442>