Skip to main content

Service

Health Check​

The service offers a readiness and health check endpoint that can be configured in orchestration tools like Docker Compose and Kubernetes.

The /api/health GET endpoint returns a 200 when the service ready and healthy or a 5xx (typically 503) error if unhealthy. The response contains the current version of Jackson. For example: {"version":"1.0.0"}.

With Docker​

The docker container can be found at boxyhq/jackson. It is preferable to use a specific version instead of the latest tag.

Replace the values for DB_URL, JACKSON_API_KEYS, NEXTAUTH_SECRET and NEXTAUTH_ADMIN_CREDENTIALS with your own values before running docker run command.

docker run \
  -p 5225:5225 \
  -e DB_ENGINE="sql" \
  -e DB_TYPE="postgres" \
  -e DB_URL="postgres://postgres:postgres@postgres:5432/postgres" \
  -e JACKSON_API_KEYS="secret" \
  -e NEXTAUTH_URL="http://localhost:5225" \
  -e EXTERNAL_URL="http://localhost:5225" \
  -e NEXTAUTH_SECRET="super-secret" \
  -e NEXTAUTH_ADMIN_CREDENTIALS="[email protected]:secretpassword" \
  -d boxyhq/jackson

OR

docker run \
  -p 5225:5225 \
  -e DB_ENGINE="mongo" \
  -e DB_URL="mongodb://localhost:27017/jackson" \
  -e JACKSON_API_KEYS="secret" \
  -e NEXTAUTH_URL="http://localhost:5225" \
  -e EXTERNAL_URL="http://localhost:5225" \
  -e NEXTAUTH_SECRET="super-secret" \
  -e NEXTAUTH_ADMIN_CREDENTIALS="[email protected]:secretpassword" \
  -d boxyhq/jackson

See the complete list of Environment Variables

Kubernetes and docker-compose deployment files will be coming soon.

Without Docker​

Please follow the below instructions.

Clone the repository​

You can clone the source from the Jackson GitHub repo

git clone https://github.com/boxyhq/jackson
cd jackson

Install dependencies​

npm install

Add environment variables​

cp .env.example .env

Update .env with your values. See the complete list of Environment Variables

Build and run​

npm run build
npm run start

Test the service is running​

Open a browser and visit http://localhost:5225.

If you see a page asking you to sign in, congrats 🎉 you are seeing the Admin Portal.

Database​

Jackson currently supports the following databases.

  • Postgres
  • MySQL
  • Microsoft SQL Server
  • MariaDB
  • MongoDB
  • Redis
  • PlanetScale (MySQL compatible)
  • Neon (Serverless Postgres)
  • Amazon DynamoDB

PlanetScale​

To connect PlanetScale database with Jackson, follow the below steps:

  1. Create a new database on PlanetScale

  2. Get your database connection URL from the PlanetScale

  3. Set the following environment variables

    • DB_ENGINE=planetscale
    • DB_TYPE=mysql
    • DB_SSL=true
    • DATABASE_URL=<PlanetScale connection URL>

  4. Run the database migration to create the tables required by SAML Jackson

cd npm && PLANETSCALE_URL=<PlanetScale connection URL> npm run db:migration:run:planetscale

Make sure you have ?ssl={"rejectUnauthorized":true} at the end of the PlanetScale connection URL.

Now you are ready to start the service.

SAML Tracer​

Each error event in the SAML request/ response phase is captured to aid in troubleshooting the SAML setup. The record or trace contains context related to the flow, like tenant, product, etc. The Admin Portal will have a tab under Enterprise SSO -> SAML Tracer showing a paginated list of traces over time. Developers can inspect a trace and will be able to ascertain the real reason for the failure.

Deployment Guides (Coming soon)​

  • Heroku
  • DigitalOcean
  • Vercel
  • Docker
  • Kubernetes
  • AWS
  • GCP
  • Azure