Quick Start

This guide gets you from a fresh checkout to a local NOOSChain development environment with dependencies installed, configuration in place, database migrations applied, core checks available, and the docs running.

It is intentionally local-development focused. It is not a production deployment guide.

Who This Is For

Use this page if you are:

• Evaluating NOOSChain for the first time.
• Setting up a local node for operator exploration.
• Preparing the repository for Nooschain development.
• Writing smart contracts and need enough local context to build, package, and test them.

If you already know your role, jump directly to Operators, Smart Contract Developers, or Nooschain Developers.

Prerequisites

Install these before starting:

• Node.js >=22.0.0
• npm
• PostgreSQL for node state, migrations, and database-backed tests
• Windows PowerShell, bash, or another shell capable of running npm scripts

Optional tooling:

• Docker Desktop or another Docker Engine, when using the containerized quick start
• Go, only when building or testing the HashiCorp Raft sidecar
• Rust/Cargo, only when building state-root sidecar or contract-runtime components under external/

The examples below use PowerShell.

Install Dependencies

From the repository root:

npm install

This installs the root TypeScript project, VitePress docs dependencies, TypeDoc, test tooling, and workspace packages referenced by the npm scripts.

Configure The Environment

Create a local .env file:

Copy-Item .env.example .env

For a basic local setup, check at least these values:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/nooschain
PORT=3000
NODE_ID=node-validator-1
NOOS_NODE_ROLE=validator
NOOS_CONSENSUS_MODE=single_node

Operator routes and CLI calls use NOOS_OPERATOR_TOKEN when protected operator access is enabled. In non-production development, the built-in development token is documented as dev-operator-token, but explicit local configuration is clearer:

NOOS_OPERATOR_TOKEN=dev-operator-token

Do not commit .env. Treat database URLs, private keys, operator tokens, and TLS key paths as local secrets.

Prepare The Database

Make sure PostgreSQL is running and the database named in DATABASE_URL exists. Then run migrations:

npm run migrate

Migrations prepare the local schema used by the node, CLI local checks, snapshots, replay, and database-backed tests.

Build And Typecheck

Compile the project:

npm run build

Run TypeScript without emitting build output:

npm run typecheck

For a quick local confidence check, typecheck is usually the cheaper command. Use build when you need the compiled dist/ output.

Start A Development Node

Start the TypeScript node in watch mode:

npm run dev

By default, local examples assume the API listens on http://127.0.0.1:3000. Keep this process running in one terminal, then use another terminal for CLI checks.

Alternative: Start With Docker

The Docker path packages the compiled node, operator CLI, SQL migrations, HashiCorp Raft, Nervos SMT, and Wasmtime in one non-root image. PostgreSQL runs as a separate Compose service. You do not need host installations of PostgreSQL, Go, or Rust for this path.

Confirm that Docker is running:

docker info

Build the image and start PostgreSQL, the one-shot migration job, and the local validator:

npm run docker:build
npm run docker:up

Check the validator with the CLI packaged inside the image:

docker compose -f docker/compose.local.yaml exec validator noos node health --json

Run the complete isolated verification when changing the Docker packaging:

npm run docker:smoke

The smoke test builds nooschain:local, starts a disposable Compose project, runs migrations, waits for validator health, verifies the CLI and the three native sidecars, initializes a temporary genesis, then signs and commits two transactions while checking the returned blocks and executed transaction records. It removes its temporary keys, containers, network, and volumes. The Dockerfile uses Rust 1.85 because the locked Wasmtime dependency graph requires stable Rust Edition 2024 support.

To verify two voting validators and ten replicated transactions:

npm run docker:test-two-validators

Add a non-voting observer to that test:

npm run docker:test-two-validators-one-observer

Stop the ordinary local stack without deleting its persistent volumes:

npm run docker:down

For custom validator and observer environment files, optional observer startup, ports, persistence, and production releases, continue with Docker Deployment.

Check The Operator CLI

Show top-level CLI help:

npm run noos -- --help

Run local environment and connectivity diagnostics:

npm run noos -- doctor

Check node health through the operator API:

npm run noos -- node health

If the node is not running yet, doctor can still report local configuration issues, but HTTP connectivity checks will fail until the development node is available.

Run Core Verification Commands

These commands are useful early confidence checks:

npm run verify:genesis
npm run verify:protocol
npm run verify:chain

Some verification commands depend on local database state and configuration. If a command fails, check .env, confirm PostgreSQL is running, and rerun migrations.

For broader regression coverage, use:

npm run test:ci

End-to-end, soak, stability, and benchmark commands can be heavier and may create significant local state. Read Command Taxonomy before running them against anything other than a disposable local database.

Run The Documentation Site

Run the documentation site locally:

npm run docs:dev

Build the docs and generated code reference:

npm run docs:build

Preview the built site over HTTP:

npm run docs:preview

Do not open docs/.vitepress/dist/index.html with file://. VitePress navigation, local search, and generated reference pages expect HTTP routing.

Optional: Admin GUI And Web GUI

The admin GUI is for operator-facing observability and guarded actions:

npm run admin:dev

The web GUI can be started separately:

npm run web:dev

Both GUI paths need API URL, CORS, and authentication configuration that matches your local node. See Admin GUI and the app-specific operator pages for details.

Optional: Smart Contract Path

Build the AssemblyScript contract SDK example:

npm run contracts:as-sdk:build

Useful next reads:

• Smart Contract Author Guide
• AssemblyScript SDK
• Publishing
• Packages And Provenance

Optional: Operator Path

After the local node and CLI work, operators should continue with:

• Operator CLI
• Recipes
• Production Readiness
• Monitoring And Alerting
• Backup, Restore, And Recovery

Do not treat this quick start as a production checklist. Production setup needs explicit identity, token, TLS/mTLS, database, backup, monitoring, consensus, and incident-response decisions.

Troubleshooting

Node is too old. Check node --version. NOOSChain requires Node.js >=22.0.0.

.env is missing. Copy .env.example to .env and review DATABASE_URL, PORT, NODE_ID, NOOS_NODE_ROLE, NOOS_CONSENSUS_MODE, and NOOS_OPERATOR_TOKEN.

Database commands fail. Confirm PostgreSQL is running, the database exists, DATABASE_URL is correct, and npm run migrate has completed.

CLI health checks fail. Start the node with npm run dev, confirm the configured PORT, and check NOOS_OPERATOR_TOKEN if operator auth is enabled.

Docs reference looks stale. Run npm run docs:api or npm run docs:build to regenerate docs/reference/code.

Windows command shims fail in constrained shells. Prefer the npm scripts from a normal terminal. In restricted automation environments, command shims may need to be invoked through the project's Node runtime.

Next Steps

• Understand the system: Overview, Data Buckets, Permission Model, Consensus Overview, and Node Roles.
• Write contracts: Smart Contract Developer Documentation.
• Run nodes: Operator Documentation.
• Change NOOSChain itself: Nooschain Developer Documentation.