NATS Service Configuration

Introduction

The nats service is the event broker of the system. It distributes events among all other services and enables other services to communicate asynchronously.

Services can Publish events to the nats service and nats will store these events on disk and distribute these events to other services eventually.

Services can Consume events from the nats service by registering to a ConsumerGroup. Each ConsumerGroup is guaranteed to get each event exactly once. In most cases, each service will register its own ConsumerGroup. When there are multiple instances of a service, those instances will usually use that ConsumerGroup as a common resource.

Default Values

  • Thumbnails listens on port 9230 by default.

  • The default location storing events is $OCIS_BASE_DATA_PATH:/nuts

Underlying Technology

As the service name suggests, this service is based on NATS specifically on NATS Jetstream to enable persistence.

Persistence

To be able to deliver events even after a system or service restart, nats will store events in a folder on the local filesystem. This folder can be specified by setting the NATS_NATS_STORE_DIR environment variable. If not set, the service will fall back to $OCIS_BASE_DATA_PATH:/nats.

TLS Encryption

Connections to the nats service (Publisher/Consumer see above) can be TLS encrypted by setting the corresponding env vars NATS_TLS_CERT, NATS_TLS_KEY to the cert and key files and ENABLE_TLS to true. Checking the certificate of an incoming request can be disabled with the NATS_EVENTS_ENABLE_TLS environment variable.

Certificate files can also be set via global variables starting with OCIS_, for details see the environment variable list.

Note that using TLS is highly recommended for production environments, especially when using container orchestration with Kubernetes.

Configuration

Environment Variables

The nats extension is configured via the following environment variables:

  • latest

  • 2.0.0

Environment variables for the nats service
Name Type Default Value Description

OCIS_LOG_LEVEL
NATS_LOG_LEVEL

string

The log level. Valid values are: "panic", "fatal", "error", "warn", "info", "debug", "trace".

OCIS_LOG_PRETTY
NATS_LOG_PRETTY

bool

false

Activates pretty log output.

OCIS_LOG_COLOR
NATS_LOG_COLOR

bool

false

Activates colorized log output.

OCIS_LOG_FILE
NATS_LOG_FILE

string

The path to the log file. Activates logging to this file if set.

NATS_DEBUG_ADDR

string

127.0.0.1:9234

Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.

NATS_DEBUG_TOKEN

string

Token to secure the metrics endpoint.

NATS_DEBUG_PPROF

bool

false

Enables pprof, which can be used for profiling.

NATS_DEBUG_ZPAGES

bool

false

Enables zpages, which can be used for collecting and viewing in-memory traces.

NATS_NATS_HOST

string

127.0.0.1

Bind address.

NATS_NATS_PORT

int

9233

Bind port.

NATS_NATS_CLUSTER_ID

string

ocis-cluster

ID of the NATS cluster.

NATS_NATS_STORE_DIR

string

~/.ocis/nats

The directory where the filesystem storage will store NATS JetStream data. If not definied, the root directory derives from $OCIS_BASE_DATA_PATH:/nats.

NATS_TLS_CERT

string

~/.ocis/nats/tls.crt

Path/File name of the TLS server certificate (in PEM format) for the NATS listener.

NATS_TLS_KEY

string

~/.ocis/nats/tls.key

Path/File name for the TLS certificate key (in PEM format) for the NATS listener.

OCIS_INSECURE
NATS_TLS_SKIP_VERIFY_CLIENT_CERT

bool

false

Whether the NATS server should skip the client certificate verification during the TLS handshake.

OCIS_EVENTS_ENABLE_TLS
NATS_EVENTS_ENABLE_TLS

bool

false

Enable TLS for the connection to the events broker. The events broker is the ocis service which receives and delivers events between the services..

Environment variables for the nats service
Name Type Default Value Description

OCIS_LOG_LEVEL
NATS_LOG_LEVEL

string

The log level. Valid values are: "panic", "fatal", "error", "warn", "info", "debug", "trace".

OCIS_LOG_PRETTY
NATS_LOG_PRETTY

bool

false

Activates pretty log output.

OCIS_LOG_COLOR
NATS_LOG_COLOR

bool

false

Activates colorized log output.

OCIS_LOG_FILE
NATS_LOG_FILE

string

The path to the log file. Activates logging to this file if set.

NATS_DEBUG_ADDR

string

127.0.0.1:9234

Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.

NATS_DEBUG_TOKEN

string

Token to secure the metrics endpoint.

NATS_DEBUG_PPROF

bool

false

Enables pprof, which can be used for profiling.

NATS_DEBUG_ZPAGES

bool

false

Enables zpages, which can be used for collecting and viewing in-memory traces.

NATS_NATS_HOST

string

127.0.0.1

Bind address.

NATS_NATS_PORT

int

9233

Bind port.

NATS_NATS_CLUSTER_ID

string

ocis-cluster

ID of the NATS cluster.

NATS_NATS_STORE_DIR

string

~/.ocis/nats

The directory where the filesystem storage will store NATS JetStream data. If not definied, the root directory derives from $OCIS_BASE_DATA_PATH:/nats.

NATS_TLS_CERT

string

~/.ocis/nats/tls.crt

Path/File name of the TLS server certificate (in PEM format) for the NATS listener.

NATS_TLS_KEY

string

~/.ocis/nats/tls.key

Path/File name for the TLS certificate key (in PEM format) for the NATS listener.

OCIS_INSECURE
NATS_TLS_SKIP_VERIFY_CLIENT_CERT

bool

false

Whether the NATS server should skip the client certificate verification during the TLS handshake.

OCIS_EVENTS_ENABLE_TLS
NATS_EVENTS_ENABLE_TLS

bool

false

Enable TLS for the connection to the events broker. The events broker is the ocis service which receives and delivers events between the services..

YAML Example

  • latest

  • 2.0.0

# Autogenerated
# Filename: nats-config-example.yaml

log:
  level: ""
  pretty: false
  color: false
  file: ""
debug:
  addr: 127.0.0.1:9234
  token: ""
  pprof: false
  zpages: false
nats:
  host: 127.0.0.1
  port: 9233
  clusterid: ocis-cluster
  store_dir: ~/.ocis/nats
  tls_cert: ~/.ocis/nats/tls.crt
  tls_key: ~/.ocis/nats/tls.key
  tls_skip_verify_client_cert: false
  enable_tls: false
# Autogenerated
# Filename: nats-config-example.yaml

log:
  level: ""
  pretty: false
  color: false
  file: ""
debug:
  addr: 127.0.0.1:9234
  token: ""
  pprof: false
  zpages: false
nats:
  host: 127.0.0.1
  port: 9233
  clusterid: ocis-cluster
  store_dir: ~/.ocis/nats
  tls_cert: ~/.ocis/nats/tls.crt
  tls_key: ~/.ocis/nats/tls.key
  tls_skip_verify_client_cert: false
  enable_tls: false