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 Selection

SQLite

Best for single-server deployments and environments where operational simplicity is paramount.

# Control Plane (default)
.\control_plane_app.exe --db-type sqlite --db-path auth_nexus_control.db

# Server Node (default)
.\server_app.exe --db-type sqlite --db-path auth_nexus_server.db

SQLite tuning:

• --sqlite-busy-timeout 5000 (default) -- timeout in milliseconds for lock contention.
• WAL mode is enabled automatically for concurrent read performance.

PostgreSQL

Recommended for multi-node deployments, high-availability requirements, or when the dataset exceeds a few GB.

# 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 for PostgreSQL; 2--4 for SQLite.
• 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 -- SQLite for single-server, PostgreSQL for multi-node.
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