Ory Polis Quickstart

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 Ory Polis. 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, 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 API_KEYS="secret" \
  -e NEXTAUTH_URL="http://localhost:5225" \
  -e EXTERNAL_URL="http://localhost:5225" \
  -e NEXTAUTH_SECRET="super-secret" \
  -e NEXTAUTH_ADMIN_CREDENTIALS="admin@company.com:secretpassword" \
  -d ory/polis

OR

docker run \
  -p 5225:5225 \
  -e DB_ENGINE="mongo" \
  -e DB_URL="mongodb://localhost:27017/jackson" \
  -e API_KEYS="secret" \
  -e NEXTAUTH_URL="http://localhost:5225" \
  -e EXTERNAL_URL="http://localhost:5225" \
  -e NEXTAUTH_SECRET="super-secret" \
  -e NEXTAUTH_ADMIN_CREDENTIALS="admin@company.com:secretpassword" \
  -d ory/polis

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 Ory Polis GitHub repo

git clone https://github.com/ory/polis

cd polis

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

Ory Polis 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 Ory Polis, 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 Ory Polis

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