Skip to content
Docs
Architecture

Architecture

Overview 

┌─────────────────────────────────────────────┐
│                     np CLI                    │
│    deploy · status · logs · scale · stop     │
└──────────┬──────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────┐
│                  Nomad Server                 │
│    scheduler · job state · rolling updates   │
└──────┬──────────────────┬───────────────────┘
       │                  │
       ▼                  ▼
┌─────────────┐   ┌─────────────┐
│ Nomad Client │   │ Nomad Client │   ...
│  (node 1)   │   │  (node 2)   │
│             │   │             │
│ ┌─────────┐ │   │ ┌─────────┐ │
│ │ alloc 1 │ │   │ │ alloc 3 │ │
│ │ alloc 2 │ │   │ │ alloc 4 │ │
│ └─────────┘ │   │ └─────────┘ │
└──────┬──────┘   └──────┬──────┘
       │                  │
       ▼                  ▼
┌─────────────────────────────────────────────┐
│                  Consul                       │
│    service registry · health checks · DNS    │
└─────────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────────┐
│                  Traefik                      │
│    ingress · routing · TLS · load balancing  │
└─────────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────────┐
│               OpenObserve                     │
│    logs · metrics · dashboards · alerts      │
└─────────────────────────────────────────────┘

Component Roles

Component Role Why this choice
Nomad Job scheduler Simple, single-binary, works with any workload
Consul Service discovery + health checks Battle-tested, DNS interface, no etcd needed
Traefik Reverse proxy + ingress Auto-discovery from Consul, automatic TLS, no config glue
OpenObserve Logs + metrics Single binary, replaces Elasticsearch + Grafana, 10x cheaper

How deployment works 

np deploy my-app
  │
  ├─→  Read np.yaml → generate Nomad job spec
  │
  ├─→  Submit job to Nomad (PUT /v1/jobs)
  │
  ├─→  Nomad schedules allocations to clients
  │
  ├─→  Wait for all allocations → "running"
  │
  ├─→  Health check: GET {health_check}
  │         ✅ 200 OK → done
  │         ❌ Error → report + wait

Node requirements

Component Min RAM Min CPU Notes
Nomad Server 256 MB 0.5 core Raft quorum needs 3 servers
Nomad Client 128 MB + workloads 0.5 core + workloads
Consul 128 MB 0.25 core Shared with Nomad Server
Traefik 64 MB 0.25 core Edge nodes only
OpenObserve 256 MB 1 core Single instance for SME scale

Next: FAQ →

CommandsFAQ