2. Quick Start — Local Development

This guide gets you from zero to a running ArmoniK.Core deployment in under 15 minutes, using the recommended local stack (ActiveMQ + Redis + HtcMock worker).

Platform: Linux or WSL2. For native Windows, see Install on Windows 11.

2.1. Step 1 — Verify prerequisites

Run these commands to confirm all tools are installed:

terraform -version      # must be >= 1.4.2
just --version          # must be >= 1.29.0
docker info             # Docker daemon must be running
dotnet --version        # must be >= 10.0

If any tool is missing, follow Prerequisites to install it.

2.2. Step 2 — Clone the repository

git clone https://github.com/aneoconsulting/ArmoniK.Core.git
cd ArmoniK.Core

2.3. Step 3 — Build and deploy locally

This command builds all Docker images locally and deploys the full stack:

just local_images=true build-deploy

Default configuration: queue=activemq, object=redis, worker=htcmock, replicas=3, partitions=2.

The first run takes a few minutes (image builds + Terraform apply). Subsequent runs are faster.

What gets deployed? Submitter, PollingAgent × 3, HtcMock Worker × 3, ActiveMQ, Redis, MongoDB, Fluent Bit, Seq, Prometheus, and Grafana — all as local Docker containers.

2.4. Step 4 — Verify the deployment is healthy

just healthChecks

Expected output: startup: Healthy, liveness: Healthy, readiness: Healthy for each PollingAgent and the Submitter.

If any service reports Unhealthy, inspect the logs:

docker cp fluentd:/armonik-logs.json - | jq 'select(.["@l"] == "Error")'

Or open Seq at http://localhost:9080 and filter by level Error.

2.5. Step 5 — Run the unit tests

dotnet test Common/tests/

These tests run without any deployed service. All should pass in under a minute.

2.6. Step 6 — Run an integration test

With the deployment up, submit 100 HtcMock tasks to verify end-to-end processing:

just runHtcmock

You should see the client submit tasks and then collect results. A non-zero exit code indicates a failure.

To try with more tasks or different parameters:

just ntasks=500 htcmock_levels=1 runHtcmock

2.7. Step 7 — Explore the monitoring

UI

URL

Purpose

Seq

http://localhost:9080

Structured log search and filtering

Prometheus

http://localhost:9090

Raw metrics and alerts

Grafana

http://localhost:3000

Dashboards (admin / admin)

2.8. Tear down

just destroy

Important: call destroy with the same variable values you used for build-deploy. Terraform needs to match the original configuration to clean up correctly.

2.9. What’s next?