Welcome to the OpenBanking Gateway project. This guide provides detailed instructions for setting up the web and server services using pnpm in a mono-repository structure.
You can choose to run this on your local environment or using Docker/Docker Compose. Docker is the preferred method for ease of setup and consistency as all dependencies are defined within the docker-compose configuration file.
For a rapid deployment, bypass manual configuration steps 1 through 4 by executing the setup script below. This script automates the cloning of the OpenBanking Gateway repository, the setup of necessary environment variables, and the initiation of the Docker containers.
Execute the following command in your terminal:
curl -fsSL raw.githubusercontent.com/openbankingnigeria/obn-gateway/main/install.sh -o install.sh && sh install.sh
cd obn-gatewayConfirm your Docker version is v23.0 or higher
Start by cloning the OpenBanking Gateway repository:
git clone https://github.com/openbankingnigeria/obn-gateway
cd obn-gateway - For a quick start, you can use the provided
.env.examplefile as is, using this command:
cp .env.example .env .envfile would be created in the root of the project folder you have cloned- Update these variables on the
.envto configure the app for your specific environment. At a minimum, you'll need to provide values for the following variables: COMPANY_NAME- This is your institution nameDEFAULT_EMAIL- This is the root email you would be logging into the platform with when the application is deployedDEFAULT_PASSWORD- This is the root password you be logging into the platform with when the application is deployedJWT_SECRET- This can be any random secure value you choose
Important: Don't use default credentials for production.
Additional environment variables are defined in the .env.example file and can be customized as necessary for your setup.
To launch the services using Docker Compose, run the following command:
docker compose --profile "*" up -d --build --force-recreate This command will set up the web and server services along with other dependencies like Kong, Elasticsearch, Logstash, and MySQL.
Configure your email service if you have one, you'll need to update the env variables with respect to the chosen email service.
Alternatively, in cases where you don't have a running email server, you can use maildev for development purposes only.
To run maildev using Docker:
docker run -d \
--name maildev.net \
-p 3007:3007 \
-p 1080:80 \
-e MAILDEV_SMTP_PORT=${EMAIL_PORT} \
-e MAILDEV_USER=${EMAIL_USER} \
-e MAILDEV_PASS=${EMAIL_PASSWORD} \
--network obn-net \
maildev/maildev bin/maildev --web 80 --smtp 3007Visit http://localhost:1080 to view all messages sent from the application.
To verify that the installation was successful, check that all Docker containers are in a 'healthy' status:
docker ps Ensure each container's STATUS is healthy.
-
Backend Service: Exposes the management application APIs, available on port 4000 by default. e.g. http://localhost:4000
-
Web App: Exposes the management application interface, available on port 3000 by default. e.g. http://localhost:3000
-
Kong: Exposes the API gateway APIs, available on ports 8000 (development) and 8100 (production) by default. e.g. http://localhost:8000 or e.g. http://localhost:8100
-
Logstash: Collects logs from the Kong service.
-
Elastic Service: Provides search and analytics on logs from Kong.
Ensure the below dependencies are available on the applicable environment:
- Node.js (v18 or higher)
- MySQL (v8)
- Kong (v3.5.0 or higher)
- Elasticsearch (v8.11.1 or higher)
- Logstash (v8.11.1 or higher)
Start by cloning the OpenBanking Gateway repository:
git clone https://github.com/openbankingnigeria/obn-gateway
cd obn-gateway Same as step 3 for Docker installation
Same as step 4 for Docker installation
If you prefer to set up the project locally, install and run the project dependencies locally using pnpm:
pnpm install
pnpm dev Same as step 7 for Docker installation
If you encounter any problems, check the Docker container logs for any errors:
docker compose --profile "*" logs Most issues can be resolved by reviewing the logs. If problems persist, consult the project documentation or seek help from the community.