Engine Installation & Setup Quickstart

This quickstart guide walks system administrators through installing, setting up, and running the Niksphere Engine connected to a database (such as PostgreSQL or embedded SQLite).

Prerequisites

The Niksphere Engine supports two database storage backends: an external PostgreSQL database (recommended for enterprise production deployments) or an embedded SQLite database (ideal for local testing and zero-configuration setups). For architectural details on multi-database isolation and layer merging, see Engine Database Architecture.

Before starting, ensure you have:

• For PostgreSQL: A running PostgreSQL instance (locally or via Docker on port 5432).
• For SQLite: No external database setup required (SQLite is embedded directly inside the Niksphere Engine).

TIP

If using PostgreSQL with Docker for testing:

docker run --name niksphere-postgres -e POSTGRES_DB=nikspheredb -e POSTGRES_USER=niksphere -e POSTGRES_PASSWORD=secret -p 5432:5432 -d postgres:16

Step 1: Install Niksphere Engine

The Niksphere Engine supports two primary deployment models: Self-Hosted (available as a Docker Container or Standalone Executable native binary / .exe) and Niksphere Cloud (Fully Managed). For a detailed comparison of these models, see Engine Deployment Architecture.

For this quickstart, choose either Option A: Standalone Executable Download or Option B: Docker Container Image below:

Option A: Standalone Executable Download

1. Go to the official Niksphere download portal:
   👉 Niksphere Downloads & Installation

2. Download the appropriate package archive for your platform (Windows .exe, Linux, or macOS).

3. Extract the downloaded archive into your desired directory (e.g., C:\NiksphereEngine\ or /opt/niksphere/).

Option B: Docker Container Image

1. Pull the official Niksphere Engine image from GitHub Container Registry (ghcr.io):

   docker pull ghcr.io/niksphere/niksphere-engine:latest

Step 2: Setup Niksphere Engine

The Niksphere Engine supports flexible configuration management and can be configured either via environment variables (NIKSPHERE_ENGINE_*) or through configuration files (config.json, config.yaml, or config.toml). For a complete list of all parameters, see the Engine Configuration Reference.

For this quickstart, configure your environment variables below:

Option 1: PostgreSQL Setup

$env:NIKSPHERE_ENGINE_DB_DRIVER="postgres"
$env:NIKSPHERE_ENGINE_DB_HOST="localhost"
$env:NIKSPHERE_ENGINE_DB_PORT="5432"
$env:NIKSPHERE_ENGINE_DB_USERNAME="niksphere"
$env:NIKSPHERE_ENGINE_DB_PASSWORD="secret"
$env:NIKSPHERE_ENGINE_DB_NAME="nikspheredb"
$env:NIKSPHERE_ENGINE_HTTP_PORT="3000"

export NIKSPHERE_ENGINE_DB_DRIVER="postgres"
export NIKSPHERE_ENGINE_DB_HOST="localhost"
export NIKSPHERE_ENGINE_DB_PORT="5432"
export NIKSPHERE_ENGINE_DB_USERNAME="niksphere"
export NIKSPHERE_ENGINE_DB_PASSWORD="secret"
export NIKSPHERE_ENGINE_DB_NAME="nikspheredb"
export NIKSPHERE_ENGINE_HTTP_PORT="3000"

export NIKSPHERE_ENGINE_DB_DRIVER="postgres"
export NIKSPHERE_ENGINE_DB_HOST="localhost"
export NIKSPHERE_ENGINE_DB_PORT="5432"
export NIKSPHERE_ENGINE_DB_USERNAME="niksphere"
export NIKSPHERE_ENGINE_DB_PASSWORD="secret"
export NIKSPHERE_ENGINE_DB_NAME="nikspheredb"
export NIKSPHERE_ENGINE_HTTP_PORT="3000"

Option 2: Embedded SQLite Setup (Default)

$env:NIKSPHERE_ENGINE_DB_DRIVER="sqlite"
$env:NIKSPHERE_ENGINE_HTTP_PORT="3000"

export NIKSPHERE_ENGINE_DB_DRIVER="sqlite"
export NIKSPHERE_ENGINE_HTTP_PORT="3000"

export NIKSPHERE_ENGINE_DB_DRIVER="sqlite"
export NIKSPHERE_ENGINE_HTTP_PORT="3000"

Step 3: Run Niksphere Engine

The Niksphere Engine can be executed directly via the command line, run as a background Docker container, or registered to run as a native system service (Windows Service / systemd). For native service setup, see Engine Service Management.

For this quickstart, execute the standalone binary or launch the Docker container below:

Running Standalone Executable

.\niksphere-engine.exe

./niksphere-engine

./niksphere-engine

Running Docker Container

docker run -d `
  --name niksphere-engine `
  -p 3000:3000 `
  -e NIKSPHERE_ENGINE_DB_DRIVER=postgres `
  -e NIKSPHERE_ENGINE_DB_HOST=host.docker.internal `
  -e NIKSPHERE_ENGINE_DB_PORT=5432 `
  -e NIKSPHERE_ENGINE_DB_USERNAME=niksphere `
  -e NIKSPHERE_ENGINE_DB_PASSWORD=secret `
  -e NIKSPHERE_ENGINE_DB_NAME=nikspheredb `
  ghcr.io/niksphere/niksphere-engine:latest

docker run -d \
  --name niksphere-engine \
  -p 3000:3000 \
  -e NIKSPHERE_ENGINE_DB_DRIVER=postgres \
  -e NIKSPHERE_ENGINE_DB_HOST=host.docker.internal \
  -e NIKSPHERE_ENGINE_DB_PORT=5432 \
  -e NIKSPHERE_ENGINE_DB_USERNAME=niksphere \
  -e NIKSPHERE_ENGINE_DB_PASSWORD=secret \
  -e NIKSPHERE_ENGINE_DB_NAME=nikspheredb \
  ghcr.io/niksphere/niksphere-engine:latest

docker run -d \
  --name niksphere-engine \
  -p 3000:3000 \
  -e NIKSPHERE_ENGINE_DB_DRIVER=postgres \
  -e NIKSPHERE_ENGINE_DB_HOST=host.docker.internal \
  -e NIKSPHERE_ENGINE_DB_PORT=5432 \
  -e NIKSPHERE_ENGINE_DB_USERNAME=niksphere \
  -e NIKSPHERE_ENGINE_DB_PASSWORD=secret \
  -e NIKSPHERE_ENGINE_DB_NAME=nikspheredb \
  ghcr.io/niksphere/niksphere-engine:latest

Verification

Upon startup, the Engine automatically connects to the database, initializes system layers, and binds to port :3000.

Verify that the Engine is running cleanly via the HTTP Health Endpoint:

curl http://localhost:3000/health

Expected Response:

{
  "status": "UP",
  "database": "connected",
  "version": "1.0.0"
}

Next Steps

• Architecture & Storage: Learn more about the Engine Database Architecture and Engine Deployment Models.
• Configuration: See the full Engine Configuration Reference.