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
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
Variable | Helm value name | Default | Description |
---|---|---|---|
AUTH_SERVER_GRANT_URL | backend.serviceUrls.AUTH_SERVER_GRANT_URL | undefined | The endpoint on your Open Payments authorization server to grant a request. |
AUTH_SERVER_INTROSPECTION_URL | backend.serviceUrls.AUTH_SERVER_INTROSPECTION_URL | undefined | The endpoint on your Open Payments authorization server to introspect an access token. |
DATABASE_URL | backend.postgresql.host ,backend.postgresql.port ,backend.postgresql.username ,backend.postgresql.database ,backend.postgresql.password | postgresql://postgres:password@localhost:5432/development | The Postgres database URL of the database storing your resource data. For Helm, these components are provided individually. |
EXCHANGE_RATES_URL | backend.serviceUrls.EXCHANGE_RATES_URL | undefined | The endpoint your Rafiki instance uses to request exchange rates. |
ILP_ADDRESS | backend.ilp.address | undefined | The ILP address of your Rafiki instance. |
ILP_CONNECTOR_URL | backend.ilp.connectorUrl | undefined | The ILP connector address where ILP packets are received. |
KEY_ID | backend.key.id | undefined | Your Rafiki instance’s client key ID. |
OPEN_PAYMENTS_URL | backend.serviceUrls.OPEN_PAYMENTS_URL | undefined | The public endpoint of your Open Payments resource server. |
REDIS_URL | backend.redis.host ,backend.redis.port | redis://127.0.0.1:6379 | The Redis URL of the database handling ILP packet data. For Helm, these components are provided individually. |
USE_TIGERBEETLE | backend.use.tigerbeetle | true | When true , a TigerBeetle database is used for accounting. When false , a Postgres database is used. |
WEBHOOK_URL | backend.serviceUrls.WEBHOOK_URL | undefined | Your endpoint that consumes webhook events. |
Conditionally required
Variable | Helm value name | Default | Description |
---|---|---|---|
INSTANCE_NAME | backend.instance.name | undefined | Your Rafiki instance’s name used to communicate for auto-peering and/or telemetry. Required when auto-peering and/or telemetry is enabled |
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.autoPeering.serverPort | 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.enable.autoPeering | false | When true , auto-peering is enabled. |
ENABLE_MANUAL_MIGRATIONS | backend.enableManualMigrations | false | When true , you must run the database manually with the command npm run knex – migrate:latest –env production |
ENABLE_SPSP_PAYMENT_POINTERS | backend.enable.spspPaymentPointers | true | When true , the SPSP route is enabled. |
ENABLE_TELEMETRY | undefined | false | Enables the telemetry service on Rafiki. |
ENABLE_TELEMETRY_TRACES | undefined | false | N/A |
EXCHANGE_RATES_LIFETIME | backend.lifetime.exchangeRate | 15_000 | The time, in milliseconds, the exchange rates you provide via the EXCHANGE_RATES_URL are valid. |
GRAPHQL_IDEMPOTENCY_KEY_LOCK_MS | backend.idempotency.keyLockMs | 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 (24 hours) | 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 | backend.incomingPayment.expiryMaxMs | 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 | development | The type of node environment: development , test , or production . |
OPEN_PAYMENTS_PORT | backend.port.openPayments | 3003 | 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 | 4 | The number of workers processing outgoing payment requests. |
POLL_INCOMING_PAYMENT_CREATED_WEBHOOK | undefined | false | N/A |
PRIVATE_KEY_FILE | backend.key.file | undefined | The path to your Rafiki instance’s client private key. |
QUOTE_LIFESPAN | backend.lifetime.quote | 5 * 60_000 (5 minutes) | The time, in milliseconds, an Open Payments quote is valid for. |
REDIS_TLS_CA_FILE_PATH | backend.redis.tlsCaFile | '' | Redis TLS config |
REDIS_TLS_CERT_FILE_PATH | backend.redis.tlsCertFile | '' | Redis TLS config |
REDIS_TLS_KEY_FILE_PATH | backend.redis.tlsKeyFile | '' | Redis TLS config |
SIGNATURE_SECRET | backend.quoteSignatureSecret | undefined | The secret to generate request header signatures for webhook event requests. |
SIGNATURE_VERSION | backend.signatureVersion | 1 | The version number to generate request header signatures for webhook events. |
SLIPPAGE | backend.ilp.slippage | 0.01 (1%) | The accepted ILP rate fluctuation. |
STREAM_SECRET | backend.ilp.streamSecret | undefined | 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 |
TRUST_PROXY | backend.trustProxy | false | When true , the X-Forwarded-Proto header is used to determine if connections are secure. |
WALLET_ADDRESS_DEACTIVATION_PAYMENT_GRACE_PERIOD_MS | backend.walletAddress.deactivationPaymentGratePeriodMs | 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 | backend.walletAddress.lookupTimeoutMs | 1500 | The time, in milliseconds, you have to create a missing wallet address before timeout. |
WALLET_ADDRESS_POLLING_FREQUENCY_MS | backend.walletAddress.pollingFrequencyMs | 100 | The frequency of polling while waiting for you to create a missing wallet address. |
WALLET_ADDRESS_URL | backend.serviceUrls.WALLET_ADDRESS_URL | 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.walletAddress | 1 | The number of workers processing wallet address requests. |
WEBHOOK_MAX_RETRY | backend.webhookMaxRetry | 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 | 2000 (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_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 | undefined | The delay in liquidity withdrawal processing. |
Auth
Required
Variable | Helm value name | Default | Description |
---|---|---|---|
AUTH_DATABASE_URL | auth.postgresql.host ,auth.postgresql.port ,auth.postgresql.username ,auth.postgresql.database ,auth.postgresql.password | postgresql://postgres:password@localhost:5432/auth_development | The URL of the Postgres database storing your Open Payments grant data. For Helm, these components are provided individually. |
AUTH_SERVER_URL | auth.server.domain | undefined | The public endpoint for your Rafiki instance’s public Open Payments routes. |
COOKIE_KEY | auth.cookieKey | undefined | The koa KeyGrip key that is used to sign cookies for an interaction session. |
IDENTITY_SERVER_URL | auth.identityServer.domain | undefined | The specific URL of your identity provider’s user-facing consent screen. |
IDENTITY_SERVER_SECRET | auth.identityServer.secret | undefined | The API key for fetching your identity (IdP) server endpoint. |
REDIS_URL | auth.redis.host ,auth.redis.port | redis://127.0.0.1:6379 | The connection URL for Redis. For Helm, these components are provided individually. |
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 | auth.adminApi.signatureVersion | 1 | The version of the request signing algorithm used to generate signatures. |
ADMIN_API_SIGNATURE_TTL_SECONDS | auth.adminAPI.signatureTtlSeconds | 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 | auth.enableManualMigrations | 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 | auth.interactionExpirySeconds | 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. |
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 | development | 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 | auth.redis.tlsCaFile | '' | Redis TLS config |
REDIS_TLS_CERT_FILE_PATH | auth.redis.tlsCertFile | '' | Redis TLS config |
REDIS_TLS_KEY_FILE_PATH | auth.redis.tlsKeyFile | '' | Redis TLS config |
TRUST_PROXY | auth.trustProxy | false | When true , the X-Forwarded-Proto header is used to determine if connections are secure. |
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 | undefined | URL for Rafiki’s GraphQL Auth Admin API |
OPEN_PAYMENTS_URL | frontend.serviceUrls.OPEN_PAYMENTS_URL | undefined | Your Open Payments API endpoint |
PORT | frontend.port | undefined | 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 | frontend.authEnabled | true | When true , only authenticated users can be granted access to Rafiki Admin by an administrator |
SIGNATURE_SECRET | frontend.quoteSignatureSecret | undefined | The signature secret used to authenticate requests to the Backend Admin API. |
SIGNATURE_VERSION | frontend.signatureVersion | 1 | The signature version number used to authenticate requests to the Backend Admin API. |
ENABLE_INSECURE_MESSAGE_COOKIE | frontend.enableInsecureMessageCookie | 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 | info | Pino log level |