Deployment, Docker Stack & WildFly Setup

Helix Cortex can be deployed using containerized Docker orchestration or deployed directly to an existing WildFly 31 Application Server.

---

1. Quickstart with Docker Compose

The simplest way to run Helix Cortex and its dependencies locally is via Docker Compose:

# Clone the repository
git clone https://github.com/7amo10/helix-cortex.git
cd helix-cortex

# Copy and configure environment variables
cp .env.example .env

# Build and start services in background
docker compose up --build -d

Services Started:

• postgres: PostgreSQL 16-alpine database on port 5432 with automated healthcheck (pg_isready).
• redis: Redis 7 Alpine cache and Pub/Sub broker on port 6379 for cluster model activation broadcasts and L4 rule caching.
• helix-cortex: WildFly 31.0.0.Final container on port 8080 (HTTP) and 9990 (Management console), waiting for PostgreSQL and Redis to be healthy before launch.
• cortex_models Volume: Dedicated persistent Docker volume mounted to /opt/helix/models preserving uploaded .onnx binary artifacts across container restarts.

Verify container status:

docker compose ps
docker compose logs -f helix-cortex

---

2. Multi-Stage Docker Architecture

Helix Cortex utilizes a multi-stage Docker build to ensure lean, secure production images:

# Stage 1: Build Application WAR
FROM maven:3.9-eclipse-temurin-17 AS builder
WORKDIR /workspace
COPY pom.xml .
COPY src ./src
RUN mvn clean package -DskipTests

# Stage 2: Production WildFly Runtime
FROM quay.io/wildfly/wildfly:31.0.0.Final-jdk17
USER root
# Install PostgreSQL JDBC Module
COPY docker/module.xml /opt/jboss/wildfly/modules/system/layers/base/org/postgresql/main/module.xml
# Configure Datasource & MicroProfile Subsystems
COPY docker/standalone.xml /opt/jboss/wildfly/standalone/configuration/standalone.xml
# Deploy Built WAR
COPY --from=builder /workspace/target/helix-cortex.war /opt/jboss/wildfly/standalone/deployments/
USER jboss
EXPOSE 8080 9990
CMD ["/opt/jboss/wildfly/bin/standalone.sh", "-b", "0.0.0.0", "-bmanagement", "0.0.0.0"]

---

3. High-Concurrency HikariCP Pool Configuration

To prevent database bottlenecking during high-throughput rule execution workloads, Helix Cortex configures the CortexPool HikariCP connection pool with tuned thresholds:

Property	Value	Rationale
maximumPoolSize	16	Sized to match typical database CPU core saturation without thread thrashing.
minimumIdle	4	Ensures ready-to-use connections for sudden bursts of incoming requests.
connectionTimeout	3000 ms	Fails fast (3s) instead of stalling client threads during pool exhaustion.
idleTimeout	600000 ms	Reclaims inactive connections after 10 minutes.
maxLifetime	1800000 ms	Refreshes connections every 30 minutes to avoid stale TCP sockets.
poolName	CortexPool	Explicit naming for JMX and Prometheus thread pool monitoring.

This configuration was verified to yield 0 SQLTimeoutExceptions under 25-concurrent-thread synthetic load.

---

4. Environment Variables Reference

Variable	Default Value	Description
CORTEX_DB_HOST	postgres	Hostname or IP of the PostgreSQL server.
CORTEX_DB_PORT	5432	Database port.
CORTEX_DB_NAME	cortex_db	PostgreSQL database name.
CORTEX_DB_USER	cortex_user	Database user account.
CORTEX_DB_PASSWORD	cortex_pass	Database user password.
CORTEX_JWT_ISSUER	https://helix.pulse.com	MicroProfile JWT expected issuer URI.
REDIS_HOST	redis	Hostname or IP of the Redis server.
REDIS_PORT	6379	Redis service port for caching and model activation broadcasts.
CORTEX_MODELS_STORAGE_DIR	/opt/helix/models	Filesystem mount path for persistent ONNX model storage.
CORTEX_MODELS_REDIS_TOPIC	helix:models:activate	Redis Pub/Sub topic for cluster-wide model activation events.

---

Related Documentation & Cross-Links

• REST API Reference & Real-Time Telemetry - Complete endpoint specifications including the Model Registry Endpoints.
• System Architecture & Integration Flow - High-level BCE layer architecture and dynamic model activation pipeline.
• ONNX Model Inference Guide - Rule engine ONNX runtime configuration and session pool sizing.