Installation

This page builds Stellar Control from source and starts everything needed to operate simulated targets on one machine: a NATS server with JetStream, the services of the core, two simulated targets and the web console. Your First Procedure then walks through using them.

Prerequisites#

Build#

From the root of the repository:

cargo build --release

The binaries land in target/release/:

The example drivers, transports and gateways (platform-v3-ccsds, ccsds-tc, obc-csp, csp1-kiss, bench-can…) are built too; see Extending Stellar Control.

To install the CLI and the language server in ~/.cargo/bin:

cargo install --path tooling/cli
cargo install --path tooling/lsp

A NATS server#

Stellar Control needs NATS 2.12 with JetStream enabled. Two options.

Plain server, no authentication#

The simplest, for a first trial:

docker run -d --name nats -p 4222:4222 docker.io/library/nats:2.12.15-alpine -js

Every component connects to nats://localhost:4222 by default.

Development server with decentralized authentication#

The repository ships a development setup close to production: an operator, an account stellar, users with restricted permissions and TLS material, all generated locally by nsc.

dev/nats/setup.sh               # once: identities in dev/nats/secrets/ (git-ignored)
docker compose up -d nats       # or: podman compose up -d nats
dev/nats/smoke-test.sh          # checks JetStream and permissions (needs the nats CLI)

setup.sh writes:

Point a component at the server with its credentials:

export STELLAR__NATS__CREDENTIALS=dev/nats/secrets/creds/dev.creds

To require TLS, start the server with the TLS configuration:

NATS_CONF=nats-server-tls.conf docker compose up -d nats

After setup.sh --force, restart the server so that it loads the new operator. The compose file also defines a timescaledb service, the database of the reference output connector (see Output Connectors).

The security model behind these files is described in NATS Accounts and Credentials.

The services of the core#

Every service reads the same global configuration file (--config or STELLAR_CONFIG); without one, the defaults of Global Configuration apply, which target nats://localhost:4222 and serve the API on 0.0.0.0:8080.

All in one process#

stellar-mcs runs the reconciler, the compute stage, the executor, the API, the alarm service, the scheduler and the transfer manager in one process, plus the editor when editor.repository is set:

stellar-mcs --config stellar.yaml

It uses about a quarter of the memory of the separate services, and each service behaves as if it ran alone. For production layouts, see Running the Services.

One process per service#

Each service has its own binary with the same command line (--config, --instance). On one host, give each its own metrics port:

STELLAR__OBSERVABILITY__METRICS_ADDR=127.0.0.1:9101 stellar-reconciler &
STELLAR__OBSERVABILITY__METRICS_ADDR=127.0.0.1:9102 stellar-compute &
STELLAR__OBSERVABILITY__METRICS_ADDR=127.0.0.1:9103 stellar-executor &
STELLAR__OBSERVABILITY__METRICS_ADDR=127.0.0.1:9104 stellar-api &

Publish a configuration#

The services work on the compiled snapshot of a configuration repository. Compile the example repository and make it the current configuration:

stellar compile examples/config --publish nats://localhost:4222

The command prints the hash of the snapshot and also writes it to <hash>.ir in the current directory (--output chooses the file). With an authenticated server, add --nats-credentials dev/nats/secrets/creds/dev.creds. See Compilation, Snapshots and Locks.

Simulated targets#

The example topology declares two simulated targets, sim-1 (a platform-v3 satellite) and psu-sim-1 (a laboratory power supply). Each is played by a stellar-simulator process that registers as their driver and gateway:

stellar-simulator --repository examples/config --simulation platform-v3-sim \
    --target sim-1 --gateway sim-gw-1 &
stellar-simulator --repository examples/config --simulation lab-psu-sim \
    --target psu-sim-1 --gateway psu-sim-gw-1 &

Within seconds the reconciler binds them and the targets become ready. Check with:

curl -s http://localhost:8080/v1/topology

The web console#

The web console is a Svelte application in core/frontend, served by the API when api.web_dir points at its build:

cd core/frontend
npm ci
npm run build          # writes core/frontend/dist

# stellar.yaml
api:
  listen: 0.0.0.0:8080
  web_dir: core/frontend/dist

Start stellar-mcs --config stellar.yaml (or stellar-api) and open http://localhost:8080/. Every path under /v1/ stays the API; any other path serves the application. See Web Console.

A complete local demonstration#

The whole flow, on a plain NATS server:

docker run -d --name nats -p 4222:4222 docker.io/library/nats:2.12.15-alpine -js
cargo build --release
export PATH="$PWD/target/release:$PATH"

stellar compile examples/config --publish nats://localhost:4222
cat > stellar.yaml <<'YAML'
api:
  web_dir: core/frontend/dist
passes:
  feeders: {fds-feeder: fds, station-feeder: provider}
observability:
  log_format: text
YAML
stellar-mcs --config stellar.yaml &

stellar-simulator --repository examples/config --simulation platform-v3-sim \
    --target sim-1 --gateway sim-gw-1 &
stellar-simulator --repository examples/config --simulation lab-psu-sim \
    --target psu-sim-1 --gateway psu-sim-gw-1 &

stellar send sim-1 'tcu[TCU1].ping'

Stop the processes with Ctrl-C (SIGINT) or SIGTERM: every component shuts down cleanly.

Next steps#

• Your First Procedure: the tutorial on these simulated targets.
• Global Configuration: every configuration key.
• Nomad: the whole stack on a Nomad agent.