Running the CLI in Docker

The CLI is published as a public image, so an installation can be checked from any machine with Docker and no Python of its own. It is the same bruce command described in Getting started, as the image's entrypoint.

docker pull nextspace/bruce-cli:latest

docker run --rm nextspace/bruce-cli --help

latest follows the newest release. Every release is also tagged with the library version it contains, which is what to pin in CI so a run is repeatable.

docker run --rm nextspace/bruce-cli:0.1.59 --version

Giving it credentials

The image holds no configuration, so settings come in per run. An env file is the usual way, and it keeps the token off the command line and out of the shell history.

NXT_ENV=UAT
NXT_ACCOUNT=your-account
NXT_TOKEN=YOUR_ACCESS_TOKEN

Pass it with --env-file. Note this is Docker's own flag reading the file into the container's environment, which is not the same as the CLI's --env-file option, though the file format is the same.

docker run --rm --env-file ./uat.env nextspace/bruce-cli status

Individual variables work too, for a CI runner that already holds them as secrets.

docker run --rm \
    -e NXT_ENV=UAT \
    -e NXT_ACCOUNT=your-account \
    -e NXT_TOKEN="$NXT_TOKEN" \
    nextspace/bruce-cli status --json

Running the core tests

This is the check worth wiring into a pipeline: run the core suite against a Hosting Location, which builds a temporary Account, exercises the journeys and removes it afterwards. It proves the installation works rather than proving one account's data does.

docker run --rm --env-file ./uat.env \
    nextspace/bruce-cli test core -hl your-location-key

Against a specific Account instead, which tests in the data that is already there:

docker run --rm --env-file ./uat.env \
    nextspace/bruce-cli test core -a your-account

core is the tag covering the CSV, BRZ, GeoJSON and historic/Scenario journeys. Swap it for all to include the assembly alignment and scale tests, or for a number, list or range to run one thing. bruce test on its own lists what a credential can run.

The command exits non-zero when a test fails, so a pipeline step needs nothing else to gate on it.

Things worth knowing

The container runs as a non-root user (UID 10001) with its home at /home/bruce. Nothing is written outside it, and --rm means a run leaves nothing behind at all.

Nothing is stored between runs. There is no bruce login to do first, because the container is gone afterwards. Mount a config directory at /home/bruce/.config if you want a login to persist across runs.

A private installation needs its urls. The environment name only implies a host for Nextspace-hosted environments. Set NXT_GUARDIAN_URL, and NXT_BASE_URL if the Account lookup should be skipped, otherwise the lookup goes to the public Guardian and resolves nothing.

Test data is real data. The tests create Entity Types, files and Entities in whatever they are pointed at, and clean up after themselves. Point them at a Hosting Location or a test Account rather than at production.