Skip to content
GitHub

Overview

The Local Playground provides a suite of packages that, together, mock an account servicing entity that has deployed Rafiki. It exposes an SPSP endpoint, the Open Payments APIs with its required GNAP auth endpoints to request grants, a STREAM endpoint for receiving Interledger packets, and the Rafiki Admin app to view and manage each Rafiki instance.

This suite of packages includes:

Package nameServices
backend
  • SPSP
  • Open Payments APIs
  • GraphQL Admin APIs
  • STREAM endpoint
authGNAP auth server
mock-account-servicing-entitymocks an account servicing entity
frontendRemix app to expose a UI for Rafiki admin management via interaction with the Backend Admin APIs

These packages depend on the following databases:

Databases required to run Rafiki

The Local Playground comes with containerized versions of the Rafiki packages and two pre-configured docker-compose files (Cloud Nine Wallet and Happy Life Bank) to start two mock account servicing entities with their respective Rafiki backend and auth servers. They automatically peer, and two to three user accounts are created on both of them.

This environment will set up a playground where you can use the Rafiki Admin APIs and the Open Payments APIs.

Running the local environment

To spin up the Local Playground install the following software on your machine:

Setup

Run the following commands from the root of the project.

Terminal window
## If you have spun up the environment before, first tear down and remove volumes!
pnpm localenv:compose down --volumes
## Otherwise start the local environment
## start the local environment
pnpm localenv:compose up

If you want to use Postgres as the accounting database instead of TigerBeetle, you must use the psql variant of the localenv:compose commands as follows:

Terminal window
## If you have spun up the environment before, first tear down and remove volumes!
## Otherwise start the local environment
pnpm localenv:compose:psql down --volumes
// start the local environment
pnpm localenv:compose:psql up

The local environment consists of a primary and secondary Rafiki instance, each with its docker-compose file (Cloud Nine Wallet, Happy Life Bank). The primary Cloud Nine Wallet docker-compose file (./cloud-nine-wallet/docker-compose.yml) includes the primary Rafiki backend and auth services, as well as the required data stores, which include TigerBeetle (if enabled), Redis, and Postgres. The primary instance contains all of the necessary components so that it can run independently.

The secondary Happy Life Bank docker-compose file (./happy-life-bank/docker-compose.yml) includes only the Rafiki services, not the data stores. It uses the data stores created by the primary Rafiki instance, so it can’t be run independently. The pnpm localenv:compose up command starts both the primary and secondary instances.

Environment components

The following components are made available via the Local Playground:

Overview of components

Mock account servicing entity 1 - Cloud Nine Wallet

LabelComponentURL
aUser Interfacehttp://localhost:3030
bBackend Admin APIhttp://localhost:3001/graphql
cOpen Payments APIhttp://localhost:3000
dAuth Admin APIhttp://localhost:3003/graphql
eOpen Payments Auth APIhttp://localhost:3006
fRafiki Admin UIhttp://localhost:3010
gKratos API - disabled by defaulthttp://localhost:4433

Mock account servicing entity 2 - Happy Life Bank

LabelComponentURL
hUser Interfacehttp://localhost:3031
iBackend Admin APIhttp://localhost:4001/graphql
jOpen Payments APIhttp://localhost:4000
kAuth Admin APIhttp://localhost:4003/graphql
lOpen Payments Auth APIhttp://localhost:4006
mRafiki Admin UIhttp://localhost:4010
nKratos API - disabled by defaulthttp://localhost:4432

Mail Slurper

LabelComponentURL
oMail UI - disabled by defaulthttp://localhost:4436

Database

ComponentURL
Postgres Serverhttp://localhost:5432

Rafiki Admin

Manage and view information about the Rafiki instance(s) through the Rafiki Admin application. Rafiki Admin is a Remix app for querying info and executing mutations against the Rafiki Backend Admin API.

We have secured access to Rafiki Admin using Ory Kratos; however, in our local playground setup we’ve chosen to disable user authentication for easier development and testing interactions.

Exploring Accounts on Cloud Nine Wallet

Navigate to localhost:3030 to view the accounts on Cloud Nine Wallet.

Click an account name to view a list of transactions.

Debugging

Debuggers for the services are exposed on the following ports:

ServicesIP and Port
Cloud Nine Backend127.0.0.1:9229
Cloud Nine Auth127.0.0.1.9230
Happy Life Bank Backend127.0.0.1:9231
Happy Life Bank Auth127.0.0.1:9232

Debugging with a Chromium browser:

  1. Go to chrome://inspect
  2. Click Configure and add the IP addresses and ports detailed above
  3. Start the docker containers
  4. Click Inspect on the service you want to debug to open the Chromium debugger.

You can either trigger the debugger by adding debugger statements in the code and restarting the Docker containers or by adding breakpoints directly to the Chromium debugger after starting the Docker containers.

Debugging with VS Code:

To debug with VS Code, add this configuration to your .vscode/launch.json:

The localRoot variable will depend on the location of the launch.json file relative to Rafiki’s root directory.

For more ways to connect debuggers, refer to the Node JS docs for debugging.

Shutting down

To shut down your local instance, run the following commands:

Terminal window
# tear down
pnpm localenv:compose down
# tear down and delete database volumes
pnpm localenv:compose down --volumes
# tear down, delete database volumes and remove images
pnpm localenv:compose down --volumes --rmi all

Commands

The following are the most commonly used commands:

CommandDescription
pnpm localenv:compose configShow all merged config (with TigerBeetle)
pnpm localenv:compose upStart (with TigerBeetle)
pnpm localenv:compose up -dStart (with TigerBeetle) detached
pnpm localenv:compose downDown (with TigerBeetle)
pnpm localenv:compose down —volumesDown and kill volumes (with TigerBeetle)
pnpm localenv:compose down —volumes —rmi allDown, kill volumes (with TigerBeetle) and images
pnpm localenv:compose:psql configShow all merged config (with PostgreSQL)
pnpm localenv:compose buildBuild all the containers (with TigerBeetle)
pnpm localenv:compose:psql upStart (with PostgreSQL)
pnpm localenv:compose:psql downDown (with PostgreSQL)
pnpm localenv:compose:psql down —volumesDown (with PostgreSQL) and kill volumes
pnpm localenv:compose:psql buildBuild all the containers (with PostgreSQL)
pnpm localenv:compose:adminauth upStart with local admin auth enabled (this is disabled by default)

Interacting with the Local Playground

Bruno & Open Payments APIs

The Open Payments APIs can be interacted with using the Bruno collection (resource server endpoints and auth server endpoints). To interact with the Open Payments APIs using Bruno, you must:

  1. load the collection into Bruno by clicking “Open Collection”
  2. navigating to /rafiki/bruno/collections/Rafiki on your machine and clicking “Open”
  3. Furthermore, you need to either load the Local Environment or the Remote Test Network Environment.

The Examples folder in the Bruno collection includes an Open Payments example that can be executed in the following sequence:

  1. Requests the sender’s wallet address
  2. Requests the receiver’s wallet address
  3. Requests a grant to create an incoming payment on the receiver’s account
  4. Creates an incoming payment on receiver’s account
  5. Requests a grant to create and read a quote on the sender’s account
  6. Creates a quote on the sender’s account
  7. Requests a grant to create and read an outgoing payment on the sender’s account
  1. Continues the grant request
  2. Creates an outgoing payment on the sender’s account
  3. Fetches the outgoing payment on the sender’s account

Admin APIs

In addition to using Rafiki Admin to interact with the Admin APIs, you can also use the Apollo Explorer on localhost:3001/graphql and localhost:4001/graphql for Cloud Nine Wallet and Happy Life Bank, respectively, and via the Bruno collection. The Bruno collection is configured to use the local environment’s default endpoints.

SPSP

Every wallet address also serves as an SPSP endpoint. A GET request with an Accept header application/spsp4+json will return an SPSP response with STREAM connection details. The following example uses http://localhost:3000/accounts/gfranklin as the SPSP endpoint.

Terminal window
http GET http://localhost:3000/accounts/gfranklin Host:backend Accept:application/spsp4+json
HTTP/1.1 200 OK
Connection:keep-alive
Content-Length:220
Content-Type:application/spsp4+json
Date:Thu, 23 Feb 2023 13:07:24 GMT
Keep-Alive:timeout=5
{
"destination_account":"
test.rafiki.viXmy1OVHgvmQakNjX1C6kQMri92DzHeISEv-5VzTDuFhrpsrkDzsq5OO9Lfa9yed0L2RJGC9hA_IX-zztTtTZ87shCYvsQ",
"receipts_enabled":false,
"shared_secret":"Rz_vudcg13EPs8ehL2drvZFJS1LJ4Y3EltOI60-lQ78"
}

Known issues

No data in the mock account servicing entities

It is possible that upon starting or restarting the local playground, you may run into an issue where there are no accounts and wallet addresses in the mock account service entities’ pages on http://localhost:3030 and http://localhost:3031, respectively. You can only seed the initial account data against an empty database. To seed the database with this initial data, clear the existing volumes and restart the docker containers by issuing the following commands:

TigerBeetle container exists with code 137

There is a known issue when running TigerBeetle in Docker. The container exits without logs and simply shows error code 137. To fix this, increase the Docker memory limit. If you run the local Docker playground on a Windows machine via the Windows Subsystem for Linux (WSL), you can increase the memory limit by configuring your .wslconfig file.