Skip to main content

Getting Started

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

  1. To host your own widget, fork the repo to install the widget application and server and install dependencies.
  2. Add credentials for each data provider for authentication in the environment variables.
  3. Configure your preferences for routing.
  4. Run the server via docker or node.

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

API Documentation​

First, review our API documentation. The API documentation for this service lives in openApiDocumentation.json and uses the (OpenAPI 3.0.0 spec)[https://swagger.io/specification/]. You can open it in your preferred tool such as swagger editor.

Authentication​

The UCW does not provide any authentication for its endpoints. You'll need to provide authentication between your application and the widget server such as IP Whitelisting or other options.

Installation​

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

Setting Up UCW​

To set up the Universal Connect Widget (UCW), first configure your environment variables to set up Docker and add credentials for each of your providers. The application relies on environment variables to store configuration settings and sensitive information that must be hard coded into the application such as authentication credentials. DO NOT put any credentials in any of the code files. If you do so, they may be committed and leaked to the public.

As mentioned in the Getting Started section, the images for this repository are hosted on DockerHub. First configure the version of the images you pull from DockerHub. The latest version is automatically configured.

1. Configure Docker Images​

For more information on how the project uses docker, review our README on Github.

  1. Run cp ./.env.example ./.env to copy the environment variables example to a new file .env.
  2. In this file, configure DOCKER_IMAGE_SERVER and DOCKER_IMAGE_UI to change the version of the images. [CHANGE THESE]

2. Add Data Provider Credentials​

  1. Run cp ./apps/server/.env.example ./apps/server/.env to copy the environment variables example to a new .env file.
  2. In the .apps/server/.env file, configure API credentials and secrets, ports, redis and more.

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.