Skip to main content

​
Prerequisites

  • Docker
  • Redis instance, if a persistent cache is in use

​
Usage

Run the service, replacing <tag> with the latest version in the ECR Public Gallery:

​
Sidecar SDK

To interface with the Sidecar service API, use the Sidecar SDK. For details, see:

Sidecar SDK

The SDK exposes a convenient stigg.api field which returns the same client as the Stigg.create_client SDK function. You can:
  • Use stigg.api wherever you would otherwise use Stigg.create_client
  • Rely on exactly the same interface and behavior
  • Know that the Sidecar SDK depends on the same underlying API client and simply exposes it for convenience
Since Sidecar SDK version 3.0.0, the TLS connection method has been deprecated in favor of non-TLS. Please ensure you are running a compatible Sidecar image version 2.494.0 or later. For backwards compatibility details, check the changelog. TLS self-signed certificates will expire on January 26, 2026, so upgrading the Sidecar image is strongly recommended.

​
Available options

Execution of the Sidecar service can be customized using the following environment variables:
​
string
required
The full access key of the environment.
​
string
default:"https://api.stigg.io"
The URL of the Stigg API.
​
boolean
default:"true"
Whether entitlements will be accessed from Edge.
​
string
default:"https://edge.api.stigg.io"
The Edge URL from which entitlements will be accessed.
​
boolean
default:"true"
Whether to listen for updates using WebSockets.
​
string
default:"wss://api.stigg.io"
The WebSocket API URL.
​
string
Identifier of the environment, used to prefix the keys in Redis. If provided, Redis will be used as the cache layer.
​
string
default:"localhost"
Redis host.
​
number
default:"6379"
Redis port.
​
number
default:"0"
Redis DB identifier.
​
string
Redis username.
​
string
Redis password.
​
boolean
default:"0"
Redis use TLS encryption. (Default=0)
​
number
default:"604800 (7 days)"
Time period for Redis to keep the data before eviction in seconds. Set to a negative value (e.g. -1, matching Redis’s own no-expiry convention) to disable expiration entirely, entries persist until invalidated by the persistent-cache-service pipeline. Useful when the Sidecar must keep serving entitlements through extended Stigg Cloud outages.
For end-to-end no-expiry behavior, the same negative value must also be set on persistent-cache-service via KEYS_TTL_IN_SECS. Setting it on only one side is inconsistent: whichever component writes a given key last decides whether it has a TTL. See persistent caching.
​
string
Global entitlement fallback strategy in JSON format.
​
number
default:"80"
Service port (HTTP/2)
​
number
default:"8443"
Deprecated TLS service port (HTTP/2 TLS)
​
number
default:"50% of total available memory size"
Maximum size of the in-memory cache in bytes. If not set, the Sidecar allocates up to 50% of the available memory.
​
string
default:"livez"
Health endpoint URL.
​
string
default:"readyz"
Ready endpoint URL.
​
number
default:"8080"
The port of the health and metrics endpoints.
​
string
default:"warn"
Log level, can be one of: error, warn, info, debug.
​
string
default:"msg"
Log string key for the ‘message’ in the JSON object.
​
string
default:"err"
Log string key for the ‘error’ in the JSON object.
​
string
default:"--max-old-space-size-percentage=75"
Node.js runtime flags. The default allocates 75% of container memory to the V8 heap, leaving room for the OS and non-heap allocations. Override to fine-tune memory allocation for your container setup.
​
boolean
default:"false"
Enables offline mode for local development.

​
Error handling

When the Sidecar encounters startup errors, such as an invalid API key or network errors to the Stigg API, it continues to run and serves entitlements from the:
  1. Persistent cache (if available)
  2. Global fallback strategy