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. The Sidecar serves the REST API on HTTP_PORT (default 8080) and gRPC on GRPC_PORT (default 80), so publish the ports your clients use:

​
Calling the Sidecar

You can call the Sidecar with the Stigg REST API, from any REST client or plain HTTP, or over gRPC with the Sidecar SDKs.

​
REST API

Requires Sidecar service 8.1.0 or later.
The Sidecar serves the Stigg REST API under /api/* on its HTTP port (default 8080). To cache your REST entitlement checks, point your REST client’s base URL at the Sidecar instead of the Stigg API. You don’t need to change any request or response code:
The Sidecar answers these reads from its cache, in the same response format as the Stigg REST API: On a cache miss, the Sidecar fetches the customer’s entitlements from Stigg, caches them, and answers from the cache. Responses served from the cache carry the x-stigg-served-by: sidecar header. All other requests are forwarded to Stigg unchanged. If the Sidecar can’t get a customer’s entitlements, for example because Stigg is unreachable on a cache miss, it answers with the configured fallback entitlements. Writes always go to Stigg. When your application changes a subscription, reports usage, or consumes credits through the Sidecar, the Sidecar reads Stigg’s response and updates its cache, so a read that follows the write reflects it. If a cache update fails, your application still receives Stigg’s response, and the Sidecar increments the sidecar_write_through_errors_total metric. The cached entry stays stale until the next refresh.

​
Sidecar SDK (gRPC)

The Sidecar SDKs call the Sidecar over gRPC. 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

​
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"
The gRPC port (HTTP/2) used by the Sidecar SDKs.
​
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 HTTP port that serves the Stigg REST API under /api/*, alongside the health and metrics endpoints. Takes precedence over METRICS_PORT if both are set.
​
number
default:"8080"
Deprecated, use HTTP_PORT instead. Still honored as an alias when HTTP_PORT is not set.
​
string
default:"https://edge.api.stigg.io"
The Stigg API URL that REST API requests are forwarded to. Must contain only a scheme and host, with no path, query, or credentials. Authentication is passed through from the caller’s X-API-KEY header.
​
boolean
default:"true"
Whether to use HTTP/2 for REST API requests forwarded to ORIGIN_URL, when the origin supports it. Set to false to force HTTP/1.1.
​
number
default:"16 over HTTP/2, 1 over HTTP/1.1"
Maximum number of concurrent requests per connection to ORIGIN_URL. If not set, the Sidecar picks the value based on the protocol it negotiates with the origin at startup.
​
number
default:"60000"
How long, in milliseconds, the Sidecar waits for ORIGIN_URL to send response headers, and between chunks of the response body, before failing a forwarded REST API request.
​
string
default:"info"
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.

​
Deployment

The Sidecar is a Docker container and runs anywhere Docker is supported, including AWS, GCP, and Azure. All deployment methods use the same Sidecar Docker image hosted on AWS ECR:
See architecture and scaling to choose between the sidecar pattern and a standalone service.

​
Google Cloud Platform (GCP)

You can deploy the Sidecar on GCP in one of the following ways:
  1. Google Kubernetes Engine (GKE): Ideal for production deployments using the sidecar pattern.
  2. Google Cloud Run: For event-driven or serverless-style deployments where scale-to-zero is needed.
  3. Google Compute Engine (GCE): Running the container directly on a VM with Docker installed.
  4. Standalone service: Run the Sidecar as a central service accessible over an internal IP and port.

​
Kubernetes

In Kubernetes environments (such as EKS or GKE), the Sidecar container can be deployed alongside your application container in the same pod, allowing low-latency REST or gRPC communication via localhost. You can install the Sidecar using either helm or kustomize. For detailed instructions, resources, and examples, visit the Stigg Helm charts GitHub repository.

​
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 persistent cache (if available), and then from the global fallback strategy.