AGENTS.md

Dev

This repository manages the local Kubernetes development environment for Virtool using Tilt and Minikube.

Stack

• Tilt — orchestrates the dev cluster; the Tiltfile is the main entry point
• Minikube — local Kubernetes cluster
• KEDA — scales workflow jobs via a metrics-api trigger pointing at http://virtool-api-web-service.../jobs/counts
• MongoDB + PostgreSQL — persisted across tilt up/tilt down runs via PVCs
• Azurite — Azure Blob Storage emulator; uses the well-known dev account devstoreaccount1 with key Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw== and persists blobs at /data via a PVC

Layout

manifests/       Kustomize manifests for all cluster resources
  db/            MongoDB, PostgreSQL, Azurite
  ingress.yaml
  migration.yaml
  storage.yaml
  ui/
  virtool/
  workflows/     ScaledJob manifests for each workflow
scripts/
  init.sh        Create/reset the Minikube cluster
  hosts.sh       Write cluster IP to /etc/hosts
  pull.sh        Update image tags in kustomization + migration manifests
  wipe.sh        Nuke PVCs, PVs, and host data
Tiltfile         Tilt configuration (resources, buttons, live-edit flags)

Common tasks

Start the cluster

bash scripts/init.sh   # first time or full reset
tilt up

Live-edit a service (repo must be a sibling of this directory)

tilt up -- --to-edit backend   # virtool/virtool
tilt up -- --to-edit ui        # virtool/virtool-ui
tilt up -- --to-edit <workflow-name>

Workflow names: build-index, create-sample, create-subtraction, iimi, pathoscope, nuvs

Update images

bash scripts/pull.sh

Or click the Pull button in the Tilt UI.

Wipe persistent data

bash scripts/wipe.sh

Or click the Wipe button in the Tilt UI (requires confirmation).

Update /etc/hosts (needed once per cluster recreation)

bash scripts/hosts.sh

PR guidelines

• No test plan section in PR descriptions.