Quickstart

Run the management stack with Docker, train one endpoint model, and activate it in a local Nginx instance. The commands below run from the product checkout, not the documentation website.

git clone https://github.com/georgi2005atanasov/pragma_change.git
cd pragma_change

Repository access is currently restricted. Use a GitHub account with access. The optional reference clients and dataset recorders live in a separate repository; they are examples to adapt, not required dependencies or published SDK products. The public documentation website is maintained separately from both repositories.

1. Start the management stack

Install Docker Engine with the Compose plugin, Python 3, and Git. On Linux, your account must have access to the Docker daemon. From this checkout:

python3 scripts/setup-env.py
docker compose up --build -d
docker compose ps
curl --fail http://127.0.0.1:8080/health

Open http://localhost:3000. Sign in with ADMIN_USERNAME and ADMIN_PASSWORD from the generated private .env. The setup script refuses to overwrite existing settings. The first build downloads dependencies and builds the portal, API, and trainer.

PostgreSQL and artifact files use named persistent volumes. Database and trainer ports are internal; the portal and API bind to loopback. Keep database and artifact backups together. For HTTPS, set PUBLIC_ORIGIN to the exact portal origin and COOKIE_SECURE=true. Changing environment credentials later does not reset an administrator already stored in the database.

docker compose logs --tail 100 api trainer portal
docker compose stop
# Start again without deleting data:
docker compose up -d

Avoid docker compose down -v unless you intend to delete stored data.

2. Configure one endpoint

In Endpoints, register an API host, then its method and path, for example api.example.test, POST, /orders. In Feature pipelines, select that endpoint and configure extractors, partition keys, windows, and ordered features. Save the immutable version.

A useful first pipeline selects X-Client-ID as a per-client partition and /amount from the JSON body, with request count and mean amount over a one-second window. The sample pipeline explains the structure; use the portal's real IDs and schema hash for imports.

New pipelines model one endpoint. Previously saved endpoint groups remain compatible, but new grouping is unavailable. Partition and runtime semantics describe exact window, extraction, and warm-up behavior.

3. Import data and train

In Datasets, choose the saved pipeline and download its templates. Supply either:

• Request-event JSONL: timestamped requests. Rust derives partitions, windows, and features.
• Feature-vector CSV: finite numeric features with the exact saved column names and order, plus the matching dataset manifest.
• An offline request recording: records.jsonl plus its finalized SDK recording manifest.json.

You can create compatible files yourself or adapt the reference recorders. No client library is required. Recording and upload instructions explain both paths and their limits.

Preview the import, correct every reported row error, and accept it. Training requires at least 20 complete vectors after warm-up. Use representative normal traffic from the actual endpoint. Synthetic examples test the workflow, not detection quality.

In Training & models, select the dataset and start training. The Python trainer uses the first 80% of rows for training and the last 20% for evaluation. Rust validates the export and checks score parity before publishing the model. Use Request replay to inspect features and decisions with isolated state.

4. Export and activate a release

In Releases, select one model per endpoint and thresholds satisfying 0 <= check < block <= 1. Download the archive. An anomaly score is not an attack probability; percentile suggestions are starting points and may need adjustment.

Follow the complete local Nginx walkthrough to build the module, start a sample upstream, create the partition secret, install the archive, and verify a matching request. It uses loopback ports 18081 and 19000 without changing a system Nginx installation.

For an existing proxy, compile against its exact Nginx version, configure flags, architecture, and libc. The bundled Nginx 1.28.0 Linux x86_64/glibc build is a reference, not a universal module. --with-compat does not remove these requirements. The C adapter links the Rust static runtime into ngx_http_pragmachange_module.so; a generic Rust .so cannot be loaded directly by Nginx.

Model releases normally reload Nginx. Native module upgrades require a reviewed restart. Manual installation and rollback remain available through scripts/deploy.py; remote server management adds pinned SSH, signed modules, configuration previews, durable jobs, serial rollouts, and verification of loaded releases.

Continue with application behavior, reference clients, or native development when you need them.