Installation

NeuroSim Core ships as a single self-contained binary (ns-core) with the web UI embedded. There is no separate web server or UI deployment step.

Obtaining NeuroSim Core

NeuroSim Core is available as a Linux RPM and as an OCI-compliant container image. Both have the same functionality; the choice of which to use depends on the customer site's capabilities, policies, and preferences.

Github access to NeuroSim's organization is required to obtain either artifact. Contact NeuroSim Sales for access.

License File

NeuroSim Core requires a valid license file to start. The license is a signed JWT file (typically named neurosim-license.jwt). Core reads this file at startup and re-validates it every hour. If the license is absent, expired, or tampered with, Core will refuse to start (or will shut down at the next validation cycle).

Place the license file somewhere stable on the host filesystem and set license_file_path in your configuration file (or the LICENSE_FILE_PATH environment variable) to its absolute path.

NeuroSim sales support issues all NeuroSim Core licenses and will email your license file.

Running as a Binary

System Requirements

TODO: Document minimum OS and CPU/memory requirements. Core is a Go binary compiled for Linux (CGO_ENABLED=0). Document:

• Supported operating systems and architectures (x86-64, arm64?)
• Minimum recommended RAM and CPU, especially under load with many active scenarios
• Disk requirements (schemas directory, log storage if applicable)

Starting Core

./ns-core --config=/etc/neurosim/core.yaml

If --config is omitted, Core starts with built-in defaults and environment variable overrides only (useful for containerized deployments where config is injected via environment).

Core logs to standard output. On a successful start you should see:

[Core] Starting NeuroSim Core version <version> with configuration: ...
[Core] Web UI enabled at /
[store] PostgreSQL connected and migrations applied

If the license file is missing or invalid, startup will fail with a license error before the HTTP server binds.

Running as a systemd Service

For production Linux deployments, run Core as a systemd service so it restarts on failure and starts on boot.

Create /etc/systemd/system/neurosim-core.service:

[Unit]
Description=NeuroSim Core
After=network.target

[Service]
Type=simple
User=neurosim
ExecStart=/opt/neurosim/ns-core --config=/etc/neurosim/core.yaml
Restart=on-failure
RestartSec=5s
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Then enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable neurosim-core
sudo systemctl start neurosim-core
sudo journalctl -u neurosim-core -f   # follow logs

TODO: Confirm the recommended install path and whether a dedicated system user should be created. Document any required filesystem permissions (the ns-core binary, the schemas/ directory, and the license file must all be readable by the service user).

Running as a Docker Container

The official NeuroSim Core container image is based on Alpine Linux and runs as a non-root user (ns). Port 8080 is exposed for the REST API and embedded web UI.

Basic Run

docker run -d \
  --name neurosim-core \
  -p 8080:8080 \
  -v /path/to/core.yaml:/etc/neurosim/core.yaml:ro \
  -v /path/to/neurosim-license.jwt:/etc/neurosim/license.jwt:ro \
  neurosim/core:latest \
  --config=/etc/neurosim/core.yaml

TODO: Confirm the container image name and registry (Docker Hub, GHCR, private registry?). Document versioning/tagging conventions (:latest, :1.2.3, etc.).

Configuration via Environment Variables

All configuration values can be supplied as environment variables instead of a config file. The mapping replaces dots with underscores:

docker run -d \
  --name neurosim-core \
  -p 8080:8080 \
  -v /path/to/license.jwt:/license.jwt:ro \
  -e HTTP_PORT=8080 \
  -e KAFKA_BROKERS=kafka:9092 \
  -e KAFKA_REGISTER_TOPIC=neurosim-plugins \
  -e KAFKA_EVENT_TOPIC=neurosim-events \
  -e STORE_TYPE=postgresql \
  -e POSTGRESQL_DSN="postgres://neurosim:changeme@postgres:5432/neurosim" \
  -e LICENSE_FILE_PATH=/license.jwt \
  neurosim/core:latest

Docker Compose (Development)

A complete development stack including Kafka and PostgreSQL:

services:
  zookeeper:
    image: confluentinc/cp-zookeeper:7.5.0
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000

  kafka:
    image: confluentinc/cp-kafka:7.5.0
    depends_on: [zookeeper]
    ports:
      - "9092:9092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:29092,PLAINTEXT_HOST://localhost:9092
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:29092,PLAINTEXT_HOST://0.0.0.0:9092
      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1

  postgres:
    image: postgres:16
    environment:
      POSTGRES_USER: neurosim
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: neurosim
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  neurosim-core:
    image: neurosim/core:latest
    depends_on: [kafka, postgres]
    ports:
      - "8080:8080"
    volumes:
      - ./license.jwt:/license.jwt:ro
    environment:
      KAFKA_BROKERS: kafka:29092
      STORE_TYPE: postgresql
      POSTGRESQL_DSN: postgres://neurosim:changeme@postgres:5432/neurosim
      LICENSE_FILE_PATH: /license.jwt

volumes:
  postgres_data:

Verifying the Installation

Once Core is running, confirm it is healthy:

curl http://localhost:8080/health

A successful response looks like:

{"status": "ok"}

The web UI is accessible at http://localhost:8080 (using the default HTTP port and if http.serve_ui is not disabled).