Skip to content

How to Run Commercial API Locally

Prerequisites

  • Node.js ≤22.4.x (see .nvmrc for version)
  • Yarn 1.22.x (Classic)
  • Docker & Docker Compose – for Postgres, Redis, and optional full-stack run

Quick Start

1. Install Dependencies

cd CREDCommercial
yarn install

2. Environment Setup

Create a .env file in the project root. You can copy from .env.example and add the variables below. For secrets and full env reference, see the 1Password Commercial API env item.

# Database (used when app connects to Docker Postgres)
DATABASE_URL=postgres://cred@db:5432/cred_commercial
PG_DATABASE_PORT=5432

# Redis
REDISCLOUD_URL=redis://commercial_cache:6379
API_REDIS_PORT=6379

# Application
NODE_ENV=development
PORT=8000
WEB_PORT=8000
WEB_DEBUG_PORT=9222

# GraphQL Router (if using with_federation profile)
GRAPHQL_ROUTER_PORT=4000

# Model API (points to dev – already set correctly in .env.example / 1Password)
CRED_MODEL_API_URL=https://model-api-dev.credplatform.com/graphql

# Auth (optional for local dev)
JWT_SECRET=your-local-dev-secret
OKTA_AUTH_CALLBACK_ENDPOINT=http://localhost:8000/okta/auth/callback
CRED_COMMERCIAL_WEB_LOGIN_PAGE=http://localhost:8002/signin

Start Postgres, Redis, and the Commercial API in containers:

docker compose up

Equivalent to yarn dev. The web container runs nodemon inside Docker, so the app restarts automatically when you edit src/ files.

With a clean rebuild:

docker compose up --build
# or
yarn dev:rebuild

The API runs at http://localhost:8000/graphql.

4. Database Setup

To get the database working (fresh setup or reset), run:

When using full Docker – inside the web container:

docker compose run --rm web yarn reset

When running the app on the host – set DATABASE_URL=postgres://cred@localhost:5432/cred_commercial and run:

yarn reset

yarn reset does: build → drop cache → drop DB → migrate → seed.
For incremental migrations only (no wipe), use yarn prep-db instead.

Run Modes

Full Docker (docker compose up)

  • Postgres, Redis, and the web app run in Docker.
  • The web container runs nodemon internally – edits to src/ trigger automatic restarts.
  • App listens on http://localhost:8000.
  • Debug port: 9222 (e.g. localhost:9222).

App on Host, DB + Redis in Docker

Useful for debugging or development without running the app in Docker:

# Start only Postgres and Redis
docker compose up -d db redis

# Point .env to localhost
# DATABASE_URL=postgres://cred@localhost:5432/cred_commercial
# REDISCLOUD_URL=redis://localhost:6379

# Build and run the app
yarn build
yarn migrate
yarn seed
yarn nodemon

The API will be at http://localhost:8000/graphql.

GraphQL Router (Federation)

To run with the Apollo GraphQL Router:

docker compose --profile with_federation up

GraphQL Router: http://localhost:4000
Commercial API: http://localhost:8000

Trino (BigQuery / analytics)

To include Trino:

docker compose --profile with_trino up

Model API

The Commercial API uses the CRED Model API for AI features. When running Commercial locally, it connects to the dev Model API. The .env file (from .env.example or 1Password) already includes the correct CRED_MODEL_API_URL. No extra setup is required.

Useful Commands

Command Description
docker compose up Start full stack (Postgres, Redis, API with hot reload)
yarn dev Same as docker compose up
yarn dev:rebuild Rebuild containers and start
yarn nodemon Run app with hot reload (when app runs on host, not in Docker)
yarn reset Reset DB: build, drop cache, drop db, migrate, seed
yarn prep-db Build, migrate, seed (no drop – incremental)
yarn migrate Run migrations
yarn seed Run seeds
yarn start:worker Background workers (Merge/Polytomic webhooks, etc.)
yarn start:nylas-worker Nylas webhook workers

Endpoints

Service URL
GraphQL API http://localhost:8000/graphql
GraphQL Playground http://localhost:8000/graphql
GraphQL Router http://localhost:4000 (with with_federation)
Debug port localhost:9222
Prometheus metrics http://localhost:8001/prometheus/metrics

Troubleshooting

Database connection refused

  • Ensure Postgres and Redis are running: docker compose ps
  • With app on host: DATABASE_URL=postgres://cred@localhost:5432/cred_commercial, REDISCLOUD_URL=redis://localhost:6379

Model API errors

  • Ensure CRED_MODEL_API_URL in .env points to https://model-api-dev.credplatform.com/graphql

Port conflicts

  • Override ports in .env: WEB_PORT, PG_DATABASE_PORT, API_REDIS_PORT

Clean reset

yarn clean
docker compose down -v
docker compose up --build
# Then: docker compose run --rm web yarn reset