Setting up inoQulate
================================================================================
.. _built-in domain: https://learn.microsoft.com/en-us/azure/virtual-machines/create-fqdn
.. _custom domain: https://learn.microsoft.com/en-us/azure/virtual-machines/custom-domain
.. _Connect to the VM: https://learn.microsoft.com/en-us/azure/virtual-machines/linux-vm-connect?tabs=Linux#connect-to-the-vm

Once the VM deployment has completed, continue to set up the solution.


.. _prepare_ssh_keypair:

Prepare an SSH keypair for users
--------------------------------------------------------------------------------
Users connecting the SFTP server to drop and pick up files for inoQulation will
use SSH keys for authentication. You may use an existing keypair.

To create a new SSH keypair, use the ``ssh-keygen`` command.

.. code-block:: bash

   ssh-keygen -m PEM -t ed25519

Note the file path that the public key is saved in. The contents of the file is
the SSH public key.


.. _set_up_domain:

Set up a domain name for your VM
--------------------------------------------------------------------------------
Configure a domain name for your VM to access the web server: either Azure's
`built-in domain`_ or a `custom domain`_. A TLS certificate will automatically
be issued to this domain associated to your VM.

Using the solution without a domain name is currently not supported.

.. note::

   If you configured a custom domain, it may take up to a few hours for the
   domain name to be updated across all nameservers on the Internet.


Connect to your VM
--------------------------------------------------------------------------------
Connect to your VM with an SSH client of your choice.

Use the following parameters:

.. list-table::
   :header-rows: 1

   * - Parameter
     - Value
   * - Server
     - The FQDN as configured in :ref:`set_up_domain`
   * - Port
     - 22
   * - Username
     - ``core``
   * - Authentication Method
     - SSH Keypair or password-based, as configured in :ref:`create_the_vm`.

For example, using the ``ssh`` command line program,

.. code-block:: bash

   ssh core@inoqulate.example.com

See Azure Documentation's `Connect to the VM`_ for more details about
connecting via SSH.


Configure the setup
--------------------------------------------------------------------------------
There are three variables to configure in the file `/opt/inoqulate/init.env`:

#. **FQDN**: The fully qualified domain name of the VM as configured in
   :ref:`set_up_domain`. This configuration sets up automatic TLS issuance.
#. **SFTP_PUB_KEY**: The SSH public key for users as configured in
   :ref:`prepare_ssh_keypair`. This allows users holding the corresponding
   private key to access the SFTP server to drop and pick up PDF files.
#. **CN_PREFIX**: The prefix to prepend to all generated X.509 certificates,
   such as your company name.

An example of a configured file is:

.. code-block:: bash
   :caption: init.env

   FQDN=inoqulate.example.com
   SFTP_PUB_KEY=ssh-ed25519 AAAACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxp+
   CN_PREFIX=Mycompany


Choose **one** of two options to configure the variables:

#. Connect to your VM and use the text editor ``vim`` to edit and fill it the
   variables in the file with the command:

   .. code-block:: bash

      vim /opt/inoqulate/init.env

   or,

#. Create a new file with the contents on your local computer and copy it into
   the VM with:

   .. code-block:: bash

      scp init.env core@inoqulate.example.com:/opt/inoqulate/init.env


Start the installation
--------------------------------------------------------------------------------
To start the installation, run the following command in the VM:

.. code-block:: bash

   sudo systemctl start inoqulate-init &

The installation will continue in the background, and takes up to 10 minutes for
a virtual machine with 4 vCPUs.

You may monitor the installation progress with:

.. code-block:: bash

   journalctl -xeu inoqulate-init

Once the installation script has exited, the installation is complete.

.. tip::

   To save costs, it is recommended to stop and deallocate your VM when not in
   use. You will not lose any data.


Resetting the installation
--------------------------------------------------------------------------------
If the configuration is incorrect or the installation encountered an error, you
can reset the installation.

.. warning::

   The reset is a destructive operation. **You will lose any data created in the
   installation, including CA keys.** You should not reset the installation if
   you have begun using the solution.

To reset the installation, run:

.. code-block:: bash

   sudo systemctl start inoqulate-reset &

The reset will continue in the backgroud and should complete within one minute.
You can monitor its progress with:

.. code-block:: bash

   journalctl -xeu inoqulate-reset