Setup¶

This section covers the installation and setup required for PacketQC.

In This Section

On-Premises Installation on a 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.

_images/setup-onpremsingledevicearchitecture.png — Fig. 1 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 System recommendations section. The installation steps are provided in the following subsections.

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

System recommendations¶

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

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

Windows only: Before beginning, ensure that Docker Desktop is running if you are using Windows.

_images/setup-dockerdesktop.png — Fig. 2 Docker Desktop is running¶

Installing/Starting 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.

_images/setup-windowsscriptinstallation.png — Fig. 3 Install/Start, Stop and Uninstall scripts¶

During the installation process, you will be prompted to enter the following:

Azure token username.
Azure token password.
PostgreSQL password. This password will be used to set up the initial PostgreSQL login credentials, so please keep it secure.

_images/setup-azurelogin.png — Fig. 4 Login into Azure image registry¶

_images/setup-postgrespassword.png — Fig. 5 Setting up PostgreSQL password¶

PacketQC will begin running once installation is complete. The service can be accessed by navigating to http://localhost:80 in any web browser. install-start.bat/sh can also be used to start PacketQC after it has been stopped.

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.

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

Stopping PacketQC¶

To stop PacketQC, run stop.bat/sh.

Uninstalling PacketQC¶

Note

Preconditons

PacketQC must be stopped before it can be uninstalled.

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.