Skip to content

Commit 9f95965

Browse files
PaulGregoryBakerPaulGregoryBaker
authored
Merge pull request #27 from infitx-org/PM4ML_docs
IME-344: Document the PM4ML onboarding process
2 parents d4d6f35 + 27c2a4b commit 9f95965

40 files changed

+1434
-0
lines changed

‎.vuepress/config.js

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,10 @@ export default defineUserConfig({
3232
text: 'Technical Integration Guide',
3333
link: '/md-docs/TechnicalIntegration',
3434
},
35+
{
36+
text: 'Deployment',
37+
link: '/md-docs/PM4ML_Docs/Overview',
38+
},
3539
{
3640
text: 'Technical Reference',
3741
link: '/md-docs/Service',
@@ -76,6 +80,38 @@ export default defineUserConfig({
7680
'ISO20022AndMerchantPayments.md'
7781
]
7882
},
83+
{
84+
text: 'Deployment',
85+
collapsible: true,
86+
children: [
87+
{
88+
text: 'Overview',
89+
link: '/md-docs/PM4ML_Docs/Overview.md'
90+
},
91+
{
92+
text: 'Docker Compose',
93+
collapsible: true,
94+
children: [
95+
'/md-docs/PM4ML_Docs/Guide.md',
96+
'/md-docs/PM4ML_Docs/CoreConnectorSetup.md',
97+
'/md-docs/PM4ML_Docs/DeployingDockerComposePayment.md',
98+
'/md-docs/PM4ML_Docs/ConfiguringACustomCoreConnector.md',
99+
'/md-docs/PM4ML_Docs/connectToLiveHub.md',
100+
'/md-docs/PM4ML_Docs/SecuringTheDockerDaemon.md',
101+
'/md-docs/PM4ML_Docs/firewallConfig.md',
102+
'/md-docs/PM4ML_Docs/TestTransfer.md'
103+
]
104+
},
105+
// {
106+
// text: 'Kubernetes',
107+
// collapsible: true,
108+
// children: [
109+
// Add Kubernetes-related docs here, e.g.:
110+
// '/md-docs/PM4ML_Docs/KubernetesGuide.md'
111+
// ]
112+
// }
113+
114+
]},
79115
{
80116
text: 'Technical Reference',
81117
collapsible: true,

‎md-docs/PM4ML_Docs/ConfiguringACustomCoreConnector.md

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Configuring the core connectors
2+
## Objective
3+
This guide documents the step-by-step process of:
4+
- Configuring the core connector service using profile-based deployment for production-ready DFSP implementations
5+
- Creating a custom configuration for managing shared environment variables used by all core connectors (MNOs, Banks, etc)
6+
- Utilizing docker-compose profiles for clean and maintainable deployments
7+
8+
### Step 1: Configuring sim-backend to use a Core Connector
9+
#### **Background:**
10+
The docker-compose architecture now supports profile-based deployments with dedicated services:
11+
- **`core-connector`**: Production-ready service for real DFSP implementations
12+
- **`portal`**: Payment manager portal UI
13+
14+
Both services can use the same core connector images but are deployed with different profiles for better service organization and deployment flexibility.
15+
#### **Action Taken:**
16+
- Add the core connector image (CORE_CONNECTOR_IMAGE) and tag (CORE_CONNECTOR_TAG) in the .env file docker-compose/.env
17+
```sh
18+
GET_SERVICES_FXP_RESPONSE= # e.g, test-fxp
19+
PM4ML_ENABLED=true
20+
SUPPORTED_CURRENCIES= # e.g., MWK
21+
22+
## Sim Backend
23+
CORE_CONNECTOR_IMAGE= # e.g, mojaloop/fsp-ug-core-connector
24+
CORE_CONNECTOR_TAG= # e.g, v1.25.0
25+
```
26+
- Create a separate `core-connector-config.env` file to configure the core connector environment variables. This file is used by the core-connector service when running as a production core connector.
27+
- The docker-compose.yaml file now supports profile-based deployments with dedicated services:
28+
**Core Connector Service (Production)**:
29+
```yaml
30+
core-connector:
31+
image: ${CORE_CONNECTOR_IMAGE:-mojaloop/ml-testing-toolkit}:${CORE_CONNECTOR_TAG:-v18.5.1}
32+
profiles:
33+
- core-connector
34+
env_file:
35+
- core-connector-config.env
36+
ports:
37+
- "3003:3003"
38+
- "3004:3004"
39+
volumes:
40+
- ./core-connector-config/:/opt/app/core-connector-config/
41+
environment:
42+
# SERVER CONFIGS
43+
- DFSP_SERVER_HOST=0.0.0.0
44+
- DFSP_SERVER_PORT=3004
45+
- SDK_SERVER_HOST=0.0.0.0
46+
- SDK_SERVER_PORT=3003
47+
- DFSP_API_SPEC_FILE=./core-connector-config/core-connector-api-spec-dfsp.yml
48+
- SDK_API_SPEC_FILE=./core-connector-config/core-connector-api-spec-sdk.yml
49+
# Mojaloop Connector
50+
- SDK_BASE_URL=http://sdk-scheme-adapter:4001
51+
```
52+
**Deployment Commands**:
53+
54+
Deploy with core connector:
55+
```bash
56+
docker-compose --profile core-connector up -d
57+
```
58+
59+
Deploy with core connector and portal:
60+
```bash
61+
docker-compose --profile core-connector --profile portal up -d
62+
```
63+
64+
**UI Services Configuration**:
65+
66+
The architecture includes separate UI services for each backend type:
67+
68+
**Core Connector UI**:
69+
```yaml
70+
core-connector-ui:
71+
image: mojaloop/ml-testing-toolkit-ui:v16.0.4
72+
profiles:
73+
- core-connector
74+
ports:
75+
- "6062:6060"
76+
environment:
77+
- API_BASE_URL=http://localhost:3003
78+
- AUTH_ENABLED=FALSE
79+
```
80+
81+
The key configuration changes include:
82+
- **Profile-based deployment**: Use `--profile core-connector` and `--profile sim-backend`
83+
- **Dedicated services**: Separate `core-connector` and `sim-backend` services with different port mappings
84+
- **Separate UI services**: `core-connector-ui` (port 6062) and `sim-backend-ui` (port 6061) for better service isolation
85+
- **Environment file separation**: Core connector uses `core-connector-config.env` for configuration
86+
- **Volume mounting**: Core connector configuration files and API specifications
87+
- **Service discovery**: Internal Docker networking for service communication
88+
89+
**Service Port Mapping**:
90+
91+
| Service | Profile | Internal Port | External Port | Purpose |
92+
|---------|---------|---------------|---------------|---------|
93+
| core-connector | core-connector | 3003, 3004 | 3003, 3004 | Production backend API |
94+
| sim-backend | sim-backend | 4040, 5050 | 5052, 5051 | Development backend API |
95+
| core-connector-ui | core-connector | 6060 | 6062 | Core connector UI |
96+
| sim-backend-ui | sim-backend | 6060 | 6061 | Sim backend UI |
97+
98+
- If no core connector image is specified (CORE_CONNECTOR_IMAGE is empty), the service will default to using the ml-testing-toolkit as a core connector.
99+
100+
### Step 2: Creating the Core Connector Configuration File
101+
#### **Problem:**
102+
Each core connector requires specific configurations that need to be managed separately from the main environment variables.
103+
#### **Solution:**
104+
We create a dedicated `core-connector-config.env` file that contains all the necessary environment variables for the core connector. This file is referenced by the sim-backend service in the docker-compose configuration.
105+
### Shared/Common Variables for core-connector-config.env:
106+
| Variable | Example |
107+
|---------------------------|-------------|
108+
| FSP_ID | Identifier type (e.g., dfsp1) |
109+
| CONNECTOR_NAME | e.g.,DFSP-UG |
110+
| LEI| e.g.,dfspuganda |
111+
112+
### Shared Configuration Block for core-connector-config.env:
113+
```sh
114+
# Mojaloop Connector Config for core connector
115+
FSP_ID= #e.g., dfsp1
116+
CONNECTOR_NAME= #e.g.,DFSP-UG
117+
LEI= #e.g.,dfspuganda
118+
```
119+
120+
### Step 3: Customizing DFSP-Specific Configuration Variables
121+
The following variables are provided as a sample and should be added to the `core-connector-config.env` file. Each DFSP requires unique values:
122+
| Variable | Example |
123+
|---------------------------|-------------|
124+
| BASE_URL | sandbox.com |
125+
| COLLECTION_API_KEY | |
126+
| COLLECTION_CLIENT_ID | |
127+
| COLLECTION_SUBSCRIPTION_KEY | |
128+
| DISBURSEMENT_API_KEY | |
129+
| DISBURSEMENT_CLIENT_ID | |
130+
| DISBURSEMENT_SUBSCRIPTION_KEY | |
131+
| TARGET_ENVIRONMENT | sandbox |
132+
| SUPPORTED_ID_TYPE | MSISDN |
133+
| CBS_NAME | |
134+
| X_COUNTRY | UG |
135+
| SERVICE_CHARGE | 0 |
136+
| EXPIRATION_DURATION | 1 |
137+
| HTTP_TIMEOUT | 5000 |
138+
| ENV | staging |
139+
| DFSP_CURRENCY | UGX |
140+
141+
### DFSP-Specific Configuration Block for core-connector-config.env:
142+
```sh
143+
# These are only provided as sample
144+
BASE_URL= #e.g.,sandbox.com
145+
COLLECTION_API_KEY= #e.g.,b1207baca1d343b581cc21346904c707
146+
COLLECTION_CLIENT_ID= #e.g.,c87a6e02-aa8c-4eaf-827a-d5d90e744241
147+
COLLECTION_SUBSCRIPTION_KEY= #e.g.,5f40c404bf0c4e4f9b37e533d4993dd7
148+
DISBURSEMENT_API_KEY= #e.g.,1188de4fcff9436f826cd1151985d7fe
149+
DISBURSEMENT_CLIENT_ID= #e.g.,980fa27a-16dc-4432-b589-7733a02008cf
150+
DISBURSEMENT_SUBSCRIPTION_KEY= #e.g.,85ce32bfcd8a44aaab993ebac601ff46
151+
TARGET_ENVIRONMENT= #e.g.,sandbox
152+
SUPPORTED_ID_TYPE= #e.g.,MSISDN
153+
CBS_NAME= #e.g.,FSP
154+
X_COUNTRY= #e.g.,UG
155+
X_CURRENCY= #e.g.,EUR
156+
SERVICE_CHARGE= #e.g.,0
157+
EXPIRATION_DURATION= #e.g.,1
158+
HTTP_TIMEOUT= #e.g.,5000
159+
ENV= #e.g.,staging
160+
DFSP_CURRENCY= #e.g.,UGX
161+
```
162+
### Final core-connector-config.env Configuration
163+
Here is what the complete `core-connector-config.env` file should look like:
164+
```sh
165+
# Mojaloop Connector Config for core connector
166+
FSP_ID= #e.g., dfsp
167+
CONNECTOR_NAME= #e.g.,DFSP-UG
168+
LEI= #e.g.,dfspuganda
169+
## DFSP-Specific Config - env variables can change as per the core connector being used
170+
# These are only provided as sample
171+
BASE_URL= #e.g.,sandbox.com
172+
COLLECTION_API_KEY= #e.g.,b1207baca1d343b581cc21346904c707
173+
COLLECTION_CLIENT_ID= #e.g.,c87a6e02-aa8c-4eaf-827a-d5d90e744241
174+
COLLECTION_SUBSCRIPTION_KEY= #e.g.,5f40c404bf0c4e4f9b37e533d4993dd7
175+
DISBURSEMENT_API_KEY= #e.g.,1188de4fcff9436f826cd1151985d7fe
176+
DISBURSEMENT_CLIENT_ID= #e.g.,980fa27a-16dc-4432-b589-7733a02008cf
177+
DISBURSEMENT_SUBSCRIPTION_KEY= #e.g.,85ce32bfcd8a44aaab993ebac601ff46
178+
TARGET_ENVIRONMENT= #e.g.,sandbox
179+
SUPPORTED_ID_TYPE= #e.g.,MSISDN
180+
CBS_NAME= #e.g.,FSP
181+
X_COUNTRY= #e.g.,UG
182+
X_CURRENCY= #e.g.,EUR
183+
SERVICE_CHARGE= #e.g.,0
184+
EXPIRATION_DURATION= #e.g.,1
185+
HTTP_TIMEOUT= #e.g.,5000
186+
ENV= #e.g.,staging
187+
DFSP_CURRENCY= #e.g.,UGX
188+
```
189+
190+
### Step 4: Testing the core connector
191+
to test the core connector:
192+
- Open ttk
193+
- go to test runner
194+
- load testing-toolkit/collections/core-connector/cc_golden_path.json
195+
- Update the env variables for the ttk using the environment manager button on the right side of the screen, near run
196+
- Load the cc_golden_path.env
197+
- Run the test
198+
199+
Verify the functionality of core connector based on this

0 commit comments

Comments
 (0)