Environment variables

Environment variables are key value pairs used to configure how your Rafiki instance will run within your infrastructure and integrate with your systems.

Each environment variable name is uppercase, followed by an equal sign and the value of the variable.

Environment variable example

WEBHOOKS_URL=http://my-business/webhooks

The environment variable in the preceding example specifies the HTTP endpoint at which you want your Rafiki instance to send you notifications of webhook events.

To run Rafiki you must set the environment variables for the backend, auth and frontend services where listed as required below.

Caution

If you are running Rafiki via Docker, you must update the variables in the docker-compose.yml files of the respective services.

If you are running Rafiki via Helm and Kubernetes, you must update the variables in the values.yaml files for each of the respective services. Refer to the Helm and Kubernetes deployment guide for details.

Backend

Required

Variable	Helm value name	Default	Description
AUTH_SERVER_GRANT_URL	backend.auth.grantUrl	http://rafiki-auth.rafiki-auth:3006	The endpoint on your Open Payments authorization server to grant a request.
AUTH_SERVER_INTROSPECTION_URL	backend.auth.introspectionUrl	http://rafiki-auth.rafiki-auth:3007	The endpoint on your Open Payments authorization server to introspect an access token.
DATABASE_URL	backend.databaseUrl.secretKeyRef.key	DATABASE_URL	The Postgres database URL of the database storing your resource data. Stored as a secret key reference.
EXCHANGE_RATES_URL	backend.rates.url	""	The endpoint your Rafiki instance uses to request exchange rates.
ILP_ADDRESS	backend.ilp.address	test.rafiki-backend	The ILP address of your Rafiki instance.
ILP_CONNECTOR_URL	backend.ilp.connector	http://rafiki-backend:3002	The ILP connector address where ILP packets are received.
KEY_ID	backend.key.id	rafiki-override-this-value	Your Rafiki instance’s client key ID.
OPEN_PAYMENTS_URL	backend.ilp.host	http://rafiki-backend:3000	The public endpoint of your Open Payments resource server.
REDIS_URL	backend.redisUrl.secretKeyRef.key	REDIS_URL	The Redis URL of the database handling ILP packet data. Stored as a secret key reference.
USE_TIGERBEETLE	backend.useTigerbeetle	false	When true, a TigerBeetle database is used for accounting. When false, a Postgres database is used.
WEBHOOK_URL	backend.webhook.url	http://wallet/webhooks/rafiki	Your endpoint that consumes webhook events.
AUTH_SERVICE_API_URL	undefined	undefined	The service-to-service api endpoint on your Open Payments authorization server.

Conditionally required

Variable	Helm value name	Default	Description
INSTANCE_NAME	backend.instanceName	rafiki-backend-changeme	Your Rafiki instance’s name used to communicate for auto-peering and/or telemetry. Required when auto-peering and/or telemetry is enabled
TRUST_PROXY	backend.trustProxy	true	Must be set to true when running Rafiki behind a proxy. When true, the X-Forwarded-Proto header is used to determine if connections are secure.

Optional

Variable	Helm value name	Default	Description
ADMIN_PORT	backend.port.admin	3001	The port of your Backend Auth API server.
ADMIN_API_SIGNATURE_TTL_SECONDS	undefined	30	The TTL, in seconds, for which a request’s signature will be valid.
API_SECRET	undefined	undefined	N/A
API_SIGNATURE_VERSION	undefined	1	The version of the request signing algorithm used to generate signatures.
AUTO_PEERING_SERVER_PORT	backend.port.autoPeering	3005	If auto-peering is enabled, the server will use this port.
CONNECTOR_PORT	backend.port.connector	3002	The port of the ILP connector for sending packets via ILP over HTTP.
ENABLE_AUTO_PEERING	backend.autoPeering.enabled	false	When true, auto-peering is enabled.
ENABLE_MANUAL_MIGRATIONS	undefined	false	When true, you must run the database manually with the command npm run knex — migrate:latest —env production
ENABLE_SPSP_PAYMENT_POINTERS	undefined	true	When true, the SPSP route is enabled.
ENABLE_TELEMETRY	backend.telemetry.enabled	false	Enables the telemetry service on Rafiki.
ENABLE_TELEMETRY_TRACES	undefined	false	N/A
EXCHANGE_RATES_LIFETIME	backend.lifetime.exchangeRate	15000	The time, in milliseconds, the exchange rates you provide via the EXCHANGE_RATES_URL are valid.
GRAPHQL_IDEMPOTENCY_KEY_LOCK_MS	backend.idempotency.keyLock	2000	The TTL, in milliseconds, for idempotencyKey concurrency lock on GraphQL mutations on the Backend Admin API.
GRAPHQL_IDEMPOTENCY_KEY_TTL_MS	backend.idempotency.keyTTL	86400000	The TTL, in milliseconds, for idempotencyKey on GraphQL mutations on the Backend Admin API.
INCOMING_PAYMENT_CREATED_POLL_FREQUENCY_MS	undefined	1000	N/A
INCOMING_PAYMENT_CREATED_POLL_TIMEOUT_MS	undefined	10000	N/A
INCOMING_PAYMENT_EXPIRY_MAX_MS	undefined	2592000000 (30 days)	The maximum into the future, in milliseconds, incoming payments expiry can be set to on creation.
INCOMING_PAYMENT_WORKER_IDLE	backend.workerIdle	200	The time, in milliseconds, that INCOMING_PAYMENT_WORKERS will wait until checking an empty incoming payment request queue again.
INCOMING_PAYMENT_WORKERS	backend.workers.incomingPayment	1	The number of workers processing incoming payment requests.
LOG_LEVEL	backend.logLevel	info	Pino log level
MAX_OUTGOING_PAYMENT_RETRY_ATTEMPTS	undefined	5	Specifies how many times an outgoing payment is retried before failing completely
NODE_ENVIRONMENT	backend.nodeEnv	production	The type of node environment: development, test, or production.
OPEN_PAYMENTS_PORT	backend.port.openPayments	3000	The port of your Open Payments resource server.
OPEN_TELEMETRY_COLLECTOR_URLS	undefined	undefined	N/A
OPEN_TELEMETRY_EXPORT_INTERVAL	undefined	15000	N/A
OPEN_TELEMETRY_TRACE_COLLECTOR_URLS	undefined	undefined	N/A
OUTGOING_PAYMENT_WORKER_IDLE	backend.workerIdle	200	The time, in milliseconds, that OUTGOING_PAYMENT_WORKERS wait until they check an empty outgoing payment request queue again.
OUTGOING_PAYMENT_WORKERS	backend.workers.outgoingPayment	1	The number of workers processing outgoing payment requests.
POLL_INCOMING_PAYMENT_CREATED_WEBHOOK	undefined	false	N/A
PRIVATE_KEY_FILE	backend.key.pvk	''	The private key pem file used. Must be provided as base64 encoded version of the pem file.
QUOTE_LIFESPAN	backend.lifetime.quote	300000	The time, in milliseconds, an Open Payments quote is valid for.
REDIS_TLS_CA_FILE_PATH	undefined	''	Redis TLS config
REDIS_TLS_CERT_FILE_PATH	undefined	''	Redis TLS config
REDIS_TLS_KEY_FILE_PATH	undefined	''	Redis TLS config
SIGNATURE_SECRET	backend.webhookSignatureSecret.secretKeyRef.key	SIGNATURE_SECRET	The secret to generate request header signatures for webhook event requests.
SIGNATURE_VERSION	undefined	1	The version number to generate request header signatures for webhook events.
SLIPPAGE	backend.slippage	0.01	The accepted ILP rate fluctuation.
STREAM_SECRET	backend.ilp.streamSecret.secretKeyRef.key	STREAM_SECRET	The seed secret to generate shared STREAM secrets.
TELEMETRY_EXCHANGE_RATES_LIFETIME	undefined	86_400_000	N/A
TELEMETRY_EXCHANGE_RATES_URL	undefined	https://telemetry-exchange-rates.s3.amazonaws.com/exchange-rates-usd.json	The endpoint Rafiki will query for exchange rates. Used as a fallback if/when exchange rates aren’t provided.
TIGERBEETLE_CLUSTER_ID	undefined	0	The TigerBeetle cluster ID picked by the system that starts the TigerBeetle cluster to create a TigerBeetle client.
TIGERBEETLE_REPLICA_ADDRESSES	undefined	3004	TigerBeetle replica addresses for all replicas in the cluster. The addresses are comma-separated IP addresses/ports, to create a TigerBeetle client.
TIGERBEETLE_REPLICA_ADDRESSES.SPLIT	undefined	3004	N/A
TIGERBEETLE_TWO_PHASE_TIMEOUT_SECONDS	undefined	5	N/A
WALLET_ADDRESS_DEACTIVATION_PAYMENT_GRACE_PERIOD_MS	undefined	86400000 (24 hours)	The time into the future, in milliseconds, to set expiration of Open Payments incoming payments when deactivating a wallet address.
WALLET_ADDRESS_LOOKUP_TIMEOUT_MS	undefined	1500	The time, in milliseconds, you have to create a missing wallet address before timeout.
WALLET_ADDRESS_POLLING_FREQUENCY_MS	undefined	100	The frequency of polling while waiting for you to create a missing wallet address.
WALLET_ADDRESS_URL	undefined	http://127.0.0.1:3001/.well-known/pay	Your Rafiki instance’s internal wallet address.
WALLET_ADDRESS_WORKER_IDLE	backend.workerIdle	200	The time, in milliseconds, that WALLET_ADDRESS_WORKERS wait until checking the empty wallet address request queue again.
WALLET_ADDRESS_WORKERS	backend.workers.paymentPointer	1	The number of workers processing wallet address requests.
WEBHOOK_MAX_RETRY	undefined	10	The maximum number of times your Rafiki instance’s backend retries sending a certain webhook event to your configured WEBHOOK_URL.
WEBHOOK_TIMEOUT	backend.lifetime.webhook	200	The time, in milliseconds, that your Rafiki instance will wait for a 200 response from your webhook endpoint. If a 200 response is not received, Rafiki will time out and try to send the webhook event again.
WEBHOOK_WORKER_IDLE	backend.workerIdle	200	The time, in milliseconds, that WEBHOOK_WORKERS will wait until they check the empty webhook event queue again.
WEBHOOK_WORKERS	backend.workers.webhook	1	The number of workers processing webhook events.
WITHDRAWAL_THROTTLE_DELAY	backend.withdrawalThrottleDelay	''	The delay in liquidity withdrawal processing.
TELEMETRY_EXCHANGE_RATES_URL	undefined	https://telemetry-exchange-rates.s3.amazonaws.com/exchange-rates-usd.json	The endpoint Rafiki will query for exchange rates. Used as a fallback if/when exchange rates aren’t provided.
TIGERBEETLE_CLUSTER_ID	undefined	0	The TigerBeetle cluster ID picked by the system that starts the TigerBeetle cluster to create a TigerBeetle client.
TIGERBEETLE_REPLICA_ADDRESSES	undefined	3004	TigerBeetle replica addresses for all replicas in the cluster. The addresses are comma-separated IP addresses/ports, to create a TigerBeetle client.
TIGERBEETLE_REPLICA_ADDRESSES.SPLIT	undefined	3004	N/A
TIGERBEETLE_TWO_PHASE_TIMEOUT_SECONDS	undefined	5	N/A
WALLET_ADDRESS_DEACTIVATION_PAYMENT_GRACE_PERIOD_MS	undefined	86400000 (24 hours)	The time into the future, in milliseconds, to set expiration of Open Payments incoming payments when deactivating a wallet address.
WALLET_ADDRESS_LOOKUP_TIMEOUT_MS	undefined	1500	The time, in milliseconds, you have to create a missing wallet address before timeout.
WALLET_ADDRESS_POLLING_FREQUENCY_MS	undefined	100	The frequency of polling while waiting for you to create a missing wallet address.
WALLET_ADDRESS_URL	undefined	http://127.0.0.1:3001/.well-known/pay	Your Rafiki instance’s internal wallet address.
WALLET_ADDRESS_WORKER_IDLE	workerIdle	200	The time, in milliseconds, that WALLET_ADDRESS_WORKERS wait until checking the empty wallet address request queue again.
WALLET_ADDRESS_WORKERS	workers.paymentPointer	1	The number of workers processing wallet address requests.
WEBHOOK_MAX_RETRY	undefined	10	The maximum number of times your Rafiki instance’s backend retries sending a certain webhook event to your configured WEBHOOK_URL.
WEBHOOK_TIMEOUT	lifetime.webhook	200	The time, in milliseconds, that your Rafiki instance will wait for a 200 response from your webhook endpoint. If a 200 response is not received, Rafiki will time out and try to send the webhook event again.
WEBHOOK_WORKER_IDLE	workerIdle	200	The time, in milliseconds, that WEBHOOK_WORKERS will wait until they check the empty webhook event queue again.
WEBHOOK_WORKERS	workers.webhook	1	The number of workers processing webhook events.
WITHDRAWAL_THROTTLE_DELAY	withdrawalThrottleDelay	''	The delay in liquidity withdrawal processing.

Auth

Required

Variable	Helm value name	Default	Description
AUTH_DATABASE_URL	auth.databaseUrl.secretKeyRef.key	DATABASE_URL	The URL of the Postgres database storing your Open Payments grant data. Stored as a secret key reference.
AUTH_SERVER_URL	auth.authServerUrl	http://rafiki-auth:3006	The public endpoint for your Rafiki instance’s public Open Payments routes.
COOKIE_KEY	auth.cookieKey.secretKeyRef.key	COOKIE_KEY	The koa KeyGrip key that is used to sign cookies for an interaction session.
IDENTITY_SERVER_URL	auth.identityServer.domain	http://rafiki-backend/idp	The URL of your IdP’s server, used by the authorization server to inform an Open Payments client of where to redirect the end-user to start interactions.
IDENTITY_SERVER_SECRET	auth.identityServer.serverSecret.secretKeyRef.key	IDENTITY_SERVER_SECRET	A shared secret between the authorization server and the IdP server; the authorization server will use the secret to secure its IdP-related endpoints. When the IdP server sends requests to the authorization server, the IdP server must provide the secret via an x-idp-secret header.
REDIS_URL	auth.redisUrl.secretKeyRef.key	REDIS_URL	The connection URL for Redis. Stored as a secret key reference.

Conditionally required

Variable	Helm value name	Default	Description
TRUST_PROXY	auth.trustProxy	true	Must be set to true when running Rafiki behind a proxy. When true, the X-Forwarded-Proto header is used to determine if connections are secure.

Optional

Variable	Helm value name	Default	Description
ACCESS_TOKEN_DELETION_DAYS	auth.accessToken.deletionDays	30	The days until expired and/or revoked access tokens are deleted.
ACCESS_TOKEN_EXPIRY_SECONDS	auth.accessToken.expirySeconds	600 (10 minutes)	The expiry time, in seconds, for access tokens.
ADMIN_API_SIGNATURE_VERSION	undefined	1	The version of the request signing algorithm used to generate signatures.
ADMIN_API_SIGNATURE_TTL_SECONDS	undefined	30	The TTL, in seconds, for which a request’s signature will be valid.
ADMIN_PORT	auth.port.admin	3003	The port of your Rafiki Auth Admin API server.
AUTH_PORT	auth.port.auth	3006	The port of your Open Payments authorization server.
DATABASE_CLEANUP_WORKERS	auth.workers.cleanup	1	The number of workers processing expired or revoked access tokens.
ENABLE_MANUAL_MIGRATIONS	undefined	false	When true, you must run the auth Postgres database manually with the command npm run knex — migrate:latest —envproduction
INCOMING_PAYMENT_INTERACTION	auth.interaction.incomingPayment	"false"	When true, incoming Open Payments grant requests are interactive
INTERACTION_EXPIRY_SECONDS	undefined	600 (10 minutes)	The time, in seconds, for which a user can interact with a grant request before the request expires.
INTERACTION_PORT	auth.port.interaction	3009	The port number of your Open Payments interaction-related APIs.
INTROSPECTION_PORT	auth.port.introspection	3007	The port of your Open Payments access token introspection server.
SERVICE_API_PORT	undefined	3011	The port to expose the internal service api.
LIST_ALL_ACCESS_INTERACTION	auth.interaction.listAll	true	When true, grant requests that include a list-all action will require interaction. In these requests, the client asks to list resources that it did not create.
LOG_LEVEL	auth.logLevel	info	Pino log level
NODE_ENV	auth.nodeEnv	production	The type of node environment: development, test, or production.
QUOTE_INTERACTION	auth.interaction.quote	"false"	When true, quote grants are interactive.
REDIS_TLS_CA_FILE_PATH	undefined	''	Redis TLS config
REDIS_TLS_CERT_FILE_PATH	undefined	''	Redis TLS config
REDIS_TLS_KEY_FILE_PATH	undefined	''	Redis TLS config
WAIT_SECONDS	auth.grant.waitSeconds	5	The wait time, in seconds, included in a grant request response (grant.continue).

Frontend

Required

Variable	Helm value name	Default	Description
GRAPHQL_URL	frontend.serviceUrls.GRAPHQL_URL	http://rafiki-backend-service.rafiki:3001/graphql	URL for Rafiki’s GraphQL Auth Admin API
OPEN_PAYMENTS_URL	frontend.serviceUrls.OPEN_PAYMENTS_URL	https://rafiki-backend-service/	Your Open Payments API endpoint
PORT	frontend.port	3010	Port from which to host the Rafiki Remix app

Conditionally required

The following variables are required only when AUTH_ENABLED is set to true.

Variable	Helm value name	Default	Description
KRATOS_ADMIN_URL	frontend.kratos.adminUrl	undefined	The admin endpoint/container address for Kratos
KRATOS_CONTAINER_PUBLIC_URL	frontend.kratos.containerPublicUrl	undefined	The URL for you to access the Kratos Docker container from within the Docker network. This is used for backend calls to Kratos.
KRATOS_BROWSER_PUBLIC_URL	frontend.kratos.browserPublicUrl	undefined	The URL for you to access the Kratos Docker container from a browser outside of the Docker network. This is used for calls from a browser (what you see in the Rafiki Admin UI) to the Kratos server on the backend.

Optional

Variable	Helm value name	Default	Description
AUTH_ENABLED	undefined	true	When true, only authenticated users can be granted access to Rafiki Admin by an administrator
SIGNATURE_SECRET	undefined	undefined	The signature secret used to authenticate requests to the Backend Admin API.
SIGNATURE_VERSION	undefined	1	The signature version number used to authenticate requests to the Backend Admin API.
ENABLE_INSECURE_MESSAGE_COOKIE	undefined	true	When set to true, t, or 1, cookie will be transmitted over insecure HTTP connection. Insecure message cookies are required for flash messages to work over HTTP.
NODE_ENV	frontend.nodeEnv	production	The type of node environment: development, test, or production.
LOG_LEVEL	frontend.logLevel	debug	Pino log level