Requirements
This page covers everything you need before installing CodeXray Observability. Start with the tier that matches your current environment — and scale up as telemetry volume and monitored-node count grow.
If your environment exceeds 200 nodes or 1 TB/day of ingest — or you have specific HA, DR, or compliance requirements — reach out to our team at hello@codexray.io and we'll help you design the right topology.
Prerequisites
Operating System
- Linux (recommended) — Ubuntu 22.04+ or any modern distribution (RHEL 8+, Rocky, Alma, Debian 11+)
- Windows — supported with some limitations; typically used for agent-only deployments
Kubernetes
- Kubernetes 1.26+
- HA control plane (3 nodes)
- A default StorageClass with dynamic PVC provisioning
Network
- Internet access to the CodeXray GitHub repository (image pulls, updates)
- Open ports for OTLP ingestion, UI, and inter-service traffic (see Network & Ports)
- Outbound HTTPS for notification providers (Slack, PagerDuty, Microsoft Teams)
External Systems
- Backup infrastructure — customer-provided; our implementation team helps configure policies
- Identity provider — optional, required only if SSO (SAML / OIDC) is enabled
Sizing Overview
CodeXray's footprint is driven by two primary signals:
- Monitored nodes — the number of VMs and Kubernetes nodes agents run on
- Telemetry ingest — combined daily volume of metrics, traces, and logs
Pick the tier that matches your environment. Beyond the Medium tier, please contact our team for a tailored sizing plan.
| Tier | Nodes | Ingest | Active Users | Deployment | HA |
|---|---|---|---|---|---|
| POC / Evaluation | up to 10 | up to 50 GB/day | 1–5 | Docker / Docker Compose | — |
| Small | up to 100 | up to 500 GB/day | up to 20 | Kubernetes | ✓ |
| Medium | up to 200 | up to 1 TB/day | 20–30 | Kubernetes | ✓ |
| Large | beyond 200 | beyond 1 TB/day | custom | Kubernetes (tailored) | Contact us |
POC / Evaluation Setup
The fastest way to try CodeXray Observability. A single VM runs everything via Docker or Docker Compose — ideal for proof-of-concept, design-partner pilots, and small team evaluations.
What's included
- CodeXray platform (all services, single replica)
- ClickHouse (single node)
- Bundled UI
- A default project, tenant, and admin user — ready to log in
Minimum VM
| Role | Qty | Configuration |
|---|---|---|
| Single-host VM (Docker / Docker Compose) | 1 | 4 vCPU · 16 GB RAM · 100 GB SSD |
Supported deployment modes
- Docker — single container per service, run individually if you want fine-grained control
- Docker Compose — recommended; brings up the full platform with one command
- Docker Swarm — for basic multi-host POCs
Capacity & assumptions
- Monitored nodes: up to 10
- Daily ingest: up to 50 GB/day (metrics + traces + logs combined)
- Active users: 1–5 on dashboards
- Retention: 7–14 days (configurable)
- HA: not included — this is an evaluation setup
- OS: any modern Linux with Docker 24+ installed
If you're evaluating CodeXray, start with Docker Compose. You can run the full platform on a single VM, instrument a few services via OpenTelemetry, and validate outcomes in under an hour. When you're ready for production, graduate to the Small tier on Kubernetes.
The POC setup is purpose-built for evaluation. For production workloads — HA, redundancy, long retention, or higher ingest — move to the Small tier or above on Kubernetes.
Small Tier — up to 100 nodes / 500 GB/day
Right-sized for early production deployments, single-cluster environments, and teams validating CodeXray at scale.
Infrastructure
| # | Role | Qty | Configuration |
|---|---|---|---|
| 1 | Kubernetes cluster nodes — runs K8s CP & all CodeXray backend pods | 3 | 12 vCPU · 48 GB RAM · 500 GB SSD |
| 2 | ClickHouse — Observability & API Security DBs, single shard × 2 replicas | 2 | 12 vCPU · 64 GB RAM · 2 × 1.92 TB NVMe (RAID0) + 200 GB OS |
| 3 | CodeXAI — correlation & causation (optional) | 1 | 12 vCPU · 48 GB RAM · 500 GB SSD · 1 × RTX 4090 or equivalent (24 GB VRAM) GPU |
Kubernetes Pods
| Component | Replicas | Requests → Limits |
|---|---|---|
| Backend (Obs) | 2 | 500m / 1.5 Gi → 2 vCPU / 4 Gi (PVC 100 Gi) |
| Obs UI | 1 | 500m / 1.5 Gi → 2 vCPU / 4 Gi (PVC 100 Gi) |
| API backend (incl. ingestion & rule evaluator) | 2 | 300m / 512 Mi → 1 vCPU / 1.5 Gi |
| API UI | 1 | 100m / 256 Mi → 500m / 512 Mi |
| Prometheus / Metrics storage (Obs) | 1 | 500m / 2 Gi → 2 vCPU / 6 Gi (PVC 200 Gi) |
| Streaming / Kafka | 1 | 100m / 256 Mi → 500m / 512 Mi |
| Keeper (ClickHouse Keeper) | 3 (one per node) | 200m / 512 Mi → 1 vCPU / 1 Gi (hostNetwork or systemd) |
| CodeXAI — Anomalies & Forecasting (optional) | 2 | 4 vCPU / 6 Gi → 6 vCPU / 8 Gi |
| Kubernetes Control Plane | 3 (one per node) | 1 vCPU / 1 Gi → 2 vCPU / 4 Gi |
- OS: customer-provided — Ubuntu or any modern Linux preferred; Windows supported with limitations
- Storage headroom: provision 200 GB total to leave room for indexing and temp queries
- Throughput: handles up to ~100K metrics/min and ~200K requests/min
- Log ingestion: 200 GB/day included in the budget
- Active users: up to 20 concurrent users on dashboards / queries
- Retention: 30 days hot data — cold storage available on request for longer windows
- HA: all configurations are HA-enabled
- Network: internet access to the CodeXray GitHub repository with download access
- CodeXAI: sized for ~200 RCA investigations/day
- Backup: backup strategy is part of the implementation plan; customer provides backup infrastructure
Medium Tier — up to 200 nodes / 1 TB/day
Sized for mid-size fleets with higher ingest volume, larger user concurrency, and deeper ClickHouse sharding for write throughput.
Infrastructure
| # | Role | Qty | Configuration |
|---|---|---|---|
| 1 | Kubernetes cluster nodes — runs K8s CP & all CodeXray backend pods | 3 | 16 vCPU · 64 GB RAM · 500 GB SSD |
| 2 | ClickHouse — Observability & API Security DBs, 2 shards × 2 replicas | 4 | 12 vCPU · 64 GB RAM · 2 × 1.92 TB NVMe (RAID0) + 200 GB OS |
| 3 | CodeXAI — correlation & causation (optional) | 1 | 12 vCPU · 48 GB RAM · 500 GB SSD · 1 × RTX 4090 or equivalent (24 GB VRAM) GPU |
Kubernetes Pods
| Component | Replicas | Requests → Limits |
|---|---|---|
| Backend (Obs) | 3 | 1 vCPU / 2 Gi → 2 vCPU / 4 Gi (PVC 200 Gi) |
| Obs UI | 1 | 1 vCPU / 2 Gi → 4 vCPU / 6 Gi (PVC 200 Gi) |
| API backend (incl. ingestion & rule evaluator) | 2 | 500m / 1 Gi → 2 vCPU / 4 Gi |
| API UI | 1 | 200m / 512 Mi → 1 vCPU / 2 Gi |
| Prometheus / Metrics storage (Obs) | 1 | 2 vCPU / 4 Gi → 4 vCPU / 8 Gi (PVC 500 Gi) |
| Streaming / Kafka | 1 | 500m / 512 Mi → 1 vCPU / 2 Gi |
| Keeper (ClickHouse Keeper) | 3 (one per node) | 200m / 512 Mi → 1 vCPU / 1 Gi (hostNetwork or systemd) |
| CodeXAI — Anomalies & Forecasting (optional) | 2 | 6 vCPU / 8 Gi → 8 vCPU / 12 Gi |
| Kubernetes Control Plane | 3 (one per node) | 1 vCPU / 1 Gi → 2 vCPU / 4 Gi |
- OS: customer-provided — Ubuntu or any modern Linux preferred; Windows supported with limitations
- Storage headroom: provision 300 GB total to leave room for indexing and temp queries
- Throughput: handles up to ~250K metrics/min and ~300K requests/min
- Log ingestion: 200 GB/day included in the budget
- Active users: 20–30 concurrent users on dashboards / queries
- Retention: 30 days hot data — cold storage available on request for longer windows
- HA: all configurations are HA-enabled
- Network: internet access to the CodeXray GitHub repository with download access
- CodeXAI: sized for ~200 RCA investigations/day
- Backup: backup strategy is part of the implementation plan; customer provides backup infrastructure
Large Tier — beyond 200 nodes / 1 TB/day
For environments beyond 200 nodes or 1 TB/day of ingest, sizing becomes a conversation — not a spreadsheet. Typical considerations at this scale:
- ClickHouse sharding — increased shard and replica counts, or tiered storage
- Dedicated ingest path — isolated OTLP gateways by traffic class
- Cold storage — S3 / GCS / MinIO tiers for 90+ day retention
- Regional deployments — multi-region collectors with centralized query
- Disaster recovery — cross-region replication and failover playbooks
- Enterprise SSO / RBAC — organization-wide rollouts with granular access
Reach out at hello@codexray.io — our engineering team will design a reference architecture tailored to your environment, compliance needs, and growth plans.
Component Reference
Brief descriptions of the components listed in the sizing tables:
| Component | What it does |
|---|---|
| Observability Backend | Ingests telemetry (metrics, traces, logs) and serves queries to the UI. |
| Observability UI | The CodeXray Observability web interface. |
| Metrics Storage | Dedicated store for high-cardinality infrastructure metrics. |
| Streaming (Kafka) | Optional buffer that absorbs ingestion spikes. |
| Keeper | Coordination service for the ClickHouse cluster (HA deployments only). |
| CodeXAI | AI-driven correlation & causation engine. GPU-accelerated. Optional. |
| Kubernetes Control Plane | Cluster management nodes. |
If you deploy CodeXray's API Security product alongside Observability, the "API backend" and "API UI" rows in the pod tables cover that workload. For Observability-only installs, those rows can be skipped.
Network & Ports
Only two categories of traffic matter to most users: inbound telemetry from your services and UI access from your team.
| Purpose | Default Port | Protocol | Exposure |
|---|---|---|---|
| OTLP ingestion (gRPC) | 4317 | gRPC | Reachable by your applications / agents |
| OTLP ingestion (HTTP) | 4318 | HTTP | Reachable by your applications / agents |
| Web UI | 443 | HTTPS | Reachable by your team (behind Ingress / LB) |
All internal services are fronted by an Ingress / Load Balancer in production. Agents only need outbound access to the OTLP endpoints above.
Outbound HTTPS is required for alert destinations you enable — Slack, PagerDuty, Microsoft Teams, or generic webhook URLs.
Data Retention & Backup
- Default retention: 30 days of hot data (configurable)
- Cold storage: available on request — long-term archival to object storage (S3 / GCS / compatible)
- Backups: customer provides backup infrastructure; our implementation team helps configure schedules, retention policies, and restore playbooks
Scaling Considerations
Most customers scale in phases: POC → Small → Medium → custom. As ingest volume, node count, or user concurrency grows, consider:
- Longer retention — move older data to cold storage instead of growing hot capacity
- Higher write throughput — scale the storage layer horizontally
- Query isolation — dedicate capacity for heavy dashboard workloads
- Regional deployments — keep collectors close to applications, with centralized query
Reach out before crossing a tier boundary — we'll help you migrate without downtime and size the next tier against your actual workload patterns.
Need Help?
Sizing production observability is a conversation, not a spreadsheet. For anything beyond a basic deployment — HA design, DR planning, regulated-industry compliance, or bespoke retention policies — we're here.
- Email: hello@codexray.io
- Phone: +91 98106 28873
- Office: MSR North Tower, Nagwara, Bangalore, India — 560045
Our team will help you:
- Right-size your deployment for current and projected load
- Plan a staged rollout (POC → pilot → production)
- Design HA, DR, and backup strategies
- Validate security, compliance, and data-residency requirements
Next Steps
- Installation Guide — step-by-step deployment walkthrough
- Architecture — deep dive into the platform's data flow, storage, and scaling model