wip: host-apt-news tutorial

docs/tutorials.rst

@@ -39,3 +39,4 @@ start. They are not sequential, so you can approach them in any order you like!
 
     tutorials/fix_intro.rst
     tutorials/create_a_fips_docker_image.rst
+    tutorials/host-apt-news.rst

docs/tutorials/common/install-multipass.txt

@@ -1,14 +1,11 @@
 Install Multipass
 =================
 
-In this tutorial, we will use a Xenial Multipass virtual machine (VM) to avoid
-making any modifications to your machine. We have chosen `Multipass`_ for this
-tutorial because it allows us to easily launch VMs without requiring any
-complicated setup.
-
-To install Multipass on your computer, run the following command on your
-machine:
+To avoid making any modifications to your live system during the tutorial, we
+will set up a virtual machine using `Multipass`_. We are using Multipass
+because it allows us to launch VMs without needing any complicated setup. To
+install Multipass on your system, run the following command on your machine:
 
 .. code-block:: bash
 
-    $ sudo snap install multipass
+   $ sudo snap install multipass

docs/tutorials/host-apt-news.rst

@@ -0,0 +1,148 @@
+Host your own APT News
+**********************
+
+In this tutorial, you will learn how to host your own APT news and how to
+configure your Ubuntu machines to use it.
+
+APT news is used to display custom messages within the `apt upgrade` command,
+and can be a good way of delivering messages that are related to APT updates
+to users.
+
+.. Why we use Multipass + command to install it
+.. include:: ./common/install-multipass.txt
+
+Tutorial Architecture
+=====================
+
+To demonstrate how APT news works, we will create three containers inside a
+Multipass VM. We will configure one of them to be the APT news server, and we
+will configure the other two to consume APT news from that server. It will
+look something like this:
+
+.. image:: host-apt-news.drawio.png
+
+
+Create the local VM and containers
+==================================
+
+Begin by launching an Ubuntu 24.04 Multipass VM by running this command:
+
+.. code-block:: bash
+
+   multipass launch noble --disk 15G --memory 2G --name apt-news-tutorial
+
+Now access the VM by running the command:
+
+.. code-block:: bash
+
+   multipass shell apt-news-tutorial
+
+Inside the VM, set up `LXD`_ by running this command:
+
+.. code-block:: bash
+
+   lxd init --minimal
+
+
+Now launch three containers inside the VM with the following commands:
+
+.. code-block:: bash
+
+   lxc launch ubuntu-daily:noble apt-news-server
+   lxc launch ubuntu-daily:noble client-2404
+   lxc launch ubuntu-daily:jammy client-2204
+
+Set up the APT news server
+==========================
+
+Now, let's setup the ``apt-news-server`` container to serve APT news content.
+APT news content is formatted as a JSON file, hosted by an HTTP(S) server and
+compressed with gzip. We can easily accomplish this with by installing and
+configuring `nginx`_ to server a properly formatted JSON file.
+
+First, enter the ``apt-news-server`` container with the following command:
+
+.. code-block:: bash
+
+   lxc shell apt-news-server
+
+Install and configure ``nginx``
+-------------------------------
+
+Now, in ``apt-news-server``, install ``nginx`` via ``apt``.
+
+.. code-block:: bash
+
+   apt install nginx
+
+Now we need to configure nginx to always gzip json files. We need to edit ``/etc/nginx/nginx.conf`` to do this.
+
+.. code-block:: bash
+
+   nano /etc/nginx/nginx.conf
+
+In this file, scroll down until you see the following section:
+
+.. code-block:: nginx
+
+   ##
+   # Gzip Settings
+   ##
+
+   gzip on;
+
+Add the following lines immediately after ``gzip on;``:
+
+.. code-block:: nginx
+
+   gzip_min_length 1;
+   gzip_types application/json;
+
+Now restart ``nginx`` and it will be ready to start serving APT news!
+
+.. code-block:: bash
+
+   systemctl restart nginx
+
+Write an APT news JSON file
+---------------------------
+
+With ``nginx`` configured and running, now we can author an APT news JSON file. Open ``/var/www/html/aptnews.json``:
+
+.. code-block:: bash
+
+   nano /var/www/html/aptnews.json
+
+and add the following content:
+
+.. code-block:: json
+
+   {
+     "messages": [
+       {
+         "begin": "TODAY",
+         "lines": [
+           "Hello! This is the APT news server."
+         ]
+       }
+     ]
+   }
+
+The value of ``"begin"`` actually needs to be an ISO8601 formatted datetime
+string, and the message won't be shown before the ``begin`` date or more than 30
+days after the ``begin`` date. For the purposes of this tutorial you can
+quickly replace "TODAY" with today's date in ``aptnews.json`` with the
+following command.
+
+.. code-block:: bash
+
+   sed -i "s/TODAY/$(date --iso-8601=seconds)/" /var/www/html/aptnews.json
+
+
+
+.. LINKS
+.. include:: ../links.txt
+
+.. _Multipass: https://multipass.run/
+.. _LXD: https://documentation.ubuntu.com/lxd/
+.. _nginx: https://nginx.org/