Installation Guide (On-Premises)

This guide walks you through deploying CodeXray API Security in your on-premises infrastructure. The installation process is streamlined for rapid deployment, typically completing within minutes once prerequisites are met.

Prerequisites

Before beginning the installation, ensure your environment meets the following requirements.

Hardware Requirements

CodeXray API Security can be deployed on various scales depending on your expected API traffic volume. Below are reference configurations for common deployment sizes.

Small Deployment (Up to 100 Nodes / 500 GB/day)

Component	Quantity	Specifications
Kubernetes Cluster Nodes	3	12 vCPU, 48 GB RAM, 500 GB SSD
ClickHouse Database	2	12 vCPU, 64 GB RAM, 2×1.92 TB NVMe (RAID0) + 200 GB OS

Capacity:

Supports up to 100 monitored nodes
Handles approximately 200K requests per minute
30 days hot data retention
Up to 20 active dashboard users

Medium Deployment (Up to 200 Nodes / 1 TB/day)

Component	Quantity	Specifications
Kubernetes Cluster Nodes	3	16 vCPU, 64 GB RAM, 500 GB SSD
ClickHouse Database	4	12 vCPU, 64 GB RAM, 2×1.92 TB NVMe (RAID0) + 200 GB OS

Capacity:

Supports up to 200 monitored nodes
Handles approximately 300K requests per minute
30 days hot data retention
Up to 30 active dashboard users

Scaling Note: For deployments exceeding these specifications, contact your CodeXray solutions architect for customized hardware sizing recommendations.

Software Requirements

Operating System

Ubuntu 20.04 LTS or later (recommended)
Any modern Linux distribution (RHEL, CentOS, Debian)
Windows Server (supported with limitations)

Container Orchestration

Kubernetes 1.24 or later
Docker 20.10 or later (for Docker Compose deployments)
kubectl CLI tool installed and configured

Network Requirements

Internet access to CodeXray GitHub repository (for initial setup)
Outbound HTTPS (443) connectivity for license validation
Internal network connectivity between cluster nodes
Load balancer or ingress controller for external access

Access Requirements

Root or sudo privileges on installation nodes
Administrative access to Kubernetes cluster
Access to container registry (if using private registry)

Provided by CodeXray

Before installation, you will receive the following from CodeXray:

Personal Access Token (PAT) - Authentication credential for accessing CodeXray resources
Agent Binary - CodeXray collection agent for your architecture (x86_64, ARM64)
Deployment Files - Configuration files based on your chosen deployment method:
- Docker Compose files (for standalone deployments)
- Kubernetes manifests (for cluster deployments)
- Helm charts (optional, for advanced configurations)

Security Note: Store your PAT securely. It provides access to your CodeXray deployment and should be treated as a sensitive credential.

Deployment Architecture Overview

CodeXray API Security consists of several core components that work together to provide comprehensive API visibility and security analysis.

Core Components:

API Backend & Ingestion

Receives and processes API telemetry from collection agents
Performs real-time rule evaluation and risk scoring
Handles HAR file and Postman collection uploads

ClickHouse Database

Stores API metadata, vulnerabilities, and risk scores
Provides high-performance querying for dashboards
Configured with replication for high availability

Web Dashboard

User interface for visualization and analysis
Role-based access control (RBAC)
Report generation and export capabilities

Message Queue (Kafka)

Handles asynchronous processing of telemetry data
Ensures reliable data ingestion under high load
Decouples collection from processing

Installation Methods

CodeXray API Security supports two primary deployment methods. Choose the approach that best fits your infrastructure.

Method 1: Docker Compose Deployment

Ideal for single-node deployments, development environments, or proof-of-concept installations.

Step 1: Prepare Environment

Create a dedicated directory for CodeXray installation:

mkdir -p /opt/codexray-api-security
cd /opt/codexray-api-security

Step 2: Configure Authentication

Set your Personal Access Token as an environment variable:

export CODEXRAY_PAT="your-pat-token-here"

For persistent configuration, add to your shell profile:

echo 'export CODEXRAY_PAT="your-pat-token-here"' >> ~/.bashrc
source ~/.bashrc

Step 3: Download Deployment Files

Extract the provided deployment package:

tar -xzf codexray-api-security-compose.tar.gz
cd codexray-api-security

The package contains:

docker-compose.yml - Main orchestration file
.env.example - Environment variable template
config/ - Configuration files for each component

Step 4: Configure Environment Variables

Copy and customize the environment template:

cp .env.example .env
nano .env

Key Configuration Parameters:

# Database Configuration
CLICKHOUSE_HOST=clickhouse
CLICKHOUSE_PORT=8123
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=your-secure-password

# API Backend Configuration
API_BACKEND_PORT=8080
API_BACKEND_REPLICAS=2

# Dashboard Configuration
DASHBOARD_PORT=3000
DASHBOARD_ADMIN_EMAIL=admin@yourcompany.com

# Security
JWT_SECRET=generate-random-secret-here
SESSION_SECRET=generate-random-secret-here

Security Tip: Generate strong random secrets using openssl rand -base64 32 for production deployments.

Step 5: Deploy Services

Launch all CodeXray services:

docker-compose up -d

Verify all containers are running:

docker-compose ps

Expected output should show all services in "Up" state.

Step 6: Verify Installation

Check service health:

# API Backend health check
curl http://localhost:8080/health

# Dashboard accessibility
curl http://localhost:3000/health

Access the dashboard at http://your-server-ip:3000 and log in with your configured credentials.

Method 2: Kubernetes Deployment

Recommended for production environments requiring high availability, scalability, and enterprise-grade reliability.

Step 1: Prepare Kubernetes Cluster

Verify cluster access and readiness:

kubectl cluster-info
kubectl get nodes

Ensure all nodes are in "Ready" state.

Step 2: Create Namespace

Isolate CodeXray resources in a dedicated namespace:

kubectl create namespace codexray-api-security
kubectl config set-context --current --namespace=codexray-api-security

Step 3: Configure Secrets

Create Kubernetes secret for authentication:

kubectl create secret generic codexray-auth \
  --from-literal=pat-token="your-pat-token-here" \
  --from-literal=clickhouse-password="your-secure-password" \
  --from-literal=jwt-secret="your-jwt-secret" \
  --namespace=codexray-api-security

Step 4: Apply Kubernetes Manifests

Extract and review the provided Kubernetes manifests:

tar -xzf codexray-api-security-k8s.tar.gz
cd codexray-api-security-k8s

Manifest Structure:

01-clickhouse/ - Database deployment and services
02-kafka/ - Message queue infrastructure
03-api-backend/ - API processing services
04-dashboard/ - Web interface deployment
05-ingress/ - External access configuration

Review and customize resource limits in each manifest based on your hardware specifications.

Step 5: Deploy ClickHouse Database

Deploy the database layer first:

kubectl apply -f 01-clickhouse/

Wait for ClickHouse pods to be ready:

kubectl wait --for=condition=ready pod -l app=clickhouse --timeout=300s

Step 6: Deploy Supporting Services

Deploy Kafka and supporting infrastructure:

kubectl apply -f 02-kafka/
kubectl wait --for=condition=ready pod -l app=kafka --timeout=300s

Step 7: Deploy Application Services

Deploy API backend and dashboard:

kubectl apply -f 03-api-backend/
kubectl apply -f 04-dashboard/

Monitor deployment progress:

kubectl get pods -w

Wait until all pods show "Running" status and pass readiness checks.

Step 8: Configure Ingress (Optional)

If using an ingress controller for external access:

# Customize ingress.yaml with your domain
nano 05-ingress/ingress.yaml

# Apply ingress configuration
kubectl apply -f 05-ingress/

Step 9: Verify Installation

Check all deployments are healthy:

kubectl get deployments
kubectl get services
kubectl get pods

Retrieve dashboard URL:

kubectl get ingress codexray-dashboard

Access the dashboard and verify login functionality.

Post-Installation Configuration

Initial Administrative Setup

Create First Admin User

Access the CodeXray dashboard
Navigate to Settings → User Management
Create an admin account with organization-wide permissions
Configure password policies and session timeouts

Configure Data Retention

Set retention policies based on compliance requirements:

Navigate to Settings → Data Retention
Configure hot data retention (default: 30 days)
Enable cold storage if long-term retention is required
Set up automated backup schedules

Set Up Organizations and Teams

Structure access control for your deployment:

Create organizations for different business units
Establish teams within organizations
Assign users to appropriate teams
Configure role-based permissions

Agent Deployment

Deploy CodeXray agents to applications for automatic telemetry collection:

Copy Agent Binary to Application Servers

# Transfer agent binary
scp codexray-agent-linux-amd64 user@app-server:/usr/local/bin/codexray-agent
ssh user@app-server 'chmod +x /usr/local/bin/codexray-agent'

Configure Agent

Create agent configuration file on application server:

# /etc/codexray/agent.yaml
server:
  endpoint: "https://your-codexray-api-backend:8080"
  auth_token: "your-pat-token"

collection:
  sample_rate: 1.0  # Collect 100% of traffic
  redact_sensitive: true
  buffer_size: 1000

monitoring:
  health_check_port: 9090
  metrics_enabled: true

Start Agent as Systemd Service

# Create systemd service file
sudo nano /etc/systemd/system/codexray-agent.service

[Unit]
Description=CodeXray API Security Agent
After=network.target

[Service]
Type=simple
User=codexray
ExecStart=/usr/local/bin/codexray-agent --config /etc/codexray/agent.yaml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable codexray-agent
sudo systemctl start codexray-agent
sudo systemctl status codexray-agent

Validation and Testing

Functional Verification

Test Manual Upload Functionality

Export a sample Postman collection
Upload through dashboard interface
Verify API discovery in inventory view
Check risk scores are computed

Test Agent Telemetry

Generate test traffic to instrumented application
Verify telemetry appears in dashboard within 60 seconds
Confirm real-time risk scoring is functioning
Validate vulnerability detection

Test Dashboard Features

Navigate through inventory, risk analysis, and vulnerability views
Generate a security report
Test search and filtering capabilities
Verify RBAC by logging in with different user roles

Performance Validation

Monitor system performance under expected load:

# Check resource utilization
kubectl top nodes
kubectl top pods

# View API backend logs
kubectl logs -l app=api-backend --tail=100

# Monitor ClickHouse query performance
kubectl exec -it clickhouse-0 -- clickhouse-client --query "SELECT * FROM system.query_log ORDER BY query_start_time DESC LIMIT 10"

Troubleshooting

Common Installation Issues

Pods Not Starting

Check pod events for detailed error messages:

kubectl describe pod <pod-name>
kubectl logs <pod-name> --previous

Common causes:

Insufficient resources (increase node capacity)
Image pull failures (verify PAT and network access)
Configuration errors (review ConfigMaps and Secrets)

Database Connection Failures

Verify ClickHouse is accessible:

kubectl exec -it clickhouse-0 -- clickhouse-client --query "SELECT 1"

Check network policies allow pod-to-pod communication.

Dashboard Not Accessible

Verify ingress configuration:

kubectl get ingress
kubectl describe ingress codexray-dashboard

Check service endpoints:

kubectl get endpoints codexray-dashboard

Agent Not Sending Data

Review agent logs:

sudo journalctl -u codexray-agent -f

Verify network connectivity:

curl -v https://your-codexray-api-backend:8080/health

Check authentication token validity.

Security Hardening

Production Security Checklist

Network Security

Configure firewall rules to restrict access
Enable TLS for all external endpoints
Use network policies to isolate pods
Implement intrusion detection

Authentication and Authorization

Enforce strong password policies
Enable multi-factor authentication
Regularly rotate secrets and tokens
Review and audit user permissions

Data Protection

Enable encryption at rest for ClickHouse
Configure automated backups
Test backup restoration procedures
Implement data retention policies

Monitoring and Auditing

Enable audit logging for all administrative actions
Set up alerts for suspicious activity
Monitor resource utilization
Review logs regularly

Backup and Disaster Recovery

ClickHouse Backup Strategy

Automated Daily Backups

# Create backup script
cat > /usr/local/bin/backup-codexray.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="/backup/codexray/$(date +%Y%m%d)"
mkdir -p $BACKUP_DIR

# Backup ClickHouse
kubectl exec clickhouse-0 -- clickhouse-client --query "BACKUP DATABASE codexray TO Disk('backups', '$BACKUP_DIR')"

# Backup Kubernetes resources
kubectl get all -n codexray-api-security -o yaml > $BACKUP_DIR/k8s-resources.yaml
EOF

chmod +x /usr/local/bin/backup-codexray.sh

Schedule with Cron

# Run daily at 2 AM
0 2 * * * /usr/local/bin/backup-codexray.sh

Disaster Recovery Procedure

Restore from Backup

# Restore ClickHouse data
kubectl exec clickhouse-0 -- clickhouse-client --query "RESTORE DATABASE codexray FROM Disk('backups', '/path/to/backup')"

# Restore Kubernetes resources if needed
kubectl apply -f /backup/codexray/20241210/k8s-resources.yaml

Upgrade Procedures

Rolling Upgrade Process

CodeXray supports zero-downtime upgrades through rolling updates:

Backup Current State
```
/usr/local/bin/backup-codexray.sh
```

Update Docker Images or Manifests

# For Kubernetes
kubectl set image deployment/api-backend api-backend=codexray/api-backend:v2.0.0
kubectl rollout status deployment/api-backend

Verify Upgrade

kubectl get pods
curl http://api-backend/version

Rollback if Needed

kubectl rollout undo deployment/api-backend

Support and Resources

Getting Help

Technical Support

Email: support@codexray.io
Support Portal: https://support.codexray.com
Emergency Hotline: Available in enterprise agreements

Community Resources

GitHub Issues: Report bugs and request features
Community Forum: Ask questions and share knowledge
Documentation Feedback: Help improve our guides

Next Steps

After completing installation, proceed with:

Data Collection Configuration - Set up API discovery methods
Risk Analysis - Understand security scoring and insights

Welcome to CodeXray API Security! Your deployment is now ready to discover and secure your API landscape.

Prerequisites​

Hardware Requirements​

Small Deployment (Up to 100 Nodes / 500 GB/day)​

Medium Deployment (Up to 200 Nodes / 1 TB/day)​

Software Requirements​

Provided by CodeXray​

Deployment Architecture Overview​

Installation Methods​

Method 1: Docker Compose Deployment​

Step 1: Prepare Environment​

Step 2: Configure Authentication​

Step 3: Download Deployment Files​

Step 4: Configure Environment Variables​

Step 5: Deploy Services​

Step 6: Verify Installation​

Method 2: Kubernetes Deployment​

Step 1: Prepare Kubernetes Cluster​

Step 2: Create Namespace​

Step 3: Configure Secrets​

Step 4: Apply Kubernetes Manifests​

Step 5: Deploy ClickHouse Database​

Step 6: Deploy Supporting Services​

Step 7: Deploy Application Services​

Step 8: Configure Ingress (Optional)​

Step 9: Verify Installation​

Post-Installation Configuration​

Initial Administrative Setup​

Agent Deployment​

Validation and Testing​

Functional Verification​

Performance Validation​

Troubleshooting​

Common Installation Issues​

Security Hardening​

Production Security Checklist​

Backup and Disaster Recovery​

ClickHouse Backup Strategy​

Disaster Recovery Procedure​

Upgrade Procedures​

Rolling Upgrade Process​

Support and Resources​

Getting Help​

Next Steps​