Project: Reactive Interaction Gateway (Orchestration & Management / API Gateway)
File: rig-ops-guide.md

id: rig-ops-guide title: Operator's Guide to the Reactive Interaction Gateway sidebar_label: Operator's Guide Typically, RIG is deployed using Docker. You can either use the image on Docker Hub, or build one yourself using `docker build -t rig .`. RIG uses environment variables for most of its configuration, listed in the following table. Variable&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | Description | Default -- | -- | - `APIHTTPPORT` | Port at which RIG exposes internal APIs such as API Proxy management or user connections management. | 4010 `APIHTTPSPORT` | Same as `APIHTTPPORT`, but encrypted. See `HTTPSCERTFILE`, `HTTPSKEYFILE`, `HTTPSKEYFILEPASS`. | 4011 `INBOUND_PORT` | Port at which RIG exposes proxy and websocket/sse/longpolling communication. | 4000 `INBOUNDHTTPSPORT` | Same as `INBOUNDPORT`, but encrypted. See `HTTPSCERTFILE`, `HTTPSKEYFILE`, `HTTPSKEYFILE_PASS`. | 4001 `HTTPS_CERTFILE` | Path to the public HTTPS certificate (PEM format). If set, HTTPS is enabled for all endpoints. | "" `HTTPSKEYFILE` | Path to the HTTPS certificate's private key (PEM format). Also supports encrypted private keys; see `HTTPSKEYFILE_PASS` and consult the Erlang documentation for supported ciphers (e.g. ; note that as of OTP 21.1, using an unsupported cipher fails silently). | "" `HTTPSKEYFILEPASS` | Passphrase to the HTTPS certificate private key. Only set this if the private key is encrypted. | "" `CORS` | The "Access-Control-Allow-Origin" setting for the inbound port. It is usually a good idea to set this to your domain. | "*" `DISCOVERY_TYPE` | Type of discovery used in distributed mode. If not set discovery is not used. Available options: `dns`. | nil `DNS_NAME` | Address where RIG will do DNS discovery for Node host addresses. | "localhost" `EXTRACTORS` | Extractor configuration, given either as path to a JSON file, or directly as JSON. The extractor configuration contains information about events' fields per event type, used to extract information. For example, the following setting allows clients to specify a constraint on the `name` field of `greeting` events: `EXTRACTORS='{"greeting":{"name":{"stablefieldindex":1,"event":{"jsonpointer":"/name"}}}}'`. Note that `stablefieldindex` and `event/jsonpointer` are required for all configured fields. | nil `HOST` | Hostname for Phoenix endpoints (HTTP communication). | "localhost" `JWTSECRETKEY` | The secret key used to sign and verify the JSON web tokens. | "" `JWT_ALG` | Algorithm used to sign and verify JSON web tokens. | "HS256" `JWTSESSIONFIELD` | The JWT claim that defines a "session", which is used for listing and killing/blacklisting sessions. The default is to use a JWT's `jti` claim, which . This way, when blacklisting a session, the user cannot use the respective token anymore, but is able to create a new one by re-authenticating with the backend. The `JWTSESSIONFIELD` is specified using the notation. For example, this is how you would use a custom `sessionId` claim instead of the `jti`: `JWTSESSIONFIELD=/sessionId`. | "/jti" `KAFKA_BROKERS` | List of Kafka brokers RIG should connect to, delimited by comma (e.g., `localhost:9092,localhost:9093`). Usually it's enough to specify one broker and RIG will auto-discover rest of the Kafka cluster. | [] `KAFKALOGSCHEMA` | Avro schema name for events published by logger | "" `KAFKALOGTOPIC` | Kafka topic for producer used to log HTTP requests going through RIG's API Proxy. | "rig-request-log" `KAFKARESTARTDELAYMS` | If the connection to Kafka fails or cannot be established, RIG retries setting up the connection after `KAFKARESTARTDELAYMS`

| nil `KAFKASCHEMAREGISTRY_HOST` | Host for Kafka Schema Registry. | nil `KAFKA_SERIALIZER` | Serializer for Kafka events, currently supports Avro. By default uses JSON serialization. | nil `KAFKASOURCETOPICS` | List of Kafka topics RIG will consume, delimited by comma. | ["rig"] `KAFKATOFILTERKAFKAGROUP_ID` | Kafka group ID used for forwarding events according to subscriptions over SSE and WS connections. Make sure to use the same value on all RIG instances that belong to the same cluster. The default should be fine. | "rig-kafka-to-filter" `KAFKASASL` | If set, SASL is used to authenticate RIG against the Kafka brokers. Use the following format for SASL/Plain authentication: "plain:myusername:mypassword". Note that setting `KAFKASASL` does not enable SSL (see `KAFKASSLENABLED` and related settings). | nil `KAFKASSLENABLED` | Enables encrypted communication to Kafka brokers. | false `KAFKASSLCACERTFILE` | Path to the CA certificate (PEM format) that was used to sign the server and client certificates. Similar to `PROXYCONFIG_FILE` the path is relative to the OTP app's `priv` directory. | "ca.crt.pem" `KAFKASSLCERTFILE` | Path to the (signed) client certificate (PEM format). Similar to `PROXYCONFIGFILE` the path is relative to the OTP app's `priv` directory. | "client.crt.pem" `KAFKASSLKEYFILE` | Path to the private key of the client certificate (PEM format). Similar to `PROXYCONFIGFILE` the path is relative to the OTP app's `priv` directory. | "client.key.pem" `KAFKASSLKEYFILE_PASS` | Passphrase in case the private key is password-protected. | "" `KINESISAPPNAME` | From Amazon's documentation: "Name of the Amazon Kinesis application. This can assist with troubleshooting (e.g. distinguish requests made by separate applications). | "Reactive-Interaction-Gateway" `KINESISAWSREGION` | The AWS region the Kinesis stream is located in. | "eu-west-1" `KINESISCLIENTJAR` | Path to the kinesis-client jar file. | "./kinesis-client/target/rig-kinesis-client-1.0-SNAPSHOT.jar" `KINESISDYNAMODBENDPOINT` | A specific DynamoDB endpoint instead of the default one - useful for testing. | "" `KINESIS_ENABLED` | If enabled, RIG will consume messages from Amazon Kinesis using the configured parameters. Credentials are expected at `~/.aws/credentials`. | false `KINESIS_ENDPOINT` | A specific Kinesis endpoint instead of the default one - useful for testing. | "" `KINESISLOGLEVEL` | The log level for the (Java) Kinesis-client subsystem. Allowed values: OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL. | "INFO" `KINESISOTPJAR` | Path to the `OtpErlang.jar` file that contains the `JInterface` implementation. If left empty, RIG picks the file from its Erlang environment (Erlang must be compiled with Java support enabled). | nil `KINESIS_STREAM` | The name of the Kinesis stream to consume. | "RIG-outbound" `LOG_LEVEL` | Log level. One of: `debug`, `info`, `warn`, `error`. | "warn" `LOG_FMT` | Log format. May be set to `json` or `gcl` (Google Cloud Logger LogEntry format). | "erlang" `MAXCONNECTIONSPER_MINUTE` | Maximum number of WS + SSE + Longpolling connections per minute. | 5000 `NATS_SERVERS` | List of servers RIG should connect to, delimited by comma (e.g., `localhost:4222,example.com:4222`). | [] `NATSSOURCETOPICS` | List of NATS topics to subscribe to, delimited by comma. | ["rig"] `NATSTOFILTERQUEUEGROUP` | NATS used for forwarding events according to subscriptions over SSE and WS connections. Make sure to use the same value on all RIG instances that belong to the same cluster. The default should be fine. | "rig-nats-to-filter" `NODE_COOKIE` | Erlang cookie used in distributed mode, so nodes in cluster can communicate between each

/>Used also as secret key for integrity-check of correlation IDs. | nil `NODEHOST` | Erlang hostname for given node, used to build Erlang long-name `rig@NODEHOST`. This value is used by Erlang's distributed mode, so nodes can see each other. | nil `PROMETHEUSMETRICSENABLED` | Enable/disable collection of Prometheus (Telemetry) metrics. | true `PROXYCONFIGFILE` | Configuration JSON file with initial API definition for API Proxy. Use this variable to pass either a path to a JSON file, or the JSON string itself. A path can be given in absolute or in relative form (e.g., `proxy/yourjsonfile.json`). If given in relative form, the working directory is one of RIG's `priv` dirs (e.g., `/opt/sites/rig/lib/riginboundgateway-2.0.2/priv/` in a Docker container). | nil `PROXYHTTPASYNCRESPONSETIMEOUT` | In case an endpoint has `target` set to `http` and `responsefrom` set to `httpasync`, this is the maximum delay between an HTTP request and the corresponding async HTTP response message. | 5000 `PROXYRECVTIMEOUT` | Timeout used when receiving a response for a forwarded/proxied request. | 5000 `PROXYKAFKARESPONSE_TOPICS` | Kafka topic for acknowledging Kafka sync events from proxy by correlation ID | ["rig-proxy-response"] `PROXYKAFKARESPONSEKAFKAGROUP_ID` | Kafka group ID used for forwarding asynchronous HTTP responses to waiting HTTP clients. The default should be fine. | "rig-proxy-response" `PROXYKAFKARESPONSETIMEOUT` | In case an endpoint has `target` set to `http` and `responsefrom` set to `kafka`, this is the maximum delay between an HTTP request and the corresponding Kafka response message. | 5000 `PROXYKINESISRESPONSETIMEOUT` | In case an endpoint has `target` set to `http` and `responsefrom` set to `kinesis`, this is the maximum delay between an HTTP request and the corresponding Kinesis response message. | 5000 `PROXYKINESISREQUEST_REGION` | AWS region for Kinesis stream publishing events from proxy. | "eu-west-1" `PROXYNATSRESPONSETIMEOUT` | If `responsefrom` is set to `nats`, this defines how long RIG waits for the response. | 60000 `REQUEST_LOG` | Type of loggers to use to log requests processed by API Proxy, delimited by comma. | [] `SUBMISSIONCHECK` | Select if and how submitting/publishing events should be denied. Can be either `nocheck` (submissions are always allowed), `jwtvalidation` (submissions are allowed if at least one authorization token is valid - using JWTSECRETKEY - and not blacklisted), or an URL that points to an external service that decides whether to allow or deny the submissions. Such an external service is expected to accept POST requests. The CloudEvent is passed as a JSON map in the body. The original request's `Authorization` headers are reused for this request. The submission is allowed if the service returns 2xx and denied otherwise; return either 401 or 403 to reject a submission request. | "NOCHECK" `SUBSCRIPTIONCHECK` | Select if and how creating subscriptions should be denied. Can be either `nocheck` (subscriptions are always allowed), `jwtvalidation` (subscription are allowed if at least one authorization token is valid - using JWTSECRETKEY - and not blacklisted), or an URL that points to an external service that decides whether to allow or deny the subscription. Such an external service is expected to accept POST requests. The subscription parameters are passed in the body. The original request's `Authorization` headers are reused for this request. The subscription is allowed if the service returns 2xx and denied otherwise; return either 401 or 403 to reject a subscription request. | "NOCHECK" .