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.

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 file of the Helm chart template.

Backend

Variable	Helm Value Name	Default	Description
ADMIN_PORT	backend.port.admin	3001	Admin API GraphQL Server port
AUTH_SERVER_GRANT_URL		undefined	endpoint on the Open Payments Auth Server to request a grant
AUTH_SERVER_INTROSPECTION_URL		undefined	endpoint on the Open Payments Auth Server to introspect an access token
AUTO_PEERING_SERVER_PORT		3005	If auto-peering is enabled, its server will use this port
CONNECTOR_PORT	backend.port.connector	3002	port of the ILP connector for for sending packets over ILP over HTTP
DATABASE_URL	backend.postgresql.host, backend.postgresql.port, backend.postgresql.username, backend.postgresql.database, backend.postgresql.password	postgresql://postgres:password@localhost:5432/development	Postgres database URL of database storing the resource data; For Helm, these components are provided individually.
ENABLE_AUTO_PEERING		false	Flag to enable auto peering. View documentation.
ENABLE_SPSP_PAYMENT_POINTERS		true	enables SPSP route
EXCHANGE_RATES_LIFETIME	backend.lifetime.exchangeRate	15_000	time in milliseconds the exchange rates provided by the ASE via the EXCHANGE_RATES_URL are valid for
EXCHANGE_RATES_URL	backend.serviceUrls.EXCHANGE_RATES_URL	undefined	endpoint on the Account Servicing Entity to request exchange rates
GRAPHQL_IDEMPOTENCY_KEY_TTL_MS	backend.idempotencyTTL	86400000	TTL in milliseconds for idempotencyKey on GraphQL mutations (Admin API). Default: 24hrs
GRAPHQL_IDEMPOTENCY_KEY_LOCK_MS		2000	TTL in milliseconds for idempotencyKey concurrency lock on GraphQL mutations (Admin API)
ILP_ADDRESS	backend.ilp.address	undefined	ILP address of this Rafiki instance
ILP_CONNECTOR_URL		undefined	The ILP connector address where ILP packets are received. Communicated during auto-peering
INCOMING_PAYMENT_EXPIRY_MAX_MS		2592000000	Maximum milliseconds into the future incoming payments expiry can be set to on creation. Default: 30 days
INCOMING_PAYMENT_WORKERS	backend.workers.incomingPayment	1	number of workers processing incoming payment requests
INCOMING_PAYMENT_WORKER_IDLE	backend.workerIdle	200	time in milliseconds that INCOMING_PAYMENT_WORKERS will wait until they check an empty incoming payment request queue again
INSTANCE_NAME		undefined	this Rafiki instance’s name used to communicate for auto-peering
KEY_ID	backend.key.id	undefined	this Rafiki instance’s client key id
LOG_LEVEL	backend.logLevel	info	Pino Log Level
MAX_OUTGOING_PAYMENT_RETRY_ATTEMPTS		5	Maximum number of retry attempts for an outgoing payment before it is considered failed
NODE_ENV	backend.nodeEnv	development	node environment, development, test, or production
OPEN_PAYMENTS_PORT	backend.port.openPayments	3003	port of the Open Payments resource server port
OPEN_PAYMENTS_URL	backend.serviceUrls.OPEN_PAYMENTS_URL	undefined	public endpoint of this Open Payments Resource Server
OUTGOING_PAYMENT_WORKERS	backend.workers.outgoingPayment	4	number of workers processing outgoing payment requests
OUTGOING_PAYMENT_WORKER_IDLE	backend.workerIdle	200	time in milliseconds that OUTGOING_PAYMENT_WORKERS will wait until they check an empty outgoing payment request queue again
PRIVATE_KEY_FILE	backend.key.file	undefined	the path to this Rafiki instance’s client private key
QUOTE_LIFESPAN	backend.lifetime.quote	5 * 60_000	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
REDIS_URL	backend.redis.host, backend.redis.port	redis://127.0.0.1:6379	Redis URL of database handling ILP packet data URL; For Helm, these components are provided individually.
SIGNATURE_SECRET	backend.quoteSignatureSecret	undefined	secret to generate request header signatures for webhook event requests
SIGNATURE_VERSION		1	version number to generate request header signatures for webhook event requests
SLIPPAGE	backend.ilp.slippage	0.01	accepted ILP rate fluctuation, default 1%
STREAM_SECRET	backend.ilp.streamSecret	undefined	seed secret to generate shared STREAM secrets
TIGERBEETLE_CLUSTER_ID		0	Tigerbeetle cluster ID picked by the system that starts the TigerBeetle cluster to create a Tigerbeetle client
TIGERBEETLE_REPLICA_ADDRESSES		3004	Tigerbeetle replica addresses for all replicas in the cluster, which are comma separated IP addresses/ports, to create a Tigerbeetle client
TRUST_PROXY		false	flag to use X-Forwarded-Proto header to determine if connections is secure
USE_TIGERBEETLE		true	flag - use TigerBeetle or Postgres for accounting
WALLET_ADDRESS_DEACTIVATION_PAYMENT_GRACE_PERIOD_MS		86400000	time in milliseconds into the future to set expiration of open incoming payments when deactivating wallet address. Default: 1 days
WALLET_ADDRESS_LOOKUP_TIMEOUT_MS		1500	time in milliseconds the ASE has to create a missing wallet address until timeout
WALLET_ADDRESS_POLLING_FREQUENCY_MS		100	frequency of polling while waiting for ASE to create a missing wallet address
WALLET_ADDRESS_URL	backend.serviceUrls.WALLET_ADDRESS_URL	http://127.0.0.1:3001/.well-known/pay	this Rafiki instance’s internal wallet address
WALLET_ADDRESS_WORKERS	backend.workers.walletAddress	1	number of workers processing wallet address requests
WALLET_ADDRESS_WORKER_IDLE	backend.workerIdle	200	time in milliseconds that WALLET_ADDRESS_WORKERS will wait until they check an empty wallet address request queue again
WEBHOOK_MAX_RETRY	backend.webhookMaxRetry	10	maximum number of times Rafiki backend retries sending a certain webhook event to the configured WEBHOOK_URL
WEBHOOK_TIMEOUT	backend.lifetime.webhook	2000	milliseconds
WEBHOOK_URL	backend.serviceUrls.WEBHOOK_URL	undefined	endpoint on the Account Servicing Entity that consumes webhook events
WEBHOOK_WORKERS	backend.workers.webhook	1	number of workers processing webhook events
WEBHOOK_WORKER_IDLE	backend.workerIdle	200	time in milliseconds that WEBHOOK_WORKERS will wait until they check an empty webhook event queue again
WITHDRAWAL_THROTTLE_DELAY	backend.withdrawalThrottleDelay	undefined	delay in liquidity withdrawal processing
ENABLE_MANUAL_MIGRATIONS	backend.enableManualMigrations	false	When set to true, user needs to run database manually with command npm run knex -- migrate:latest --env production

Auth

Variable	Helm Value Name	Default	Description
ACCESS_TOKEN_DELETION_DAYS	auth.accessToken.deletionDays	30	days until expired or revoked access tokens are deleted
ACCESS_TOKEN_EXPIRY_SECONDS	auth.accessToken.expirySeconds	10 * 60	expiry time in seconds for access tokens (default: 10 minutes)
ADMIN_PORT	auth.port.admin	3003	Admin API GraphQL Server port
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	Postgres database URL of database storing the grant data; For Helm, these components are provided individually.
AUTH_PORT	auth.port.auth	3006	port of this Open Payments Auth Server
AUTH_SERVER_URL			Public endpoint for this Rafiki instance’s public Open Payment routes.
COOKIE_KEY	auth.cookieKey		koa KeyGrip key that is used to sign cookies for an interaction session
DATABASE_CLEANUP_WORKERS	auth.workers.cleanup	1	number of workers processing expired or revoked access tokens
IDENTITY_SERVER_URL	auth.identityServer.domain		endpoint of the identity server controlled by the Account Servicing Entity
IDENTITY_SERVER_SECRET	auth.identityServer.secret		API key to fetch the identity server endpoint
INCOMING_PAYMENT_INTERACTION	auth.interaction.incomingPayment	false	flag - incoming payments grant requests are interactive or not
INTERACTION_EXPIRY_SECONDS	auth.interactionExpirySeconds	600	time in seconds for which a user can interact with a grant request
INTERACTION_PORT	auth.port.interaction	3009	Port number for the interaction APIs
INTROSPECTION_PORT	auth.port.introspection	3007	port of this Open Payments Auth - Token Introspection Server
LIST_ALL_ACCESS_INTERACTION		true	Specify whether grant requests including a list-all action should require interaction. In these requests, the client asks to list resources that they themselves did not create.
LOG_LEVEL	auth.logLevel	info	Pino Log Level
NODE_ENV	auth.nodeEnv	development	node environment, development, test, or production
QUOTE_INTERACTION	auth.interaction.quote	false	flag - quote grants are interactive or not
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
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.
TRUST_PROXY		false	flag to use X-Forwarded-Proto header to determine if connections is secure
WAIT_SECONDS	auth.grant.waitSeconds	5	wait time included in grant request response (grant.continue)
ENABLE_MANUAL_MIGRATIONS	auth.enableManualMigrations	false	When set to true, user needs to run database manually with command npm run knex -- migrate:latest --env production

Frontend

Variable	Helm Value Name	Default	Description
GRAPHQL_URL	frontend.serviceUrls.GRAPHQL_URL	undefined	URL for the GraphQL Admin API and it’s required
OPEN_PAYMENTS_URL	frontend.serviceUrls.OPEN_PAYMENTS_URL	undefined	Open Payments API Endpoint and it’s required
PORT	frontend.port	3005	Port from which to host the Remix app
ENABLE_INSECURE_MESSAGE_COOKIE		true	Values of true, t, 1 will not use a secure message cookie which is required for flash messages to work over http. When not set, the secure flag is set to true.