Skip to main content

Get Started

This guide provides a high level overview to get started with UCW. The following details cover pre-installation considerations, forking the repo, adding credentials for each of your aggregators, configuring your preferences, and running the server.

Preinstallation​

Before using the Universal Connect Widget, you should:

  • Set up accounts with your aggregators. Note that these aggregators require that you have a contract and credentials to access their production APIs. You'll need appropriate sign-ups and credentials for your chosen aggregators.

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

    • API Key
    • Client ID
    • Note: MX requires your IP address(es) for their allow-list prior to connecting. This can be done in their dashboard. For more information, review their documentation.

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

    • UserId
    • AccessKey

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, docker Compose, and 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. You can open it in your preferred tool such as Swagger editor.

Changelog​

UCW follows Semantic Versioning. View the changelog for any updates.

Authentication​

The UCW provides optional authentication or you may provide your own. Details are available in the Authentication guide.

Setup​

The application relies on environment variables to store configuration settings and sensitive information. Do not put credentials in the code files. If you do so, they may be committed and leaked to the public.

Note: You may fork the repository or download the repository ZIP file (https://github.com/Universal-Connect-Project/ucw-app/archive/refs/heads/main.zip).

  1. Clone the ucw-app repo
  2. From the root directory, run:
    • npm ci
    • cp ./.env.example ./.env
    • cp ./apps/server/.env.example ./apps/server/.env
      • See ENVIRONMENT.md for details on what values you must provide in the ./apps/server/.env file such as API credentials for aggregators, ports to use, and more.
    • cp ./apps/server/cachedDefaults/preferences.example.json ./apps/server/cachedDefaults/preferences.json
  3. Make sure you have Docker installed (or another compatible container runtime), which is a required dependency for the institution search feature to function, even when running via Node.js. More info in available in our DOCKER readme.
  4. Finally, you can run the docker containers, or simply run from the cli, via node.
    • For docker: docker compose up
    • For node: npm run dev

The server may take a few moments to initialize and set up elasticsearch.

Once the server is running, and you will receive the following message, "Message":"App initialized successfully". The Universal Connect Widget UI will now load in a browser at http://localhost:8080/widget?job_type=aggregate&user_id=test-user-id.

Common Docker Commands​

Use the docker compose up command to start UCW. If you need debug issues, the following commands are available.

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

Troubleshooting​

If you get an error such as failed to authorize, failed to fetch oauth token, or 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. To fix this, you will need to run docker logout from your terminal, then run docker compose up.