Skip to main content

Getting Started

The overall process for installing and configuring the Universal Connect Widget is as follows:

  1. Clone the repo to install the widget application and server and install dependencies.
  2. Configure docker in the environment variables.
  3. Add credentials for each data provider for authentication in the environment variables.
  4. Configure your preferences for routing.
  5. Run the server via docker or node to see the Universal Connect Widget UI.

Before You Begin​

Before you begin complete the following:

  • Set up accounts with your data providers. Note that these providers require that you have a contract to access their production APIs. Once you have access to these accounts, access the data providers API credentials.

  • MX: https://dashboard.mx.com/sign_up

    • API Key
    • Client ID
    • Note: MX requires that your IP address(es) be approved and added to their allow-list, prior to being able to connect. This can be done in their dashboard. For more information, review their documentation.

  • Sophtron: https://sophtron.com/Account/Register

    • UserId
    • AccessKey

  • Ensure you have the correct skills and access to the tools listed in the Assumptions section.

Assumptions​

You should have an understanding of the following topics:

  • Consuming external Open Finance services for connectivity and aggregation
  • Configuring your servers to consume connectivity and aggregation
  • Using git
  • Using docker and docker Compose
  • Using docker containers
  • Using Node.js and npm (https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
  • Securing your servers
  • Securing your API keys and configurations
  • Compliance with your institution’s security requirements and the requirements of your security auditing entity

Docker​

Docker is required for both development and production. Compatible options include both Docker Desktop and Rancher Desktop. You don't need the desktop version of docker for this project but it does require a docker-compatible container client. Not all clients have been tested at this time.

Docker Images​

The images for the ucw-app repository are available on Dockerhub. For more information on specifying versions, review this information.

Common Docker Commands for Testing​

Use the following commands to test the docker images. They are not normally ran separately, and instead are ran together, using the docker compose up command. However, there are times when you may want to test the individual docker images to make sure they are working as expected or to debug issues.

Server​

docker build -f ./docker-server.Dockerfile -t ucw-app-server-cli --build-arg APP=server .
docker run --name ucw-app-server-cli -p 8080:8080 --env-file ./apps/server/.env -t ucw-app-server-cli

UI​

docker build -f ./docker-ui.Dockerfile -t ucw-app-ui-cli --build-arg APP=ui .
docker run --name ucw-app-ui-cli -p 5137:5137 -e UI_PORT=5137 -t ucw-app-ui-cli

Testing with Docker Compose​

While developing the UCW with docker compose, using --pull never ensures that the docker images used are always local, and not from dockerhub. This ensures that your local changes can be tested.

docker compose up --pull never

Docker Troubleshooting​

If you get an error such as failed to authorize, or failed to fetch oauth token, or a 401 Unauthorized, you may have logged-in previously with a docker login (via cli), and your auth has expired.

You do not need a docker login to pull the UCW docker images, but if you have stale tokens, docker will try to use them, thus resulting in the error. To fix this, you will need to run docker logout from your terminal, prior to running docker compose up.

Installation​

  1. Clone the UCP repository, either by downloading the ZIP file (https://github.com/Universal-Connect-Project/ucw-app/archive/refs/heads/main.zip) OR by running the command:
  2. git clone https://github.com/Universal-Connect-Project/ucw-app.git
  3. Navigate to the root project: cd ucw-app
  4. Install dependencies: npm ci