Deployment Guide

This guide covers everything needed to deploy AuthNexus in a production environment, from hardware sizing to operational configuration.

Hardware Requirements

Minimum (Development / Small Deployment)

Resource	Specification
CPU	2 cores
RAM	2 GB
Disk	10 GB SSD
OS	Windows Server 2019+ or Linux (kernel 5.4+)

Recommended (Production)

Resource	Specification
CPU	8+ cores
RAM	8+ GB
Disk	50+ GB SSD (NVMe preferred for DB)
Network	1 Gbps+

AuthNexus scales vertically. A single 8-core server node can handle thousands of concurrent SDK connections with the --auto thread configuration.

Database Configuration

AuthNexus uses PostgreSQL as its only database backend.

# Control Plane
.\control_plane_app.exe --db-type postgres \
    --db-host db.example.com --db-port 5432 \
    --db-user authnexus --db-pass secret \
    --db-name auth_nexus_control \
    --db-connect-timeout 5 \
    --db-statement-timeout 15000 \
    --db-lock-timeout 5000

# Server Node
.\server_app.exe --db-type postgres \
    --db-host db.example.com --db-port 5432 \
    --db-user authnexus --db-pass secret \
    --db-name auth_nexus_server

The Control Plane DB and Server Runtime DB are always separate databases, even when both use PostgreSQL. Do not share a database instance between them in production.

Port Mapping

Port	Process	Protocol	Bind Default	Description
9090	control_plane_app	HTTP	127.0.0.1	Admin API (/admin/v1/*)
9091	control_plane_app	mTLS HTTP	0.0.0.0	CP southbound (/cp/v2/* + SSE)
9092	control_plane_app	Plain HTTP	0.0.0.0	OCSP responder
8080	server_app	mTLS TCP	0.0.0.0	Business protocol (SDK connections)

Firewall Rules

• 9090: restrict to localhost or internal network (admin only).
• 9091: allow from server node IPs only.
• 9092: allow from server node IPs only.
• 8080: allow from SDK client networks.

Reverse Proxy (Admin API)

The admin API listens on loopback by default. Use a reverse proxy to expose it externally.

Nginx Example

server {
    listen 443 ssl;
    server_name admin.authnexus.example.com;

    ssl_certificate     /etc/nginx/certs/admin.crt;
    ssl_certificate_key /etc/nginx/certs/admin.key;

    location /admin/v1/ {
        proxy_pass http://127.0.0.1:9090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Do not proxy the CP southbound port (9091) through a non-mTLS reverse proxy -- it requires direct mTLS termination.

Thread Tuning

Automatic (Recommended)

.\server_app.exe --auto
.\control_plane_app.exe --auto

The --auto flag (enabled by default) scales thread counts based on CPU cores. See System Architecture for the scaling table.

Manual Override

Server node flags:

Flag	Domain	Default
-i / --io	IO threads	2
--logic-threads	Logic pool	auto
-d / --db	DB threads	2
-c / --crypto	Crypto threads	2
--cp-io	CP HTTP pool	1
--bg-threads	Background runtime	2

Control Plane flags:

Flag	Domain	Default
--admin-threads	Admin HTTP worker pool	auto
--cp-threads	CP southbound worker pool	auto
--bg-threads	Background runtime	auto

The CP also has event_thread_pool_count for SSE long-connection capacity. The actual httplib thread pool size is cp_thread_pool_count + event_thread_pool_count.

Tuning Guidelines

• IO threads: 1 per 2000 concurrent connections. Rarely needs more than 4.
• Logic threads: match to CPU cores available for business logic. The hot path.
• DB threads: scale with DB query concurrency. 3--8 typical for PostgreSQL.
• Crypto threads: scale with login rate (password hashing is the bottleneck). 2--4 typical.
• Cloud function threads: scale with Lua execution concurrency. Backpressure is managed by cloud_function_max_in_flight.

Logging

Log Levels

.\server_app.exe --log-level info     # Production default
.\server_app.exe --log-level debug    # Local troubleshooting only
.\server_app.exe --log-level trace    # Extreme verbosity
.\server_app.exe -q                   # Silent mode

WARNING

debug and trace levels generate tens of MB of logs quickly and will pollute benchmark samples. Use only for targeted troubleshooting.

Production Logging Recommendations

• Set --log-level info for production.
• Pipe output to a log aggregation system (e.g., journald, Windows Event Log, or a file-based collector).
• Monitor for WARN and ERROR entries, especially:
  • [Setup] -- PKI initialization issues
  • [CP Agent] -- Control Plane connectivity problems
  • [Security] -- blacklist or epoch sync failures
  • [TLS] -- certificate validation errors

Deployment Checklist

1. Build all targets in Release mode with --parallel.
2. Initialize PKI via the setup wizard (all four CAs).
3. Create nodes in the admin UI and download deploy packages.
4. Configure database -- provision PostgreSQL instances for the Control DB and Runtime DB.
5. Set up reverse proxy for the admin API (port 9090).
6. Configure firewall rules per the port mapping table above.
7. Start Control Plane first: control_plane_app.exe --auto.
8. Start server nodes: server_app.exe --auto --node-agent node_agent.json.
9. Verify node enrollment via the admin dashboard (node status should show "online").
10. Monitor certificate expiration via /admin/v1/pki/expiring.
11. Set log level to info and configure log rotation.

Windows Service Deployment

For production Windows deployments, use the provided batch script:

scripts\start_authnexus_control_plane.bat

This script starts the Control Plane without creating demo data, suitable for customer delivery.

Multi-Node Topology

                      ┌─────────────────────┐
SDK Clients ──mTLS──> │  server_app (Node 1) │──mTLS──┐
                      └─────────────────────┘         │
                      ┌─────────────────────┐         ▼
SDK Clients ──mTLS──> │  server_app (Node 2) │──mTLS──> control_plane_app
                      └─────────────────────┘         ▲      (centralized)
                      ┌─────────────────────┐         │
SDK Clients ──mTLS──> │  server_app (Node 3) │──mTLS──┘
                      └─────────────────────┘

Each node operates independently with its own Runtime DB. The Control Plane is the single coordination point for configuration, commands, and security policy.

Next Steps

• Operations Manual -- monitoring, maintenance, and troubleshooting
• System Architecture -- thread domain and database details
• TLS & PKI -- certificate rotation procedures