Collector Installation

This guide imports the Ozone Data Collector OVA and brings it up clean on the first boot. The appliance is immutable, so every fix ships as a new image, never as a live edit, and installation is "import, boot, verify," not "configure."

1. Size the host

Start from the baseline and scale by device count and collection cadence. The two heavy consumers are the VictoriaMetrics time-series store and the JetStream buffer during a WAN outage.

Profile	Devices	vCPU	RAM	Disk (SSD)
PoC / small branch	≤ 100	4	8 GB	100 GB
Standard site	100–500	8	16 GB	250 GB
Large site	500–2000	16	32 GB	500 GB+

Disk sizing math (plan for the buffer, not just steady state):

steady_state_disk ≈ (metrics_series × 30d retention)            # VictoriaMetrics, --retentionPeriod=30d
                  + 20 GB overhead (images, SQLite, OS)
                  # logs and flows are forwarded upstream, not retained locally in a columnar store;
                  # their transient footprint lives in the JetStream buffer below

wan_outage_buffer ≈ avg_forward_rate × longest_expected_outage  # JetStream store-and-forward backlog
                  # e.g. 2 MB/s curated forward × 24h ≈ ~170 GB worst case, so size headroom for it

Under-sizing disk is the most common field issue: a long WAN outage fills the data mount with the JetStream backlog. Size for your worst-case outage window, and watch disk before it bites. See Troubleshooting, buffer overflow.

The appliance keeps its own state in SQLite (roughly 15 databases, one per subsystem) on a host bind mount at AIOPS_DATA_DIR (default /opt/aiops/data), not a Docker named volume. That mount survives rebuilds, docker volume prune, and docker system prune. Include it in your disk plan, and never run docker compose down -v on a live appliance (see Section 4).

2. Import the OVA

The appliance ships as TechForcz-Collector-v1.x.ova (~8 GB). VirtualBox is validated; vSphere and KVM are the field targets.

VMware vSphere / ESXi

# Deploy via OVF Tool; pin the appliance to a datastore and a network that can reach both
# the monitored devices (LAN) and the internet egress to ozone.techforcz.com.
ovftool \
  --datastore=DS_SSD_01 \
  --network="VLAN_MGMT" \
  --diskMode=thin \
  --name="techforcz-collector-site01" \
  TechForcz-Collector-v1.x.ova \
  "vi://administrator@vsphere.local:PASSWORD@vcenter.example/DC/host/Cluster/Resources/RP_Observability"

KVM / libvirt (convert the OVA's VMDK and define a domain):

tar -xvf TechForcz-Collector-v1.x.ova                       # yields the .ovf + .vmdk
qemu-img convert -O qcow2 TechForcz-Collector-disk1.vmdk collector.qcow2
virt-install --name techforcz-collector-site01 \
  --memory 8192 --vcpus 4 \
  --disk path=/var/lib/libvirt/images/collector.qcow2,bus=virtio \
  --network bridge=br-mgmt,model=virtio \
  --import --os-variant ubuntu22.04 --noautoconsole

VirtualBox (lab/PoC):

VBoxManage import TechForcz-Collector-v1.x.ova --vsys 0 --vmname techforcz-collector-lab
VBoxManage modifyvm techforcz-collector-lab --memory 8192 --cpus 4 --nic1 bridged
VBoxManage startvm techforcz-collector-lab --type headless

Place the appliance on a segment that satisfies both sides of the firewall requirements: inbound from devices on the LAN, outbound 443 to the Orchestrator.

3. Cold boot

First boot comes up clean with no manual intervention. The Compose stack starts in dependency order: datastores, then collectors, then intelligence, then presentation.

# From the appliance console after boot, the canonical (and only) stack:
cd /opt/techforcz/collector/deploy/docker-compose
docker compose ps        # every aiops-* container should reach Up / healthy

If a service is stuck in Restarting, do not edit the container. Capture state and consult Troubleshooting. Because the appliance is immutable, any fix ships in a new image rather than as a live patch.

4. The single-stack rule

One appliance runs exactly one Compose stack. A second docker-compose.yml (for example a stray copy under /opt/techforcz) collides on the datastore and collector ports and cascade-breaks the appliance.

# There must be exactly ONE result (ignore python site-packages):
find / -name docker-compose.yml 2>/dev/null | grep -v site-packages
# Expect ONLY:
#   /opt/techforcz/collector/deploy/docker-compose/docker-compose.yml

If a duplicate exists, stop and remove the non-canonical stack, and never run two. Likewise, treat the OVA as immutable: every fix ships as a new appliance version.

Never docker compose down -v on a live appliance. The -v flag deletes Docker volumes. Appliance state is safe on the AIOPS_DATA_DIR host bind mount, but a reflexive down -v still tears down the running stack and is the wrong tool for a restart. Use docker compose restart <service> or docker compose up -d.

5. Verify the stack

# Full appliance self-check, writes /opt/techforcz/logs/diagnostics.json
python3 /opt/techforcz/bin/diagnostics.py

# Confirm every container is up and healthy
cd /opt/techforcz/collector/deploy/docker-compose
docker compose ps

# Open the local WebUI (operator console) and confirm devices and dashboards load
curl -s localhost:3000 | head -3

Expected pre-enrolment baseline: 13 of 16 diagnostic checks pass. Checks 13/15/16 (registration, DNS-to-Orchestrator, SaaS-reachable) are meant to fail until the appliance is enrolled and the Orchestrator is reachable, which is healthy, not broken.

Next	Guide
Open the network paths the appliance needs	Firewall & Network
Route egress through a proxy	Outbound Proxy
Register and finish verification	Enrolment & Verification

1. Size the host​

2. Import the OVA​

3. Cold boot​

4. The single-stack rule​

5. Verify the stack​

1. Size the host

2. Import the OVA

3. Cold boot

4. The single-stack rule

5. Verify the stack