Quick Start

Get coreX Platform running in minutes with Docker Compose. This guide covers deployment, first login, and your first config apply.

Prerequisites

  • A Linux host with Docker and the Docker Compose plugin installed
  • Ports 80, 443, 3000, 8000, and 8404 available (configurable)

1. Clone the Repository

git clone https://github.com/ne4u/corex_manager.git
cd corex_manager

2. Configure Environment

Copy the example environment file and edit it:

cp .env.example .env

The .env.example file documents every configurable variable with inline comments. The tables below group them by category. At minimum, set the secrets marked required before starting the stack in production.

Generate strong secrets

Generate random values for SECRET_KEY, MCP_SECRETS_KEY, VECTOR_SECRETS_KEY, RESP_TRANSFORM_KEY, and the MCP tokens with:

python -c “import secrets; print(secrets.token_urlsafe(32))”

Core

VariableDefaultDescription
DATABASE_URLsqlite:///data/haproxy_manager.dbSQLAlchemy database URL. Use PostgreSQL for HA/production.
HAPROXY_CONFIG_PATH/app/data/haproxy.cfgPath where the generated HAProxy config is written.
HAPROXY_SOCKET_PATH/var/run/haproxy.sockHAProxy stats socket used by the control plane.
CERT_DIR/app/certsDirectory holding TLS certificates.
DATA_DIR./dataBase directory for persistent data bind mounts (haproxy config, postgres, valkey, varnish).
SECRET_KEY(random)Required for production. JWT signing key.
ADMIN_PASSWORD(random)Admin user password. Generated and logged on first start if unset.
LOG_LEVELINFOBackend log level.

Valkey (Redis-compatible cache/store)

VariableDefaultDescription
VALKEY_HOSTvalkeyValkey hostname.
VALKEY_PORT6379Valkey port.
VALKEY_DB0Valkey database index.
VALKEY_PASSWORD(empty)Set a strong password to require auth on the Valkey network.

Rate Limiting & Tasks

VariableDefaultDescription
RATE_LIMIT_REQUESTS100Max requests per window per identity.
RATE_LIMIT_WINDOW60Rate limit window in seconds.
TASK_QUEUE_ENABLEDtrueEnable the Valkey-backed async task queue.

Certificates

VariableDefaultDescription
AUTO_RENEW_ENABLEDtrueEnable automatic certificate renewal.
AUTO_RENEW_INTERVAL_SECONDS86400Renewal check interval (24h).

Coraza SPOA WAF

VariableDefaultDescription
CORAZA_SPOA_ENABLEDtrueEnable the Coraza WAF SPOA.
CORAZA_SPOA_HOSTcoraza-spoaCoraza SPOA hostname.
CORAZA_SPOA_PORT9000Coraza SPOA port.
CORAZA_SPOA_TARGETScoraza-spoa:9000SPOA targets passed to HAProxy.
CORAZA_SPOA_APPhaproxy-wafSPOA application name.
CORAZA_SPOA_CONFIG_PATHdata/coraza-spoa.yamlCoraza SPOA config file.
CORAZA_SPOA_AUTO_RESTARTtrueAuto-restart the SPOA on failure.
CORAZA_SPOE_CONFIG_PATHdata/coraza.cfgHAProxy SPOE config file.
CORAZA_SPOA_LOG_PATHdata/coraza-spoa.logCoraza JSON event log path.
WAF_RULE_VERSION_MAX_PER_RULE10Max WAF rule snapshots kept per rule (0 = unlimited).
CRS_DIRdata/crsOWASP CRS directory.
CRS_SNAPSHOT_MAX5Max CRS snapshots retained.
CUSTOM_RULES_DIRdata/custom-rulesCustom WAF rules directory.
RULE_SET_DOWNLOAD_INTERVAL_SECONDS300Remote rule set download interval.

CAPTCHA

VariableDefaultDescription
CAPTCHA_SERVICE_URLhttp://cap:3000Cap CAPTCHA service URL (Native provider).
CAPTCHA_SERVICE_PUBLIC_URLhttp://localhost:3001Legacy public URL (kept for backward compatibility).
CAPTCHA_CHALLENGE_URL/_cap/challengeChallenge URL path on the HAProxy listener.
CAPTCHA_SITE_KEY(empty)Cap site key.
CAPTCHA_SECRET(empty)Cap secret.
CAPTCHA_PROXY_PATH/_capPath prefix for proxying captcha traffic through HAProxy.
CAPTCHA_WIDGET_CDN_URLhttps://cdn.jsdelivr.net/npm/@cap.js/widget@0.1.57/cap.min.jsCDN URL for the Cap widget script.
CAPTCHA_API_BACKEND_HOSTapiBackend API host for challenge/verify proxy.
CAPTCHA_API_BACKEND_PORT8000Backend API port for challenge/verify proxy.
CAP_ADMIN_KEY(empty)Required if Cap service is enabled. Strong random key.
RECAPTCHA_SITE_KEY(empty)reCAPTCHA (Google) site key.
RECAPTCHA_SECRET(empty)reCAPTCHA secret.
RECAPTCHA_VERSIONv2reCAPTCHA version.
RECAPTCHA_MIN_SCORE0.5reCAPTCHA v3 minimum score.
TURNSTILE_SITE_KEY(empty)Cloudflare Turnstile site key.
TURNSTILE_SECRET(empty)Cloudflare Turnstile secret.

MaxMind GeoIP

VariableDefaultDescription
MAXMIND_LICENSE_KEY(empty)MaxMind license key for GeoIP DB downloads.
GEOIP_DOWNLOAD_INTERVAL_HOURS24GeoIP DB refresh interval.
GEOIP_DB_PATHdata/GeoLite2-Country.mmdbGeoIP Country DB path.
ASN_DB_PATHdata/GeoLite2-ASN.mmdbGeoIP ASN DB path.

Security Lists & Rules

VariableDefaultDescription
SECURITY_LISTS_DIRdata/listsSecurity list files directory.
SECURITY_LISTS_FEED_POLL_INTERVAL_SECONDS300Dynamic feed poll interval.
SECURITY_RULES_BLOCK_STATUS403HTTP status returned by block rules.

Audit

VariableDefaultDescription
AUDIT_PAYLOAD_MAX_BYTES16384Max bytes captured per audit payload.

Metrics

VariableDefaultDescription
HAPROXY_MASTER_SOCKET_PATH/var/run/haproxy-master.sockHAProxy master socket path.
HAPROXY_MAXCONN100000Max HAProxy connections. Lower if memory is limited.
METRICS_SAMPLE_INTERVAL_SECONDS30HAProxy metrics sample interval.
METRICS_RETENTION_DAYS7HAProxy metrics retention.
WAF_METRICS_SAMPLE_INTERVAL_SECONDS10WAF metrics sample interval.
WAF_METRICS_RETENTION_DAYS7WAF metrics retention.
WAF_LOG_RETENTION_LINES500Max raw coraza-spoa.log lines kept (0 = unlimited).

Caching

VariableDefaultDescription
DISK_CACHE_ENABLEDfalseEnable Varnish disk cache sidecar.
CACHE_METRICS_SAMPLE_INTERVAL_SECONDS30Cache metrics sample interval.
CACHE_METRICS_RETENTION_DAYS7Cache metrics retention.
VARNISH_CONTAINER_NAMEvarnishVarnish container name.
VARNISH_PORT6081Varnish port.
VARNISH_VCL_PATHdata/varnish/default.vclVarnish VCL config path.
VARNISH_STORAGE_SIZE1GVarnish storage size.
HAPROXY_CONTAINER_NAMEcorexHAProxy container name (used by Docker SDK).

Vector Log Pipeline

VariableDefaultDescription
VECTOR_IMAGEtimberio/vector:0.58.0-alpineVector container image.
VECTOR_SYSLOG_TARGETvector:601HAProxy coreX log stream target.
VECTOR_SECRETS_KEY(falls back to SECRET_KEY)Encryption key for sink credentials.

Response Transforms

VariableDefaultDescription
RESP_TRANSFORM_ENABLEDfalseEnable the response transform Rust Lua module.
RESP_TRANSFORM_DIRdata/resp-transformResponse transform module directory.
RESP_TRANSFORM_RELOAD_INTERVAL_SECONDS30Module reload check interval.
RESP_TRANSFORM_FALLBACK_KEY_ENVRESP_TRANSFORM_KEYEnv var name for tokenize-mode fallback AES key.
RESP_TRANSFORM_KEY(empty)AES-256 key (≥32 bytes) for encrypt-mode and tokenize fallback.

CORS & Session

VariableDefaultDescription
CORS_ALLOWED_ORIGINShttp://localhost:3000Comma-separated allowed CORS origins.
SESSION_TIMEOUT_MINUTES30GUI session timeout.
SESSION_WARNING_SECONDS60Session expiry warning countdown.

Data Plane API

VariableDefaultDescription
DATAPLANE_API_ENABLEDtrueEnable the HAProxy Data Plane API.
DATAPLANE_API_USERadminData Plane API user.
DATAPLANE_API_PASSWORD(empty)Required when enabled. Strong password.
DATAPLANE_API_CA_BUNDLE(empty)Optional CA bundle for verifying the Data Plane TLS cert.

HAProxy Stats Auth

VariableDefaultDescription
HAPROXY_STATS_USER(empty)Stats page user (set both to enable auth on :8404).
HAPROXY_STATS_PASS(empty)Stats page password.

API Armor

VariableDefaultDescription
API_ARMOR_ENABLEDfalseEnable API Armor (toggled via Global Options GUI).
API_ARMOR_MAX_BODY_BYTES1048576Max request body size for inspection.
API_ARMOR_MODULE_ENABLEDtrueUse the Rust Lua module vs pure-Lua fallback.
API_ARMOR_DIRdata/api-armorAPI Armor data directory.
API_ARMOR_PROFILE_LOG_PATHdata/api-armor/profiling.logProfiling log path.
API_ARMOR_PROFILE_LOG_MAX_BODY_BYTES4096Max body bytes captured per profile log entry.
API_ARMOR_PROFILE_LOG_MAX_SIZE_MB100Max profiling log size.
API_ARMOR_SCHEMA_LEARN_INTERVAL_SECONDS30Schema learning interval.
API_ARMOR_SCHEMA_LEARN_MIN_SAMPLES100Min samples before a schema is materialized.
API_ARMOR_SCHEMA_LEARN_RETENTION_DAYS30Learned schema retention.
API_ARMOR_PROFILE_RETENTION_DAYS30Behavioral profile retention.
API_ARMOR_PROFILER_INTERVAL_SECONDS30Profiler sampler interval.

MCP Gateway & Server

VariableDefaultDescription
MCP_GATEWAY_ENABLEDfalseEnable the MCP gateway proxy (policy/DLP/guardrails).
MCP_SECRETS_KEY(empty)Required when gateway enabled. Encrypts server auth secrets.
MCP_SELF_REGISTERtrueAuto-register the mcp-server into the gateway on startup.
COREX_MCP_TOKEN(empty)Bearer token for direct mcp-server connections (optional).
MCP_SERVICE_TOKEN(empty)Shared secret bypassing per-user rate limits on in-process calls.

Auth0 IdP

VariableDefaultDescription
AUTH0_DOMAIN(empty)Auth0 tenant domain.
AUTH0_CLIENT_ID(empty)Auth0 client ID.
AUTH0_CLIENT_SECRET(empty)Auth0 client secret.
AUTH0_SECRET(empty)Auth0 session secret.
AUTH0_MCP_AUDIENCE(empty)Auth0 API identifier MCP clients request tokens for.
AUTH0_SYNC_ENABLEDfalseEnable Auth0 user sync.
AUTH0_SYNC_TEAM_ID(empty)Team ID for synced users.

High Availability (HA)

Disabled by default. When HA_ENABLED=true, deploy with docker compose -f docker-compose.yml -f docker-compose.ha.yml up -d. See Docker Swarm and Kubernetes for HA on orchestrators.

VariableDefaultDescription
HA_ENABLEDfalseEnable HA mode (second HAProxy, Coraza, Valkey replica, Sentinel, keepalived).
HAPROXY_INSTANCES(empty)Semicolon-separated name=url[,user[,password]] inventory.
HAPROXY_PEER_PORT10000HAProxy peer port for stick-table replication.
HA_TOPOLOGYsingleTopology: single, single-host, or multi-host.
HAPROXY_HA_REPLICAS1HAProxy replica count (informational).
VALKEY_HA_REPLICAS1Valkey replica count (informational).
CORAZA_HA_REPLICAS1Coraza replica count (informational).
KEEPALIVED_VIP(empty)Floating IP clients connect to.
KEEPALIVED_VIRTUAL_ROUTER_ID51VRRP virtual router ID.
KEEPALIVED_PRIORITY100Priority for the primary instance.
KEEPALIVED_PRIORITY_290Priority for the secondary instance.
KEEPALIVED_INTERFACEeth0Network interface for VRRP.
KEEPALIVED_AUTH_PASSWORD(empty)Shared VRRP auth password (all instances must match).
KEEPALIVED_PEER_ADDRESSES(empty)Comma-separated peer IPs for unicast VRRP.
KEEPALIVED_ADVERT_INT1VRRP advert interval (seconds).
KEEPALIVED_PREEMPTtrueAllow the higher-priority instance to reclaim MASTER.
KEEPALIVED_TRACK_SCRIPT(empty)Optional health check script path.
VALKEY_SENTINEL_ENABLEDfalseEnable Valkey Sentinel for primary/replica failover.
VALKEY_SENTINEL_HOSTS(empty)Comma-separated Sentinel host:port list.
VALKEY_SENTINEL_SERVICEmymasterSentinel monitored master name.
CORAZA_SPOA_TARGETS_HAcoraza-spoa:9000,coraza-spoa2:9000Coraza SPOA targets for HA mode.

Docker Swarm mode

Set SWARM_MODE=true when deploying with docker stack deploy. See Docker Swarm.

VariableDefaultDescription
SWARM_MODEfalseEnable Swarm mode (skips keepalived; ingress mesh provides VIP + failover).
SWARM_API_IMAGEcorex-api:latestSwarm API image name (override if using a registry).
SWARM_HAPROXY_IMAGEcorex-haproxy:latestSwarm HAProxy image name.
SWARM_FRONTEND_IMAGEcorex-frontend:latestSwarm frontend image name.
SWARM_HAPROXY_REPLICAS2HAProxy replicas (HA + Swarm).
SWARM_CORAZA_REPLICAS2Coraza SPOA replicas (HA + Swarm).
SWARM_VALKEY_REPLICA_REPLICAS1Valkey replica count (HA + Swarm).
SWARM_SENTINEL_REPLICAS3Sentinel replicas for quorum (HA + Swarm).

3. Get a Free MaxMind GeoIP License Key

coreX Platform uses MaxMind’s GeoLite2 Country and ASN databases for GeoIP-based security rules, country blocking, and ASN-based rate limiting. The databases are free but require a MaxMind license key to download.

  1. Sign up for a free MaxMind account at www.maxmind.com
  2. After verifying your email, generate a license key in your account settings
  3. Set it in your .env: 
    MAXMIND_LICENSE_KEY=your_license_key_here
  4. coreX Platform downloads the GeoIP and ASN databases on startup and refreshes them every 24 hours
Why set this up now?

GeoIP and ASN databases power GeoIP security lists, ASN-based WAF rate limiting, and country-level access rules. Setting the key before the first start means these features work out of the box — no restart needed later.

4. Start the Stack

docker compose up -d --build

This starts the core services plus optional ones depending on your .env:

ServicePortDescription
frontend3000 (HTTP), 3443 (HTTPS)React web GUI
api8000FastAPI control plane
corex80 (HTTP), 443 (HTTPS/HTTP3), 8404 (stats), 5555 (Data Plane API)HAProxy data plane
coraza-spoa—Coraza WAF SPOA (internal)
valkey—In-memory store: caching, rate limits, tokens (internal)
postgres5432PostgreSQL database
cap3001Cap CAPTCHA service (when CAPTCHA is enabled)
varnish—Varnish disk cache (internal, when DISK_CACHE_ENABLED=true)
vector—Vector log pipeline (internal, when configured)
mcp-gateway-rs8089MCP gateway proxy (when MCP_GATEWAY_ENABLED=true)
mcp-server8082coreX MCP server exposing the control plane (when MCP_GATEWAY_ENABLED=true)

5. Log In

Open your browser to http://<host>:3000 and log in with:

  • Username: admin
  • Password: the value of ADMIN_PASSWORD from your .env file (or admin if unset)
Change the default password

For production deployments, always set ADMIN_PASSWORD in your .env file before starting the stack. If left unset, a random password is generated and printed in the API logs.

6. Add a Listener

  1. Navigate to Configuration > Listeners
  2. Click Add Listener
  3. Enter a name (e.g. web-frontend)
  4. Set bind address to 0.0.0.0 and port to 80
  5. Select protocol http
  6. Click Save

7. Add a Backend

  1. Navigate to Configuration > Backends
  2. Click Add Backend
  3. Enter a name (e.g. web-servers)
  4. Select protocol http
  5. Select algorithm roundrobin
  6. Click Save
  7. Click Servers on the backend row
  8. Add a server: name web1, address 127.0.0.1, port 8080
  9. Click Save

8. Apply Configuration

  1. Navigate to the Dashboard (home page)
  2. Click Preview to see the generated HAProxy config
  3. Review the config, then click Apply Config
  4. Watch the task toast in the bottom-right corner for progress
  5. Once applied, HAProxy is live and routing traffic
Config snapshots

Every Apply Config creates a config snapshot. You can revert to any previous snapshot from Management > Snapshots.

Service URLs

After deployment, the services are available at:

ServiceURLNotes
Web GUI (HTTP)http://<host>:3000React frontend
Web GUI (HTTPS)https://<host>:3443React frontend over TLS
APIhttp://<host>:8000FastAPI control plane
HAProxy (HTTP)http://<host>:80Data plane ingress
HAProxy (HTTPS)https://<host>:443Data plane ingress over TLS
HAProxy (HTTP/3)https://<host>:443QUIC/HTTP3 over UDP (443/udp)
HAProxy Statshttp://<host>:8404Stats page (set HAPROXY_STATS_USER/PASS to enable auth)
Data Plane APIhttps://<host>:5555/v3HAProxy Data Plane API (when DATAPLANE_API_ENABLED=true)
CAPTCHAhttp://<host>:3001Cap challenge service (when CAPTCHA enabled)
MCP Gatewayhttp://<host>:8089/mcpTools appear as corex-manager__* (when MCP_GATEWAY_ENABLED=true)
MCP Serverhttp://<host>:8082/mcpDirect MCP server; requires Authorization: Bearer <COREX_MCP_TOKEN>
PostgreSQL<host>:5432Database (bind to 127.0.0.1 in production)
Production hardening

Bind admin/internal ports (8000, 8404, 5555, 5432, 8082, 8089) to 127.0.0.1 in docker-compose.yml to prevent public access. Only the frontend (3000/3443) and HAProxy data plane (80/443) should be publicly exposed.

Next Steps

Next → Architecture