@affixapi/integrator NPM

integrator

Intro

Deploy a self-contained service that integrates with the Affix API within your infrastructure.

Affix API follows the OAuth 2.1 specification, which makes integrating as standardised as possible; this does require you coding to our API.

We also offer a no-code solution where we can drop the extracts over SFTP or AWS S3.

Somewhere inbetween is this service, which you can deploy to your cloud and does most of the integration for you.

Quickstart (local)

git clone git@github.com:affixapi/integrator.git && cd integrator

docker login ghcr.io --username YOUR_GITHUB_USERNAME

docker compose up

The service is now running @ localhost:8080

Quickstart (prod + connect your own DB)

docker pull ghcr.io/affixapi/integrator:latest

docker run --rm -it \
  --env-file .env \
  -e DB_CXN_STR=postgres://postgres:affixapi@postgres:5432/affixapi \
  -p 8080:8080 \
  integrator:latest \
  --name integrator \
  npm start

The service is now running @ localhost:8080

environment variables

Create the .env file and edit appropriately.

cp .env.EXAMPLE .env

do note, depending if you are running the app locally or within docker, you will need to change the DB_CXN_STR

DB_CXN_STR=postgres://postgres:affixapi@localhost:5432/postgres # locally

DB_CXN_STR=postgres://postgres:affixapi@postgres:5432/postgres # in docker

export CLIENT_ID='' # your client_id for the respective environment provided for you in your onboarding document
export CLIENT_SECRET='' # your client_id for the respective environment provided for you in your onboarding document
export REDIRECT_URI='http://localhost:8080/callback' # for testing you can leave as is. for development/production environments put your real redirect url for the respective environment
export NODE_ENV=dev # dev or prod
export HOST=0.0.0.0 # interface the node server listens on. either `0.0.0.0` (for server running in docker or accepting non-local traffic) or `localhost` (for local testing)
export PORT=8080

export DB_CXN_STR='postgres://your-username:your-password@your-postgres-host:5432/affixapi' # if not using the postgres docker container
export POSTGRES_PASSWORD='your-postgres-password' # if launched via docker-compose only

dev

npm install
dev-resources/run-db # or configure your own DB with the DB_CXN_STR env var
npm run dev

dev/prod (with docker)

docker pull ghcr.io/affixapi/integrator:latest
# make sure to set the DB_CXN_STR env var the `.env` file
docker compose up

prod (without docker)

git clone git@github.com:affixapi/integrator.git && cd integrator
npm ci --production

# make sure to set the DB_CXN_STR env var

npm start

Production

You will need to deploy this within your production environment.

Two options:

use a load balancer for SSL termination, and forward request to a box hosting the service

In AWS speak, set up an Application Load Balancer (ALB), forward port 80 to port 443, and forward port 443 to either an EC2 box hosting the service, or one of the many AWS services (AWS Fargate, etc) that can host a docker container

create an SSH certificate

Next steps

Create a persistent database connection; either to your existing main database or a microservice data. Ensure that only respective teammates can access, as Affix tokens will be stored inside this DB.
Use a Key Management Service (such as AWS KMS) to store the Affix API keys in the DB as ciphertext. This ensures that even in the unlikely event of data exfiltration, the keys are not usable by non-internal team members.
Use a database connection pool