.. |br| raw:: html

   <br />

.. _getting_started:

======================================================
Setup
======================================================

This section covers the installation and setup required for PacketQC.

 **In This Section**

 #. :ref:`On-Premises Installation on a Single Device <h2-on-prem-installation-single-device>`

----

.. _h2-on-prem-installation-single-device:

---------------------------------------------------------
1. On-Premises Installation on a Single Device
---------------------------------------------------------

This deployment is designed for an on-premises environment where all application components are hosted on a single Windows or Linux device using Docker containers. The system consists of a frontend user interface, a backend processing engine, and a PostgreSQL database, all operating within the same local deployment environment.

.. figure:: _static/setupImgs/setup-onpremsingledevicearchitecture.png
   :width: 100%
   :align: center

   On prem single device setup for PacketQC

To ensure stable and reliable operation, the host device must have sufficient compute, memory, storage, and network resources to support all three containers concurrently.

Key considerations
^^^^^^^^^^^^^^^^^^^^^^^^

- CPU: The host machine should be provisioned with adequate CPU capacity to support backend processing workloads, especially when handling large PCAP files or multiple analysis requests.
- RAM: Sufficient memory must be available for Docker, the backend engine, the database, and the operating system to operate without resource contention.
- Storage: Storage capacity should also be planned carefully, as uploaded PCAP files, CBOM files, generated reports, database records, logs, and Docker volumes may grow over time depending on usage frequency and file size.
- Security: The device should be placed in a controlled on-premises environment with appropriate access restrictions.
- Architecture: Suitable for organizations that require a self-contained on-premises deployment, where uploaded network artifacts such as PCAP and CBOM files remain within the organization’s environment.

For detailed information on the required system specifications, please refer to the :ref:`System recommendations <system-recommendations>` section. The installation steps are provided in the following subsections.

* :ref:`System recommendations <system-recommendations>`
* :ref:`Docker all-in-one local setup: automated installation (Recommended)<install-on-a-single-laptop-recommended-automated-setup>`

----

.. _system-recommendations:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~
System recommendations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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

   * - Component
     - Recommendations
   * - Web Browser
     - Preferably the latest versions of Google Chrome, Mozilla Firefox or Microsoft Edge
   * - PostgreSQL
     - Version 18 or above
   * - Docker Engine
     - Version 29 or above
   * - CPU
     - 3 cores
   * - RAM
     - 4GB
   * - Storage
     - 2GB for Docker images, with additional storage allocated for the PostgreSQL persistent volume

----

.. _install-on-a-single-laptop-recommended-automated-setup:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Docker all-in-one local setup: automated installation (Recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This installation is meant for a single device with no existing setup. It will deploy the PacketQC UI, Engine, and PostgreSQL database on a Docker Swarm environment.

We provide installation scripts for PacketQC using the following files.

#. ``linux folder``, containing ``install-start.sh``, ``stop.sh`` and ``uninstall.sh``
#. ``windows folder``, containing ``install-start.bat``, ``stop.bat`` and ``uninstall.bat``
#. ``.env.example``
#. ``docker-stack.yml``
#. ``packetqc-images.tar``

|br|

Installing PacketQC
^^^^^^^^^^^^^^^^^^^^

For Windows installations, double-click ``install-start.bat`` to begin the installation. For Linux installations, such as Ubuntu, navigate to the ``linux`` folder and run ``bash install-start.sh`` to begin the installation.

During the installation process, you will be prompted to enter a PostgreSQL password. This password will be used to set up the initial PostgreSQL login credentials, so please keep it secure.

.. list-table::
   :widths: 27 73
   :class: borderless

   * - .. figure:: _static/setupImgs/setup-windowsscriptinstallation.png
          :width: 100%
          :align: center

          Windows installation script
     - .. figure:: _static/setupImgs/setup-postgrespassword.png
          :width: 100%
          :align: center

          Setting up PostgreSQL password

PacketQC will begin running once installation is complete. ``install-start.bat/sh`` can also be used to start PacketQC after it has been stopped. To stop PacketQC, run ``stop.bat/sh``.

|br|

Uninstalling PacketQC
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

PacketQC can be uninstalled using ``uninstall.bat/sh``. During the uninstall process, you will be prompted to confirm whether the following items should be removed:

* Docker Secrets, such as the PostgreSQL password
* Docker Images, which are PacketQC images stored locally on the host system
* Docker Volumes, including data stored in PostgreSQL
* The ``.env`` file, which contains application configuration settings

After PacketQC has been uninstalled using ``uninstall.bat/sh``, it can be reinstalled at any time by running ``install-start.bat/sh``.

.. note::

   **Recovering your PostgreSQL password**

   If you lose your password, you can retrieve it from the PostgreSQL container by running the following command. Replace ``container_id`` with that of your PostgreSQL container.

   .. code-block:: text

	    docker exec -it container_id cat /run/secrets/postgres_password