# Deploying ## What you'll learn in this chapter * Creating an update content server * Creating images * Deploying an initial image to a target * Starting a Clear Linux OS based Virtual Machine (VM) * Switching the Clear Linux machine to use the custom mix update content ## Conveying the content to a target For the purpose of this training, we chose a setup that can be reproduced easily using a stock Clear Linux OS. The simplest setup is to use a simple VM that will be updating against our locally produced mix content. We will set up a HTTP service for the client using `nginx` because it comes with Clear Linux OS in a bundle. `nginx` needs some minor configuration but we won't cover more complex `nginx` setup issues here. This training does not cover topics like `certbot` which will be different for most setups. ## nginx ``` ~/mix $ sudo swupd bundle-add web-server-basic ``` This installs the `nginx` service onto your device. It doesn't start by default and we need to configure it. ``` ~/mix $ sudo mkdir -p /etc/nginx/conf.d ~/mix $ sudo cp /usr/share/nginx/conf/nginx.conf.example /etc/nginx/nginx.conf ``` The default `nginx` configuration works just fine as a base nginx config file. We'll create a specific update server config separately. To do that, we create a small config file for nginx that will make it point to our update content directly. ``` ~/mix $ sudoedit /etc/nginx/conf.d/mixer.conf ``` Insert the following content into the `mixer.conf` file: ``` server { server_name localhost; location / { root /home/clear/mix/update/www; autoindex on; } } ``` Make sure to insert the correct username in case your username isn't `clear`. Once this file is in place, we start the http server and you can view the content by visiting `http://localhost`: ``` ~/mix $ sudo systemctl restart nginx ``` ## Conveying the URL to mixer Once this is functional, we tell `mixer` to point to this content by its URL. To do this, we edit `builder.conf` and change the following options to properly point the system to the mix we are making. Because of an issue with QEMU\* and networking, we point the OS inside the virtual machine at the external IP address of the host where `nginx` is running. We can find out the IP address with the following command: ``` ~/mix $ networkctl status ``` There are likely 2 or 3 entries listed under `Address` in the output of this command. All entries should be valid, but we recommend you pick the top one listed for use in the `builder.conf`: ``` CONTENTURL=http://10.276.302.138/ VERSIONURL=http://10.276.302.138/ ``` Now that that is in place, we can proceed to the next step, which is to create an image for a VM. ## VM kernel We need to create an image for a QEMU virtual machine. We can use the standard bundle list that mixer uses by default, but this includes the `native` kernel. This is not very efficient, as the QEMU virtual machine only includes a very small set of hardware, and we don't need all the hundreds of drivers that the `native` kernel includes. For this reason, we want to modify our default bundle set already so we have a smaller amount of content to process. We'll get a faster boot time out of it, simply because the kernel image will be smaller and faster to load. To do this, we include the `kernel-kvm` bundle in our mix, and we use the upstream content for now: ``` ~/mix $ mixer bundle add kernel-kvm ``` We need to generate an update so that the new kernel images are available in our content stream and the image will be able to include it: ``` ~/mix $ mixer build all ``` You should verify that the `www` content contains a new version, and that a `Manifest.kernel-kvm` now exists in the latest version of the update content. ## Create the image We need to generate an `ister` config file that describes what kind of image we're creating and what needs to go into the image. For the purpose of this training, we will make a `live` image that we can boot straight into without the need for an installation step. First, we create the file `release-image-config.json` with the following content in the mix folder: ``` { "DestinationType" : "virtual", "PartitionLayout" : [ { "disk" : "release.img", "partition" : 1, "size" : "32M", "type" : "EFI" }, { "disk" : "release.img", "partition" : 2, "size" : "16M", "type" : "swap" }, { "disk" : "release.img", "partition" : 3, "size" : "10G", "type" : "linux" } ], "FilesystemTypes" : [ { "disk" : "release.img", "partition" : 1, "type" : "vfat" }, { "disk" : "release.img", "partition" : 2, "type" : "swap" }, { "disk" : "release.img", "partition" : 3, "type" : "ext4" } ], "PartitionMountPoints" : [ { "disk" : "release.img", "partition" : 1, "mount" : "/boot" }, { "disk" : "release.img", "partition" : 3, "mount" : "/" } ], "Version": "latest", "Bundles": ["kernel-kvm", "os-core", "os-core-update"] } ``` After this file is in place, `mixer` can properly start `ister` for us with the `build image` subcommand. ``` ~/mix $ sudo mixer build image --native ``` Note: If you have made any changes to `builder.conf` or the content of your mix, you need to run `sudo mixer build all` before creating a new image, otherwise your image may be built with old content and not include the needed URL changes for `swupd` to work properly inside the image. This outputs a file called `release.img` which is directly bootable in QEMU. We use the standard `start_qemu.sh` script to invoke QEMU to then invoke the image and redirect the VM output to our local console. For this we also need the `OVMF.fd` file. These can be found in the `files` folder inside the training repository. ``` ~/mix $ sudo ./start_qemu.sh release.img ``` You need to log in as root and immediately provide a new root password, because Clear Linux OS does not ship with a default root password, as you may already know. After logging in as root, `swupd update` will display that there are no current updates available, and it will list your latest mix content version as the last available update. If we create a new update on the outside of the VM quickly with: ``` ~/mix $ mixer build all ``` Then run `swupd update` inside the VM, we will see the update apply. ## Exercises * List your own mix bundles on your target system. * Verify your install. * Downgrade your target system with `swupd`, and then update it again. * Create an installer image using the installer configuration file at \[]. You will need the referenced Python\* script. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://clr.gitbook.io/clearlinux-docs/05-deploying.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.