==================================================================
Delivering QKDLite in a air-gapped environment (Podman)
==================================================================

This guide describes how to install ``QKDLite`` with Podman on a device that
has no route to the QKDLite registry. The images are collected on a device that
does have access, transferred, and loaded on the air-gapped device before the
installation runs.


Prerequisites
=============

Ensure the following are available before installing:

* An internet-connected device running Podman, used to collect the images
* Credentials to QKDLite registry (``qkdlite.azurecr.io``)
* QKDLite Podman installer package on both devices
* A means of transferring files to the air-gapped device


Steps
=====

Collecting the images
---------------------

On the internet-connected device, run the installer and answer ``N`` when asked
whether this is an offline install, then ``y`` when asked for an offline copy.

.. code-block:: console
   :caption: console on internet-connected device

   $ cd podman-qkdlite
   $ ./install_qkdlite_podman.sh

.. code-block:: console
   :caption: console on internet-connected device

   ==> Step 1: Container images
   Is this an offline (airgapped) install, with the images already loaded? [y/N]: N
   Container registry to pull images from [qkdlite.azurecr.io]:
   Registry token name: user
   Registry token/password:
   Login Succeeded
   Do you need an offline copy of the images to transfer into an airgapped environment? [y/N]: y
     Images will also be saved to /home/<user>/qkdlite-images

Each image is saved to ``~/qkdlite-images`` as it is pulled.

.. note::

   This device pulls, saves and installs in the same run. If it is only being
   used to collect the images, the installation it performs can be removed
   afterwards with ``./remove_qkdlite_podman.sh``.

Transferring the images
-----------------------

Transfer the contents of ``~/qkdlite-images`` to the air-gapped device, by
whichever means that environment allows.

Loading the images
------------------

On the air-gapped device, load each image into Podman.

.. code-block:: console
   :caption: console on air-gapped device

   $ podman load -i qkdlite-images/qkdlite-hsm.tar
   $ podman load -i qkdlite-images/qkdlite-runtime.tar
   $ podman load -i qkdlite-images/qkdlite-node.tar
   $ podman load -i qkdlite-images/pqtls-nginx-image.tar

Installing
----------

Run the installer on the air-gapped device and answer ``y`` at the first
question.

.. code-block:: console
   :caption: console on air-gapped device

   $ cd podman-qkdlite
   $ ./install_qkdlite_podman.sh

.. code-block:: console
   :caption: console on air-gapped device

   ==> Step 1: Container images
   Is this an offline (airgapped) install, with the images already loaded? [y/N]: y
     ✓ Offline mode: skipping registry login, images must already be loaded

The installer then skips the registry login and every image pull, and uses the
images loaded above. The remainder of the installation is identical to
:doc:`installation_podman`, starting at the topology configuration.

.. note::

   An air-gapped device cannot reach the registry, so a registry login there
   can only fail. Answering ``y`` is what tells the installer not to attempt
   one. Setting ``OFFLINE_MODE=1`` in ``qkdlite.conf`` has the same effect and
   skips the question.