Getting Started

This guide walks you through building AuthNexus from source, completing first-run PKI initialization, launching the core services, and verifying the setup with the admin frontend and SDK demo.

Prerequisites

Compiler & Toolchain

Requirement	Minimum Version
C++ Standard	C++23
MSVC (Windows)	Visual Studio 2022 17.8+
GCC (Linux)	13+
CMake	3.25+
Node.js	18+ (for admin frontend & website)

System Libraries

OpenSSL 3.x -- TLS, certificate operations, and HMAC hashing.
libpq + libpqxx -- required only when building with PostgreSQL support.
Lua 5.4 -- embedded for cloud function execution.

On Windows, the project uses static MSVC runtime linking (/MT / /MTd). MSVC flags include /W4 /permissive- /utf-8.

Building from Source

Configure

powershell

# Clone and enter the repository
git clone https://github.com/AuroraEchos/AuthNexus.git
cd AuthNexus

# Configure (first time or after CMakeLists.txt changes)
cmake -B build -S .

Compile

powershell

# Release build (recommended parallel flag)
cmake --build build --config Release --parallel 16

# Debug build
cmake --build build --config Debug --parallel 16

# Build a single target
cmake --build build --config Release --target control_plane_app --parallel 16

Key build targets:

Target	Description
`control_plane_app`	Unified admin + control plane process
`server_app`	Business TCP node (mTLS)
`unit_tests`	GoogleTest test binary
`benchmark_app`	SDK-level load testing
`sdk_demo`	Minimal SDK integration example

All binaries are output to build/bin/<Config>/. The schema/ directory is automatically copied next to the binaries via a POST_BUILD step.

Running Tests

powershell

# Full test suite
ctest --test-dir build -C Release --output-on-failure

# Filter by test name (regex)
ctest --test-dir build -C Release --output-on-failure -R "PasswordHasher|CloudFunction"

# Run the binary directly (useful for debugging)
.\build\bin\Release\unit_tests.exe --gtest_filter=PasswordHasher.*

PostgreSQL Tests

PostgreSQL tests require connection environment variables. Without them, PG-specific tests are skipped automatically.

powershell

$env:AUTHNEXUS_TEST_PG_HOST = "localhost"
$env:AUTHNEXUS_TEST_PG_PORT = "5432"
$env:AUTHNEXUS_TEST_PG_USER = "postgres"
$env:AUTHNEXUS_TEST_PG_PASSWORD = "your_password"

ctest --test-dir build -C Release --output-on-failure -R "PgDBTest"

First Run -- Control Plane

The Control Plane must be started first. On its initial launch, it enters setup-only mode: the /cp/* southbound endpoints are not served until PKI initialization is complete.

powershell

.\build\bin\Release\control_plane_app.exe --auto

By default, the admin HTTP API listens on 127.0.0.1:9090 (loopback only). The CP southbound interface listens on 0.0.0.0:9091 (for remote node access).

On first startup the console prints a one-time setup token. Save this token -- it is required to complete the web-based setup wizard.

PKI Initialization (Setup Wizard)

Open the admin frontend (see below) and navigate to the setup wizard at /admin/v1/setup/status. The wizard guides you through:

Root admin creation -- establish the platform administrator account.
CA bootstrap -- initialize the four independent Certificate Authorities:
- cp_server_ca -- Control Plane server certificate
- cp_node_client_ca -- Node-to-CP client certificate
- tcp_server_ca -- Business TCP server certificate
- app_client_ca -- SDK / application client certificate

Until all four CAs are initialized, the Control Plane remains in setup-only mode and will not serve /cp/* endpoints.

First Run -- Server Node

After the Control Plane is ready and a node has been created via the admin UI (which generates a node_agent.json deployment package):

powershell

.\build\bin\Release\server_app.exe --auto --node-agent node_agent.json

The server binds to 0.0.0.0:8080 by default for client TCP connections (TLS 1.3 + mTLS). The --auto flag selects thread counts based on CPU core count.

The server will not open its business TLS port until the CP Agent has successfully connected and applied critical configurations (fail-closed startup).

Admin Frontend

powershell

cd src\admin_frontend
npm install
npm run dev    # http://localhost:3000

The Vite dev server proxies /admin/v1 and /cp requests to localhost:9090.

Demo Mode (No Backend Required)

powershell

npm run dev:demo    # MSW intercepts all API calls in-browser

Demo mode uses MSW (Mock Service Worker) to intercept requests at /admin/v1 within the browser. No backend process is needed. Mock handlers live in src/admin_frontend/src/mocks/handlers/.

Production Build

powershell

npm run build       # Outputs to dist/
npm run build:demo  # Outputs to dist-demo/ (for embedding in the website)

Choose a Production Frontend Route First

Before publishing the admin frontend, choose the deployment route. This choice affects the Admin API endpoint: an HTTPS frontend cannot call a plain HTTP API from the browser.

Route	Frontend URL	Admin API URL	Best for	Required work
CDN + HTTPS	`https://panel.example.com`	`https://api.example.com/admin/v1`	Public admin panel with CDN acceleration/protection	CDN, domain, certificate, reverse proxy or tunnel
Native HTTP	`http://<server-ip>:<port>`	`http://<server-ip>:9090/admin/v1`	Local, intranet, temporary deployments	A plain HTTP static file server

Choose before deploying

If you choose the CDN route, the frontend will be HTTPS and the Admin API must also be reachable through HTTPS. If you do not want to configure certificates, reverse proxies, or tunnels, choose the native HTTP route from the start.

Route A: CDN + HTTPS

The login page lets operators enter the Admin API base URL. Choose one HTTPS access method before signing in:

Option	Best for	Login page value	Notes
Nginx / Caddy reverse proxy	You control a server and domain certificate	`https://api.example.com/admin/v1`	Keep `control_plane_app` bound to `127.0.0.1:9090`; terminate HTTPS at the proxy
Cloudflare Tunnel	You do not want to open public ports, or the server is behind NAT	`https://api.example.com/admin/v1`	Cloudflare provides the public HTTPS endpoint and forwards traffic to the local Admin API

Do not expose port 9090 directly

The Admin API defaults to 127.0.0.1:9090. In production, do not bind it directly to the public Internet. Put it behind HTTPS termination, a tunnel, and access controls.

Example Nginx reverse proxy:

nginx

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate     /etc/nginx/certs/api.example.com.crt;
    ssl_certificate_key /etc/nginx/certs/api.example.com.key;

    location /admin/v1/ {
        proxy_pass http://127.0.0.1:9090/admin/v1/;
        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 https;
    }
}

Example Cloudflare Tunnel ingress:

yaml

tunnel: authnexus-admin
credentials-file: /etc/cloudflared/authnexus-admin.json

ingress:
  - hostname: api.example.com
    service: http://127.0.0.1:9090
  - service: http_status:404

Route B: Native HTTP

Use this route when you do not want to deal with CDN, HTTPS certificates, reverse proxies, or tunnels. Serve the built admin frontend with any plain HTTP static server, then enter the HTTP Admin API URL on the login page:

text

http://<server-ip>:9090/admin/v1

Local or intranet use only

Native HTTP has no transport encryption and no CDN protection. For a long-running public admin panel, use the CDN + HTTPS route.

SDK Demo

After building, the sdk_demo binary provides a minimal integration example:

powershell

.\build\bin\Release\sdk_demo.exe

The SDK demo requires a running server_app with valid mTLS certificates. See SDK Integration for detailed integration steps.

Website (Marketing & Docs)

powershell

cd src\website
npm install
npm run dev              # http://localhost:5173
npm run build:with-demo  # Joint build including /demo/ sub-path

The dev server middleware routes /demo/* to the admin frontend demo build for a self-contained static site.

Directory Structure Overview

AuthNexus/
  build/bin/<Config>/     # Compiled binaries + schema/
  schema/                 # PostgreSQL schema files
  src/
    control_plane/        # Control Plane process source
    server/               # Server node process source
    core/                 # Shared library (DB, protocol, TLS, etc.)
    sdk/                  # C++ client SDK
    admin_frontend/       # Vue 3 admin dashboard
    website/              # VitePress marketing site
  tests/                  # GoogleTest source (*_tests.cpp)
  docs/                   # Internal design documents

Next Steps

System Architecture -- understand the three-process model
TLS & PKI -- deep dive into the certificate infrastructure
Deployment Guide -- production deployment checklist
SDK Integration -- integrate AuthNexus into your application

Getting Started ​

Prerequisites ​

Compiler & Toolchain ​

System Libraries ​

Building from Source ​

Configure ​

Compile ​

Running Tests ​

PostgreSQL Tests ​

First Run -- Control Plane ​

PKI Initialization (Setup Wizard) ​

First Run -- Server Node ​

Admin Frontend ​

Demo Mode (No Backend Required) ​

Production Build ​

Choose a Production Frontend Route First ​

Route A: CDN + HTTPS ​

Route B: Native HTTP ​

SDK Demo ​

Website (Marketing & Docs) ​

Directory Structure Overview ​

Next Steps ​

Getting Started

Prerequisites

Compiler & Toolchain

System Libraries

Building from Source

Configure

Compile

Running Tests

PostgreSQL Tests

First Run -- Control Plane

PKI Initialization (Setup Wizard)

First Run -- Server Node

Admin Frontend

Demo Mode (No Backend Required)

Production Build

Choose a Production Frontend Route First

Route A: CDN + HTTPS

Route B: Native HTTP

SDK Demo

Website (Marketing & Docs)

Directory Structure Overview

Next Steps