Scripts Overview

NoKV now groups shell entrypoints by role instead of keeping every helper flat under scripts/.

Layout

This split is deliberate:

• dev scripts are allowed to help with local experiments and smoke tests.
• ops scripts must treat the migration CLI as source of truth and stay stricter.
• lib is where shared rules live, so shell semantics do not drift across scripts.

Bootstrap & Local Launch

scripts/dev/cluster.sh

• Purpose: build nokv and nokv-config, start the canonical 333 separated dev cluster, seed fresh store workdirs, then start stores from raft_config.json.
• Starts:
  • three nokv meta-root processes (Truth plane; replicated is the only mode)
  • one nokv coordinator process (Service plane; always remote-rooted)
  • all configured stores (Execution plane)
• Uses shared rules from:
  • scripts/lib/common.sh
  • scripts/lib/config.sh
  • scripts/lib/workdir.sh
• Example:

  ./scripts/dev/cluster.sh --config ./raft_config.example.json --workdir ./artifacts/cluster
  

• Notes:
  • --config defaults to ./raft_config.example.json
  • --workdir defaults to ./artifacts/cluster
  • uses fixed local metadata-root gRPC endpoints 127.0.0.1:2380/2381/2382
  • uses fixed local metadata-root raft transport endpoints 127.0.0.1:3380/3381/3382
  • store workdirs are rejected if they contain unexpected files
  • logs stream with [meta-root-<id>] / [coordinator] / [store-<id>] prefixes and are still written to root.log / coordinator.log / server.log
  • this is a bootstrap/dev launcher, not a restart command
  • production-style restarts should run scripts/ops/serve-meta-root.sh, scripts/ops/serve-coordinator.sh, and scripts/ops/serve-store.sh directly against the same durable workdirs

scripts/ops/bootstrap.sh

• Purpose: seed local peer catalog metadata into a set of store directories derived from a path template.
• Intended for:
  • Docker Compose bootstrap
  • local static-topology experiments
• Example:

  ./scripts/ops/bootstrap.sh --config /etc/nokv/raft_config.json --path-template /data/store-{id}
  

• Notes:
  • skips stores that already contain CURRENT
  • refuses to seed into dirty directories
  • this is bootstrap-only; it does not recover runtime topology
  • use nokv serve / scripts/ops/serve-store.sh to restart an existing store from the same workdir

scripts/ops/serve-store.sh

• Purpose: thin wrapper around nokv serve for one store.
• Example:

  ./scripts/ops/serve-store.sh \
    --config ./raft_config.example.json \
    --store-id 1 \
    --workdir ./artifacts/cluster/store-1 \
    --scope local
  

• Notes:
  • resolves store listen/workdir/Coordinator defaults through nokv serve --config
  • remote peer recovery comes from raftstore/localmeta; config stores only provide storeID -> addr
  • no longer treats config.regions as restart-time topology truth
  • if a static transport override is needed, use --store-addr <store-id>=<addr> rather than a peer-id keyed mapping
  • --scope docker selects container-friendly addresses

scripts/ops/serve-meta-root.sh

• Purpose: thin wrapper around nokv meta-root for one replicated metadata-root peer.
• Example:

  ./scripts/ops/serve-meta-root.sh \
    --addr 127.0.0.1:2380 \
    --workdir ./artifacts/cluster/meta-root-1 \
    --node-id 1 \
    --transport-addr 127.0.0.1:3380 \
    --peer 1=127.0.0.1:3380 \
    --peer 2=127.0.0.1:3381 \
    --peer 3=127.0.0.1:3382
  

• Notes:
  • --peer values are metadata-root raft transport addresses, not gRPC service addresses
  • --workdir, --node-id, --transport-addr, and exactly 3 --peer values are required; there is no single-process local mode
  • forwards shutdown signals to nokv meta-root

scripts/ops/serve-coordinator.sh

• Purpose: thin wrapper around nokv coordinator for one coordinator process wired to an external 3-peer meta-root cluster.
• Example:

  ./scripts/ops/serve-coordinator.sh \
    --addr 127.0.0.1:2379 \
    --coordinator-id c1 \
    --root-peer 1=127.0.0.1:2380 \
    --root-peer 2=127.0.0.1:2381 \
    --root-peer 3=127.0.0.1:2382
  

• Notes:
  • --root-peer values are metadata-root gRPC service addresses, not raft transport
  • exactly 3 --root-peer values are required (mirrors the Truth-plane quorum)
  • --coordinator-id is required (stable lease owner id)
  • forwards shutdown signals to nokv coordinator

Migration Workflow

scripts/ops/migrate-cluster.sh

• Purpose: one-shot local operator wrapper for the standalone-to-cluster migration path.
• Drives:
  • nokv migrate plan
  • nokv migrate init
  • nokv migrate expand
  • optional transfer-leader
  • optional remove-peer
• Example:

  ./scripts/ops/migrate-cluster.sh \
    --config ./raft_config.example.json \
    --workdir ./artifacts/standalone \
    --seed-store 1 \
    --seed-region 1 \
    --seed-peer 101 \
    --target 2:201 \
    --target 3:301 \
    --transfer-leader 201 \
    --remove-peer 101
  

• Notes:
  • seed workdir must already contain standalone data
  • target store workdirs must be fresh
  • uses the migration CLI as the only source of truth

Shared Shell Rules

scripts/lib/common.sh

• shared repo-root detection
• shared build helpers for nokv and nokv-config
• shared TCP readiness helper

scripts/lib/config.sh

• shared nokv-config lookups for:
  • store lines
  • region lines
  • Coordinator address
  • Coordinator workdir

scripts/lib/workdir.sh

• shared workdir hygiene rules:
  • remove stale LOCK
  • reject unexpected directory contents
  • assert a directory is fresh before seeding or bootstrap

This is where shell-level correctness rules should keep living. New scripts should reuse these helpers instead of open-coding workdir or config parsing logic again.

Tooling & Benchmarks

For recovery and transport fault validation, use direct Go tests instead of shell wrappers:

RECOVERY_TRACE_METRICS=1 \
go test ./... -run 'TestRecovery(RemovesStaleValueLogSegment|FailsOnMissingSST|FailsOnCorruptSST|ManifestRewriteCrash|SlowFollowerSnapshotBacklog|SnapshotExportRoundTrip|WALReplayRestoresData)' -count=1 -v

CHAOS_TRACE_METRICS=1 \
go test -run 'TestGRPCTransport(HandlesPartition|MetricsWatchdog|MetricsBlockedPeers)' -count=1 -v ./raftstore/transport

Relationship with nokv-config

• nokv-config stores / regions / coordinator remain the structured topology source for shell scripts.
• config.regions remain bootstrap/deployment metadata, not restart-time peer truth.
• nokv-config catalog writes Region metadata into the local peer catalog.
• Go tools can import github.com/feichai0017/NoKV/config and call config.LoadFile / Validate directly.

Maintaining a single raft_config.json still keeps development scripts, Docker Compose, and automated tests aligned. The difference now is that shell behavior is shared and explicit instead of repeated across four separate entrypoints.