From a213cb8860a253541fc32fb1f659e3e4aa7b76f4 Mon Sep 17 00:00:00 2001
From: Renan Rodrigo <renanrodrigo@canonical.com>
Date: Tue, 11 Jun 2024 01:43:33 -0300
Subject: [PATCH] docs: add explanation on how to use custom APT configuration

Signed-off-by: Renan Rodrigo <renanrodrigo@canonical.com>
---
 docs/howtoguides.rst                       |  8 ++
 docs/howtoguides/use_custom_apt_config.rst | 99 ++++++++++++++++++++++
 2 files changed, 107 insertions(+)
 create mode 100644 docs/howtoguides/use_custom_apt_config.rst

diff --git a/docs/howtoguides.rst b/docs/howtoguides.rst
index bb85630f4d..466813f64a 100644
--- a/docs/howtoguides.rst
+++ b/docs/howtoguides.rst
@@ -111,3 +111,11 @@ Fixing multiple CVEs
    :maxdepth: 1
 
    Better visualise results when fixing multiple CVEs <howtoguides/how_to_better_visualise_fixing_multiple_cves>
+
+APT integration
+===============
+
+.. toctree::
+   :maxdepth: 1
+
+    How to use custom APT configuration when running Pro commands <howtoguides/use_custom_apt_config>
diff --git a/docs/howtoguides/use_custom_apt_config.rst b/docs/howtoguides/use_custom_apt_config.rst
new file mode 100644
index 0000000000..12ba3c53d4
--- /dev/null
+++ b/docs/howtoguides/use_custom_apt_config.rst
@@ -0,0 +1,99 @@
+How to use the Pro Client with custom APT configuration
+*******************************************************
+
+The Pro Client CLI is able, through the security-status command, to show
+information about installed packages in the system, their origins, and
+potential updates that may be available for these. This information is also
+available through the
+:ref:`packages updates API<references/api:u.pro.packages.updates.v1>` and the
+:ref:`packages summary API<references/api:u.pro.packages.summary.v1>` calls,
+for example.
+
+The information presented on the outputs mentioned above is taken directly
+from the local APT caches. Packages, origins, versions, candidates, all is
+calculated using the ``python3-apt`` library, which in turn relies on whatever
+APT has knowledge about in a particular machine.
+
+Some users may have the need to configure APT to some specific behaviour. An
+example of a use case would be to pass custom ``.list`` or ``.sources`` files,
+to APT, whether to limit or to increase knowledge about different package
+sources.
+
+The Pro Client will respect the `configuration set directly on APT`_, at
+execution time. If system level configuration is present, it will be used by
+default. To configure APT without changing the system, there is the option of
+passing the config file as an environment variable.
+
+Use an APT config file
+=========================
+For example, consider that the ``/etc/apt/apt.conf.d/50-custom`` file exists,
+and has this content:
+
+.. code-block:: bash
+
+    $ cat /etc/apt/apt.conf.d/50-custom
+    # setting custom sources.list and unsetting the parts directory
+    Dir::Etc::Sourcelist "/my/personal/configured/sources.list";
+    Dir::Etc::Sourceparts "nonexisting-dir";
+
+APT will be using this configuration by default when running all operations.
+The Pro Client will do the same - all outputs will take the custom ``.list``
+file into consideration, and no parts directory will be loaded (unless the
+directory set there actually exists ;)
+
+Use an environment variable
+===========================
+Now, if the user does not want to change their system, the ``APT_CONFIG``
+environment variable can be set when running APT commands, pointing to the
+desired configuration file.
+
+For example, let's say that instead of ``apt.conf.d``, the config file is
+created in ``/tmp``:
+
+.. code-block:: bash
+
+    $ cat /tmp/custom-config
+    # setting custom sources.list and unsetting the parts directory
+    Dir::Etc::Sourcelist "/my/personal/configured/sources.list";
+    Dir::Etc::Sourceparts "nonexisting-dir";
+
+APT will respect this configuration if found in the aforementioned environment
+variable:
+
+.. code-block:: bash
+
+    $ APT_CONFIG=/tmp/custom-config apt list --installed
+    $ APT_CONFIG=/tmp/custom-config sudo apt update
+
+If the variable is set when executing the Pro Client commands that depend on
+APT, it will also be respected:
+
+.. code-block:: bash
+
+    $ APT_CONFIG=/tmp/custom-config pro security-status
+    $ APT_CONFIG=/tmp/custom-config pro api u.pro.packages.updates.v1
+
+In the python API integration
+=============================
+Changing the environment also works for the integration with the Pro Client's
+APIs. Even after import time, it is just a matter of setting the value in
+``os.environ`` before calling the function.
+
+.. code-block:: python3
+
+    import os
+    from uaclient.api.u.pro.packages.updates.v1 import updates
+
+    # call updates using the system APT configuration
+    updates()
+
+    # set the custom configuration, so updates will respect it
+    os.environ["APT_CONFIG"] = "/tmp/custom-config"
+    updates()
+
+    # unsetting the envvar will cause updates to respect system config again
+    os.environ["APT_CONFIG"] = ""
+    updates()
+
+
+.. _configuration set directly on APT: https://manpages.debian.org/unstable/apt/apt.conf.5.en.html