Nex CE Deployment

This page covers how to configure and deploy a Nex CE node as a container. For an overview of what Nex CE is, see Nex CE.

Nex CE is published as a container image whose entrypoint is the nex-ce binary, so any argument you pass after the image name is passed straight to nex-ce. A node is started with the node up command:

docker run --rm \
  -v "$(pwd)/config.json:/etc/nex-ce/config.json:ro" \
  -v "$(pwd)/ngs.creds:/etc/nex-ce/ngs.creds:ro" \
  registry.synadia.io/nexce:latest \
  node up

The same pattern works with podman run.

Configuration

A Nex node is configured through a JSON config file, CLI flags appended after the image name, or a mix of both. CLI flags take precedence over the config file.

The container looks for its config file at /etc/nex-ce/config.json by default, so the simplest setup is to mount your config to that path (as in the example above). To use a different in-container path, mount it wherever you like and point at it with --config:

docker run --rm \
  -v "$(pwd)/config.json:/config.json:ro" \
  registry.synadia.io/nexce:latest \
  node up --config /config.json

Make sure you change node_seed to your own unique seed.

Example config file

{
  "namespace": "system",

  "logger": {
    "level": "info"
  },

  "nats": {
    "servers": ["nats://connect.ngs.global"],
    "creds_file": "/etc/nex-ce/ngs.creds"
  },

  "name": "nexnode",
  "nexus": "nexus",
  "node_seed": "SNAKXRJB...",
  "creds_signing_key": "SAANZQ3BU6Y...",
  "control_account": "ADH253XRZ...",

  "nexlets": {
    "native": {
      "enabled": true,
      "registerType": "native"
    },
    "containers-podman": {
      "enabled": true,
      "registerType": "container",
      "podmanUser": "user"
    }
  }
}

When using platform (Control Plane) registration, omit nexus and control_account. They are populated automatically from the platform response:

{
  "nats": { "...": "<see above>" },
  "name": "nexnode",
  "node_seed": "SNAKXRJB...",
  "nexlets": { "...": "<see above>" },
  "logger": { "...": "<see above>" },
  "platform": {
    "enabled": true,
    "url": "<sc_api_url>",
    "token": "<some_token>"
  }
}

Global Options

Logger Options

All logger options use the --logger.* flag prefix (or the "logger": {} object in config).

NATS Options

All NATS options use the --nats.* flag prefix (or the "nats": {} object in config).

Node Options

These options apply to the node up command (appended after the image name). --node-seed is required (typically supplied via the config file).

The creds_signing_key (config) / --creds-signing-key (CLI) is a "Programmatic Key" generated under Users > Group in Control Plane. The control_account (config) / --control-account (CLI) is the account public key shown on the Control Plane overview page.

Platform Options

When --platform.enabled is true, --nexus and --control-account must be omitted. They are populated automatically from the platform response.

To get a platform component token, enable the Workloads platform component in Control Plane's system settings. Click Enable Workloads, click Submit to save the updated settings, then click Component Token to get the token.

Catalog Options

When enabled, the node starts a Synadia Catalog service over NATS micro. The catalog uses the node's NATS connection and shuts down with the node.

To get a platform component token, enable the Catalog platform component in Control Plane's system settings. Click Enable Catalog, enter the NUID of the catalog, click Submit to save the updated settings, then click Component Token to get the token.

Nexlet Options

Nexlets are the pluggable runtimes that execute workloads (native, Podman). They are configured exclusively via the "nexlets" object in the JSON config file. They cannot be set with CLI flags.

Map keys are the nexlet names (see Valid nexlets); field keys use camelCase matching the Go field names.

Note: Podman nexlets require a socket running for the configured user. Use podmanUser to specify the user, or podmanSocketPath to point directly to a socket.

Valid nexlets

The nexlets available depend on the build tags compiled into the binary:

• native
• containers-podman
• connectors-podman

You can see which nexlets are compiled into the image in the --version output:

$ docker run --rm registry.synadia.io/nexce:latest --version
0.0.0 [unknown] | Built: unknown
Nexlets: connectors-podman, containers-podman, native

Running a node

Each of the following appends a nex-ce command after the image name. Define a shell alias to keep the examples short:

alias nex-ce='docker run --rm \
  -v "$(pwd)/config.json:/etc/nex-ce/config.json:ro" \
  -v "$(pwd)/ngs.creds:/etc/nex-ce/ngs.creds:ro" \
  registry.synadia.io/nexce:latest'

# Start a node (config mounted at the default /etc/nex-ce/config.json)
nex-ce node up

# List running nodes
nex-ce node list

# List running nodes in a specific nexus
nex-ce node list --filter nex.nexus=mynexus

# Show detailed info about a node, including running agents
nex-ce node info NBTAFHAKW...

# Put a node into lame duck mode (workloads drain, then stop)
nex-ce node lameduck --delay 2m NBTAFHAKW...

A long-running node (node up) is usually run with docker run -d (detached) or under an orchestrator rather than the interactive --rm form shown here. The read-only client commands (node list, node info, etc.) connect to NATS and exit, so the --rm form is fine for those.

Exit codes