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 and edition of Ory Polis. The edition is oss for the open source build and oel for the Ory Enterprise License build. For example: {"version":"1.0.0","edition":"oss"}.

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="[email protected]:secretpassword" \
  -d boxyhq/jackson

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="[email protected]:secretpassword" \
  -d boxyhq/jackson

See the complete list of Environment Variables

To run Ory Polis with a Postgres database using Docker Compose, use the docker-compose.yml in the repository.

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

Ory Polis uses pnpm. Run corepack enable once to get the pnpm version the repository pins.

pnpm install

Add environment variables

cp .env.example .env

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

Build and run

pnpm run build

pnpm 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
• CockroachDB
• YugabyteDB
• MySQL
• Microsoft SQL Server
• MariaDB
• SQLite
• 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> pnpm 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.

SSO Traces

Ory Polis records each error in an SSO flow, SAML or OIDC, as a trace, to help troubleshoot connection setups. A trace holds the context of the flow, such as the tenant and product. The Admin Portal lists them under Enterprise SSO > SSO Traces, where you can inspect a trace to find the reason for the failure. See SSO Traces to configure how long traces are kept.

Deployment guides

• Heroku
• Vercel