Skip to content
GitHub

Environment variables

Environment variables are key value pairs that are 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 example above 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.

Backend

Required

VariableHelm value nameDefaultDescription
AUTH_SERVER_GRANT_URLbackend.serviceUrls.AUTH_SERVER_GRANT_URLundefinedThe endpoint on your Open Payments authorization server to grant a request.
AUTH_SERVER_INTROSPECTION_URLbackend.serviceUrls.AUTH_SERVER_INTROSPECTION_URLundefinedThe endpoint on your Open Payments authorization server to introspect an access token.
DATABASE_URLbackend.postgresql.host,
backend.postgresql.port,
backend.postgresql.username,
backend.postgresql.database,
backend.postgresql.password
postgresql://postgres:password@localhost:5432/developmentThe Postgres database URL of the database storing your resource data. For Helm, these components are provided individually.
EXCHANGE_RATES_URLbackend.serviceUrls.EXCHANGE_RATES_URLundefinedThe endpoint your Rafiki instance uses to request exchange rates.
ILP_ADDRESSbackend.ilp.addressundefinedThe ILP address of your Rafiki instance.
ILP_CONNECTOR_URLbackend.ilp.connectorUrlundefinedThe ILP connector address where ILP packets are received.
KEY_IDbackend.key.idundefinedYour Rafiki instance’s client key ID.
OPEN_PAYMENTS_URLbackend.serviceUrls.OPEN_PAYMENTS_URLundefinedThe public endpoint of your Open Payments resource server.
REDIS_URLbackend.redis.host,
backend.redis.port
redis://127.0.0.1:6379The Redis URL of the database handling ILP packet data. For Helm, these components are provided individually.
USE_TIGERBEETLEbackend.use.tigerbeetletrueWhen true, a TigerBeetle database is used for accounting. When false, a Postgres database is used.
WEBHOOK_URLbackend.serviceUrls.WEBHOOK_URLundefinedYour endpoint that consumes webhook events.

Conditionally required

VariableHelm value nameDefaultDescription
INSTANCE_NAMEbackend.instance.nameundefinedYour Rafiki instance’s name used to communicate for auto-peering and/or telemetry. Required when auto-peering and/or telemetry is enabled

Optional

VariableHelm value nameDefaultDescription
ADMIN_PORTbackend.port.admin3001The port of your Backend Auth API server.
ADMIN_API_SIGNATURE_TTL_SECONDSundefined30The TTL, in seconds, for which a request’s signature will be valid.
API_SECRETundefinedundefinedN/A
API_SIGNATURE_VERSIONundefined1The version of the request signing algorithm used to generate signatures.
AUTO_PEERING_SERVER_PORTbackend.autoPeering.serverPort3005If auto-peering is enabled, the server will use this port.
CONNECTOR_PORTbackend.port.connector3002The port of the ILP connector for sending packets via ILP over HTTP.
ENABLE_AUTO_PEERINGbackend.enable.autoPeeringfalseWhen true, auto-peering is enabled.
ENABLE_MANUAL_MIGRATIONSbackend.enableManualMigrationsfalseWhen true, you must run the database manually with the command npm run knex – migrate:latest –env production
ENABLE_SPSP_PAYMENT_POINTERSbackend.enable.spspPaymentPointerstrueWhen true, the SPSP route is enabled.
ENABLE_TELEMETRYundefinedfalseEnables the telemetry service on Rafiki.
ENABLE_TELEMETRY_TRACESundefinedfalseN/A
EXCHANGE_RATES_LIFETIMEbackend.lifetime.exchangeRate15_000The time, in milliseconds, the exchange rates you provide via the EXCHANGE_RATES_URL are valid.
GRAPHQL_IDEMPOTENCY_KEY_LOCK_MSbackend.idempotency.keyLockMs2000The TTL, in milliseconds, for idempotencyKey concurrency lock on GraphQL mutations on the Backend Admin API.
GRAPHQL_IDEMPOTENCY_KEY_TTL_MSbackend.idempotency.keyTTL86400000 (24 hours)The TTL, in milliseconds, for idempotencyKey on GraphQL mutations on the Backend Admin API.
INCOMING_PAYMENT_CREATED_POLL_FREQUENCY_MSundefined1000N/A
INCOMING_PAYMENT_CREATED_POLL_TIMEOUT_MSundefined10000N/A
INCOMING_PAYMENT_EXPIRY_MAX_MSbackend.incomingPayment.expiryMaxMs2592000000 (30 days)The maximum into the future, in milliseconds, incoming payments expiry can be set to on creation.
INCOMING_PAYMENT_WORKER_IDLEbackend.workerIdle200The time, in milliseconds, that INCOMING_PAYMENT_WORKERS will wait until checking an empty incoming payment request queue again.
INCOMING_PAYMENT_WORKERSbackend.workers.incomingPayment1The number of workers processing incoming payment requests.
LOG_LEVELbackend.logLevelinfoPino log level
MAX_OUTGOING_PAYMENT_RETRY_ATTEMPTSundefined5Specifies how many times an outgoing payment is retried before failing completely
NODE_ENVIRONMENTbackend.nodeEnvdevelopmentThe type of node environment: development, test, or production.
OPEN_PAYMENTS_PORTbackend.port.openPayments3003The port of your Open Payments resource server.
OPEN_TELEMETRY_COLLECTOR_URLSundefined*undefinedN/A
OPEN_TELEMETRY_EXPORT_INTERVALundefined15000N/A
OPEN_TELEMETRY_TRACE_COLLECTOR_URLSundefinedundefinedN/A
OUTGOING_PAYMENT_WORKER_IDLEbackend.workerIdle200The time, in milliseconds, that OUTGOING_PAYMENT_WORKERS wait until they check an empty outgoing payment request queue again.
OUTGOING_PAYMENT_WORKERSbackend.workers.outgoingPayment4The number of workers processing outgoing payment requests.
POLL_INCOMING_PAYMENT_CREATED_WEBHOOKundefinedfalseN/A
PRIVATE_KEY_FILEbackend.key.fileundefinedThe path to your Rafiki instance’s client private key.
QUOTE_LIFESPANbackend.lifetime.quote5 * 60_000 (5 minutes)The time, in milliseconds, an Open Payments quote is valid for.
REDIS_TLS_CA_FILE_PATHbackend.redis.tlsCaFile''Redis TLS config
REDIS_TLS_CERT_FILE_PATHbackend.redis.tlsCertFile''Redis TLS config
REDIS_TLS_KEY_FILE_PATHbackend.redis.tlsKeyFile''Redis TLS config
SIGNATURE_SECRETbackend.quoteSignatureSecretundefinedThe secret to generate request header signatures for webhook event requests.
SIGNATURE_VERSIONbackend.signatureVersion1The version number to generate request header signatures for webhook events.
SLIPPAGEbackend.ilp.slippage0.01 (1%)The accepted ILP rate fluctuation.
STREAM_SECRETbackend.ilp.streamSecretundefinedThe seed secret to generate shared STREAM secrets.
TELEMETRY_EXCHANGE_RATES_LIFETIMEundefined86_400_000N/A
TELEMETRY_EXCHANGE_RATES_URLundefinedhttps://telemetry-exchange-rates.s3.amazonaws.com/exchange-rates-usd.jsonThe endpoint Rafiki will query for exchange rates. Used as a fallback if/when exchange rates aren’t provided.
TIGERBEETLE_CLUSTER_IDundefined0The TigerBeetle cluster ID picked by the system that starts the TigerBeetle cluster to create a TigerBeetle client.
TIGERBEETLE_REPLICA_ADDRESSESundefined3004TigerBeetle replica addresses for all replicas in the cluster. The addresses are comma-separated IP addresses/ports, to create a TigerBeetle client.
TIGERBEETLE_REPLICA_ADDRESSES.SPLITundefined3004N/A
TIGERBEETLE_TWO_PHASE_TIMEOUT_SECONDSundefined5N/A
TRUST_PROXYbackend.trustProxyfalseWhen true, the X-Forwarded-Proto header is used to determine if connections are secure.
WALLET_ADDRESS_DEACTIVATION_PAYMENT_GRACE_PERIOD_MSbackend.walletAddress.deactivationPaymentGratePeriodMs86400000 (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_MSbackend.walletAddress.lookupTimeoutMs1500The time, in milliseconds, you have to create a missing wallet address before timeout.
WALLET_ADDRESS_POLLING_FREQUENCY_MSbackend.walletAddress.pollingFrequencyMs100The frequency of polling while waiting for you to create a missing wallet address.
WALLET_ADDRESS_URLbackend.serviceUrls.WALLET_ADDRESS_URLhttp://127.0.0.1:3001/.well-known/payYour Rafiki instance’s internal wallet address.
WALLET_ADDRESS_WORKER_IDLEbackend.workerIdle200The time, in milliseconds, that WALLET_ADDRESS_WORKERS wait until checking the empty wallet address request queue again.
WALLET_ADDRESS_WORKERS`backend.workers.walletAddress1The number of workers processing wallet address requests.
WEBHOOK_MAX_RETRYbackend.webhookMaxRetry10The maximum number of times your Rafiki instance’s backend retries sending a certain webhook event to your configured WEBHOOK_URL.
WEBHOOK_TIMEOUTbackend.lifetime.webhook2000 (2 seconds)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_IDLEbackend.workerIdle200The time, in milliseconds, that WEBHOOK_WORKERS will wait until they check the empty webhook event queue again.
WEBHOOK_WORKERSbackend.workers.webhook1The number of workers processing webhook events.
WITHDRAWAL_THROTTLE_DELAYbackend.withdrawalThrottleDelayundefinedThe delay in liquidity withdrawal processing.

Auth

Required

VariableHelm value nameDefaultDescription
AUTH_DATABASE_URLauth.postgresql.host,
auth.postgresql.port,
auth.postgresql.username,
auth.postgresql.database,
auth.postgresql.password
postgresql://postgres:password@localhost:5432/auth_developmentThe URL of the Postgres database storing your Open Payments grant data. For Helm, these components are provided individually.
AUTH_SERVER_URLauth.server.domainundefinedThe public endpoint for your Rafiki instance’s public Open Payments routes.
COOKIE_KEYauth.cookieKeyundefinedThe koa KeyGrip key that is used to sign cookies for an interaction session.
IDENTITY_SERVER_URLauth.identityServer.domainundefinedThe specific URL of your identity provider’s user-facing consent screen.
IDENTITY_SERVER_SECRETauth.identityServer.secretundefinedThe API key for fetching your identity (IdP) server endpoint.
REDIS_URLauth.redis.host,
auth.redis.port
redis://127.0.0.1:6379The connection URL for Redis. For Helm, these components are provided individually.

Optional

VariableHelm value nameDefaultDescription
ACCESS_TOKEN_DELETION_DAYSauth.accessToken.deletionDays30The days until expired and/or revoked access tokens are deleted.
ACCESS_TOKEN_EXPIRY_SECONDSauth.accessToken.expirySeconds600 (10 minutes)The expiry time, in seconds, for access tokens.
ADMIN_API_SIGNATURE_VERSIONauth.adminApi.signatureVersion1The version of the request signing algorithm used to generate signatures.
ADMIN_API_SIGNATURE_TTL_SECONDSauth.adminAPI.signatureTtlSeconds30The TTL, in seconds, for which a request’s signature will be valid.
ADMIN_PORTauth.port.admin3003The port of your Rafiki Auth Admin API server.
AUTH_PORTauth.port.auth3006The port of your Open Payments authorization server.
DATABASE_CLEANUP_WORKERSauth.workers.cleanup1The number of workers processing expired or revoked access tokens.
ENABLE_MANUAL_MIGRATIONSauth.enableManualMigrationsfalseWhen true, you must run the auth Postgres database manually with the command npm run knex – migrate:latest –envproduction
INCOMING_PAYMENT_INTERACTIONauth.interaction.incomingPaymentfalseWhen true, incoming Open Payments grant requests are interactive
INTERACTION_EXPIRY_SECONDSauth.interactionExpirySeconds600 (10 minutes)The time, in seconds, for which a user can interact with a grant request before the request expires.
INTERACTION_PORTauth.port.interaction3009The port number of your Open Payments interaction-related APIs.
INTROSPECTION_PORTauth.port.introspection3007The port of your Open Payments access token introspection server.
LIST_ALL_ACCESS_INTERACTIONauth.interaction.listAlltrueWhen 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_LEVELauth.logLevelinfoPino log level
NODE_ENVauth.nodeEnvdevelopmentThe type of node environment: development, test, or production.
QUOTE_INTERACTIONauth.interaction.quotefalseWhen true, quote grants are interactive.
REDIS_TLS_CA_FILE_PATHauth.redis.tlsCaFile''Redis TLS config
REDIS_TLS_CERT_FILE_PATHauth.redis.tlsCertFile''Redis TLS config
REDIS_TLS_KEY_FILE_PATHauth.redis.tlsKeyFile''Redis TLS config
TRUST_PROXYauth.trustProxyfalseWhen true, the X-Forwarded-Proto header is used to determine if connections are secure.
WAIT_SECONDSauth.grant.waitSeconds5The wait time, in seconds, included in a grant request response (grant.continue).

Frontend

Required

VariableHelm value nameDefaultDescription
GRAPHQL_URLfrontend.serviceUrls.GRAPHQL_URLundefinedURL for Rafiki’s GraphQL Auth Admin API
OPEN_PAYMENTS_URLfrontend.serviceUrls.OPEN_PAYMENTS_URLundefinedYour Open Payments API endpoint
PORTfrontend.portundefinedPort from which to host the Rafiki Remix app

Conditionally required

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

VariableHelm value nameDefaultDescription
KRATOS_ADMIN_URLfrontend.kratos.adminUrlundefinedThe admin endpoint/container address for Kratos
KRATOS_CONTAINER_PUBLIC_URLfrontend.kratos.containerPublicUrlundefinedThe 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_URLfrontend.kratos.browserPublicUrlundefinedThe 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

VariableHelm value nameDefaultDescription
AUTH_ENABLEDfrontend.authEnabledtrueWhen true, only authenticated users can be granted access to Rafiki Admin by an administrator
SIGNATURE_SECRETfrontend.quoteSignatureSecretundefinedThe signature secret used to authenticate requests to the Backend Admin API.
SIGNATURE_VERSIONfrontend.signatureVersion1The signature version number used to authenticate requests to the Backend Admin API.
ENABLE_INSECURE_MESSAGE_COOKIEfrontend.enableInsecureMessageCookietrueWhen 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_ENVfrontend.nodeEnvproductionThe type of node environment: development, test, or production.
LOG_LEVELfrontend.logLevelinfoPino log level