Skip to content

Local Quickstart + OSS Docker Path

Status & scope

  • Stage: DRAFT
  • Module: Dockerfile.parallax-standalone, docker-compose.parallax.yml, docs/QUICKSTART-LOCAL.md
  • Part of: #18 Full Fusion Cycle · Umbrella #6 · Supports #10 (Cold Start)
  • Milestone: M4 (OSS Substrate)

Problem

A curious engineer evaluating Athena must have it producing useful matches on their own data within 15 minutes of docker run. Today that's impossible without Titan, ES, and Xanadu — a multi-day setup. Every ambitious open-source fusion library that failed was abandoned at "looks cool, can't figure out how to start."

Decision

Ship a self-contained Docker image that includes: 1. All fusion primitives (parallax kernel) 2. SQLite persistence (component.parallax.local-persistence-adapter) 3. A bundled demo lens + small synthetic dataset 4. A CLI to query matches, inspect lineage, and attest from the terminal

No Titan. No ES. No Xanadu. No Beacon. Pure Athena + SQLite.

Architecture

docker run axonis/parallax-standalone \
  --lens examples/person_er_default.yaml \
  --data-a demo-data/firm_customers.csv \
  --data-b demo-data/vrs_sample.csv

    ┌───────────────────────────────────────┐
    │           Container                    │
    │                                        │
    │   1. Parse lens (person_er_default)   │
    │   2. Load + normalize records         │
    │   3. Block → score → cluster          │
    │   4. Persist to SQLite (axonis.db)    │
    │   5. Print summary                    │
    │   6. Drop into CLI (interactive)      │
    │         or exit (batch mode)          │
    │                                        │
    │   Volume mount: /data ← user's data   │
    │   Output: /output/axonis.db           │
    └───────────────────────────────────────┘

15-Minute Path

The QUICKSTART-LOCAL.md walk-through hits these gates:

Minute Gate What happens
0 Image pull docker pull axonis/parallax-standalone:latest
1 Run with demo data docker run ... --demo (uses bundled sample data + default person-ER lens)
3 Summary printed "Found 18 matches (15 confirmed, 3 probable, 0 conflict). 2 decayed. Evidence frozen."
4 Query from CLI axonis-cli matches list --status proposed shows results in table
5 Attest from CLI axonis-cli attest CR-001 --rationale "Evidence reviewed: name + DOB + postcode all match"
7 Run with own data docker run ... --data-a /data/my_file_a.csv --data-b /data/my_file_b.csv
10 Inspect lineage axonis-cli lineage CR-001 shows CREATED → ATTESTED chain
12 Run decay axonis-cli decay --lens person_er_default --dry-run shows what would transition
15 Export results axonis-cli export matches --format csv > my_matches.csv

Deliverables

(a) Dockerfile

Dockerfile.parallax-standalone: - Base: python:3.12-slim (or Iron Bank equivalent for regulated builds) - Installs parallax + SQLite (already in Python stdlib) - Entry point: parallax.ops.fusion.cli.main - Non-root (UID 1001), read-only FS except /output/ - <200MB compressed image size

(b) CLI

parallax/ops/fusion/cli/ (new module):

axonis-cli run     --lens <path> --data-a <path> --data-b <path> [--store <path>]
axonis-cli matches list [--status <status>] [--lens <lens_id>]
axonis-cli matches show <correlation_id>
axonis-cli lineage <correlation_id>
axonis-cli attest  <correlation_id> --rationale <text>
axonis-cli reject  <correlation_id> --rationale <text>
axonis-cli decay   --lens <lens_id> [--dry-run]
axonis-cli export  matches --format csv|json
axonis-cli reverse <federate_id>:<record_ref>
axonis-cli info    (shows lens, primitive versions, test count, store path)

Implemented with argparse (zero deps) or click (BSD, already common in Python CLI projects). Each command is a thin wrapper over the library functions from component.parallax.local-persistence-adapter..25 + existing fusion pipeline.

(c) Demo dataset + default lens

Ship with: - examples/person_er_default.yaml — person entity resolution (name + DOB + postcode + phone/email) - demo-data/firm_customers.csv (20 synthetic records — small enough to commit) - demo-data/vrs_sample.csv (30 synthetic records) - Ground truth file for validation

(d) docker-compose.parallax.yml

For evaluators who prefer compose:

services:
  parallax:
    image: axonis/parallax-standalone:latest
    command: ["run", "--lens", "/app/examples/person_er_default.yaml",
              "--data-a", "/data/firm.csv", "--data-b", "/data/vrs.csv",
              "--store", "/output/axonis.db"]
    volumes:
      - ./my-data:/data:ro
      - ./output:/output

(e) QUICKSTART-LOCAL.md

Step-by-step walk-through with copy-paste commands at each step. Includes troubleshooting section for common failures (Docker not running, CSV format mismatch, missing required fields).

Invariants

  1. No network dependency. The image works fully offline once pulled.
  2. No secrets required. Demo mode runs without API keys, tokens, or certificates.
  3. Reproducible. Same demo data + same image tag → same matches → same hashes.
  4. Volume-safe. User data is mounted read-only; output DB is user-owned.
  5. Sub-15-minute. If an evaluator following QUICKSTART-LOCAL.md takes more than 15 minutes to see queryable matches on the demo data, the spec has failed.

Testing

E2E test (CI)

  • test_quickstart_e2e — build image, run demo data, verify match count = expected, query CLI, attest, decay (all automated, no interactive input)
  • Gate: must pass on a fresh Docker daemon in under 5 minutes.

CLI command tests

  • Every axonis-cli subcommand has a dedicated test exercising both happy path and error handling
  • Store commands (matches, lineage, reverse, attest, reject) use :memory: SQLite backend
  • test_cli_info_shows_primitive_versions — validates that the versioning substrate (component.parallax.fusion-governance-lifecycle / #13) integrates cleanly

Image tests

  • test_image_non_root — verify container runs as UID 1001
  • test_image_read_only_fs — verify /app is immutable, /output is writable
  • test_image_size — compressed image <200MB
  • test_image_offline — disconnect network after pull, run demo, verify success

Acceptance

  • [ ] Dockerfile.parallax-standalone builds and pushes to registry.axonis.ai
  • [ ] docker-compose.parallax.yml works with user-mounted data
  • [ ] CLI runs all subcommands
  • [ ] QUICKSTART-LOCAL.md walk-through validated by someone other than the author
  • [ ] Demo data + default lens produce expected match count
  • [ ] E2E test passes in CI under 5 minutes
  • [ ] Sub-15-minute evaluator gate met (manual validation at least once)

Rollback plan

The quickstart is a deployment artifact, not a kernel change.

  1. Remove Dockerfile.parallax-standalone + docker-compose.parallax.yml.
  2. Remove CLI module parallax/ops/fusion/cli/.
  3. Remove demo data + default lens.
  4. The underlying specs (component.parallax.local-persistence-adapter..25) remain intact and functional without the quickstart.

No kernel dependency on the quickstart. It's pure packaging.

Out of scope (tracked separately)

  • Helm chart / K8s deployment → component.parallax.vrs-rest-api / existing charts/parallax/ (server path, not OSS path)
  • Domain-default lens packs (vessel-ER, emitter-ER) → #10 cold-start bootstrap
  • Label-100-pairs calibration UI → #10 cold-start bootstrap
  • Web-based UI → #17 (UX surfaces; quickstart is CLI-only by design)
  • Multi-node / federated quickstart → future; quickstart is single-process, two-node simulation only
  • Publication of the quickstart to public container registries (Docker Hub, GitHub Packages) → licensing decision (deferred per discussion; Apache 2.0 compatible)

Depends on: component.parallax.attestation-rationale, component.parallax.decay-scheduler, component.parallax.local-persistence-adapter, component.parallax.observation-reverse-index

Realizes: product.fusion