Skip to content
NKZ OS NKZ OS

Quickstart

NKZ OS runs on any machine with Docker. The local compose stack gives you a full FIWARE Context Broker, Keycloak SSO, PostgreSQL/TimescaleDB, and the frontend host — enough to create your first NGSI-LD entity and explore the UI.

Prerequisites

Section titled “Prerequisites”
  • Docker Engine 24+ and Docker Compose v2
  • 4 GB RAM available, 10 GB free disk
  • Node.js 22+ and pnpm (for building the frontend)

Start the platform

Section titled “Start the platform”
Terminal window
# Clone the monorepo
git clone https://github.com/nkz-os/nkz
cd nkz


# Start core services (Orion-LD, Keycloak, PostgreSQL, MongoDB, Redis, MinIO)
docker compose up -d


# Install frontend dependencies and build internal packages
pnpm install --frozen-lockfile
pnpm --filter @nekazari/design-tokens build
pnpm --filter @nekazari/ui-kit build
pnpm --filter @nekazari/viewer-kit build
pnpm --filter @nekazari/sdk build
pnpm --filter @nekazari/module-kit build


# Start the frontend host in dev mode
cd apps/host && pnpm dev

Open http://localhost:5173. Keycloak admin at http://localhost:8080/auth/admin (user: admin, password: admin).

First NGSI-LD entity

Section titled “First NGSI-LD entity”
Terminal window
curl -X POST http://localhost:1026/ngsi-ld/v1/entities \
  -H "Content-Type: application/ld+json" \
  -H "Link: <http://localhost:5000/ngsi-ld-context.json>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"" \
  -d '{
    "id": "urn:ngsi-ld:AgriParcel:test-1",
    "type": "AgriParcel",
    "location": {
      "type": "GeoProperty",
      "value": { "type": "Point", "coordinates": [-1.64, 42.81] }
    },
    "name": { "type": "Property", "value": "Test Parcel" }
  }'

Next steps

Section titled “Next steps”

Troubleshooting

Section titled “Troubleshooting”

Port conflicts: Stop any local PostgreSQL (5432), MongoDB (27017), or Redis (6379).

Login loop: Clear browser cookies for localhost. Keycloak needs the nekazari-frontend client configured with valid redirect URIs.

Frontend blank: Run pnpm --filter @nekazari/design-tokens build first — the host needs the design token CSS custom properties at build time.