🔌 Installation#

📜 Prerequisites#

Make sure these software are already installed on your system:

Docker (Installation Guide)
Pixi (Installation Guide)

If you are on a Mac, these dependencies can be quickly installed via homebrew executing:

brew install docker pixi

and verify the installation

docker version
pixi -V

🚀 Quick Start#

The package is under active development. To install QualPipe package you need to clone the source code from gitlab:

git clone https://gitlab.cta-observatory.org/cta-computing/dpps/qualpipe/qualpipe-webapp.git
cd qualpipe-webapp
git submodule update --init --recursive

Next, follow the installation instructions for developers.

Installation for developers#

Setup (first time only)#

1. Setup environment:#

pixi run dev-setup

This will:

✅ Create an isolate Python environment with pixi
✅ Install all dependencies from pyproject.toml (frontend, test, doc, dev)
✅ Install the ctao-qualpipe-webapp package in editable mode
✅ Generate data models
✅ Compile backend and frontend requirements
✅ Generate javascript schema
✅ Install node dependencies
✅ Install pre-commit hooks

Note

Pixi Environments: The project defines three environments in pixi.toml:

default - Uses development dependencies (same as qualpipe-webapp-dev)
qualpipe-webapp - Production environment with minimal dependencies
qualpipe-webapp-dev - Development environment with all dev/test dependencies

You can specify which environment to use with pixi run -e <environment> <task> or use the default environment. For development work, the default environment is recommended.

Tip

Development Shell: For a fully configurable development environment, use:

pixi shell

This activates the Pixi environment and is recommended for:

Making commits (pre-commit hooks will be available)
Log inspection and debugging
Running any commands from this guide that don’t start with pixi run

Best Practice: Run pixi run commands from a separate shell (not inside pixi shell) to avoid shell termination issues, as running pixi run tasks within an active pixi shell can terminate the shell environment.

To clean your pixi environment you can execute pixi clean.

2. Configure host#

To add qualpipe.local hostname to the /etc/hosts file execute:

echo "127.0.0.1 qualpipe.local" | sudo tee -a /etc/hosts

3. Start the local development environment#

To deploy the app and start the local development environment execute:

pixi run dev-up

✅ Create a kind cluster with port mappings
✅ Build Docker images (backend + frontend)
✅ Deploy the application via Helm

⏳ Wait for all pods to be ready (can take 2-3 minutes).

4. Access the application#

No port-forward needed! The kind cluster exposes ports directly via extraPortMappings.

Open in your browser:

Frontend: http://qualpipe.local:8080/home
Backend API: http://qualpipe.local:8080/api/docs

Dev Workflow (after the first time)#

Note

The local kubernetes cluster should be running already, if not execute pixi run dev-up. If you changed any dependency or modified code that requires model regeneration re-execute pixi run dev-setup.

Are images changed?#

Rebuild images and restart services with:

pixi run dev-restart

Are images NOT changed?#

Upgrade only Helm chart with:

pixi run helm-dev-upgrade

View logs#

To display logs from both backend and frontend containers execute:

pixi run kind-logs

To stop logs, you can soft-kill them with CTRL+C.

Verify installation#

To check that the app is correctly deployed and properly set up, execute this command:

pixi run dev-health