Installation

This guide covers various methods to install and run Ory Kratos in your environment.

Docker

The recommended way to run Ory Kratos is using the official Docker images.

Pull the latest image

docker pull oryd/kratos:v25.4.0

Use specific version tags for production deployments. See available tags on Docker Hub.

Run Kratos with Docker

Create configuration file

Create a basic kratos.yml configuration:

kratos.yml

version: v0.13.0

dsn: memory

serve:
  public:
    base_url: http://localhost:4433/
    cors:
      enabled: true
  admin:
    base_url: http://localhost:4434/

selfservice:
  default_browser_return_url: http://localhost:4455/
  methods:
    password:
      enabled: true

  flows:
    login:
      ui_url: http://localhost:4455/login
    registration:
      ui_url: http://localhost:4455/registration

identity:
  default_schema_id: default
  schemas:
    - id: default
      url: file:///etc/config/kratos/identity.schema.json

log:
  level: info
  format: json

secrets:
  cookie:
    - PLEASE-CHANGE-ME-I-AM-VERY-INSECURE
  cipher:
    - 32-LONG-SECRET-NOT-SECURE-AT-ALL

hashers:
  algorithm: bcrypt
  bcrypt:
    cost: 12

Change the secrets values before deploying to production. Use strong, randomly generated values.

Create identity schema

Create an identity.schema.json file:

identity.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "traits": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "title": "E-Mail",
          "ory.sh/kratos": {
            "credentials": {
              "password": {"identifier": true}
            },
            "verification": {"via": "email"},
            "recovery": {"via": "email"}
          }
        }
      },
      "required": ["email"],
      "additionalProperties": false
    }
  }
}

Run the container

Start Kratos with your configuration:

docker run -d \
  --name kratos \
  -p 4433:4433 \
  -p 4434:4434 \
  -v $(pwd)/kratos.yml:/etc/config/kratos/kratos.yml \
  -v $(pwd)/identity.schema.json:/etc/config/kratos/identity.schema.json \
  oryd/kratos:v25.4.0 \
  serve -c /etc/config/kratos/kratos.yml

Verify it’s running:

curl http://localhost:4433/health/ready

Binary installation

Install the Kratos CLI binary for your operating system.

Linux
macOS
Windows

Using the install script

bash <(curl https://raw.githubusercontent.com/ory/kratos/master/install.sh) -b . kratos
sudo mv ./kratos /usr/local/bin/

Manual download

Download the latest release:

# AMD64
wget https://github.com/ory/kratos/releases/download/v25.4.0/kratos_25.4.0-linux_64bit.tar.gz
tar -xzf kratos_25.4.0-linux_64bit.tar.gz
sudo mv kratos /usr/local/bin/

# ARM64
wget https://github.com/ory/kratos/releases/download/v25.4.0/kratos_25.4.0-linux_arm64.tar.gz
tar -xzf kratos_25.4.0-linux_arm64.tar.gz
sudo mv kratos /usr/local/bin/

Verify installation:

kratos version

Using Homebrew

brew install ory/tap/kratos

Using the install script

bash <(curl https://raw.githubusercontent.com/ory/kratos/master/install.sh) -b . kratos
sudo mv ./kratos /usr/local/bin/

Manual download

# Intel (AMD64)
wget https://github.com/ory/kratos/releases/download/v25.4.0/kratos_25.4.0-macos_64bit.tar.gz
tar -xzf kratos_25.4.0-macos_64bit.tar.gz
sudo mv kratos /usr/local/bin/

# Apple Silicon (ARM64)
wget https://github.com/ory/kratos/releases/download/v25.4.0/kratos_25.4.0-macos_arm64.tar.gz
tar -xzf kratos_25.4.0-macos_arm64.tar.gz
sudo mv kratos /usr/local/bin/

Verify installation:

kratos version

Using Chocolatey

choco install ory-kratos

Manual download

Download the Windows binary from GitHub Releases:

# Download and extract
Invoke-WebRequest -Uri https://github.com/ory/kratos/releases/download/v25.4.0/kratos_25.4.0-windows_64bit.zip -OutFile kratos.zip
Expand-Archive kratos.zip -DestinationPath C:\Program Files\kratos

# Add to PATH
$env:Path += ";C:\Program Files\kratos"

Verify installation:

kratos version

Run Kratos from binary

Once installed, run Kratos with:

kratos serve -c /path/to/kratos.yml

Database setup

For production deployments, use a persistent database instead of in-memory storage.

PostgreSQL
MySQL
CockroachDB
SQLite

Install PostgreSQL

Install PostgreSQL 12 or later:

# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib

# macOS
brew install postgresql

Create database and user

CREATE DATABASE kratos;
CREATE USER kratos WITH PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE kratos TO kratos;

Configure Kratos

Update your kratos.yml with the PostgreSQL DSN:

dsn: postgres://kratos:your-secure-password@localhost:5432/kratos?sslmode=disable&max_conns=20&max_idle_conns=4

For production, enable SSL with sslmode=require and configure connection pooling appropriately.

Run migrations

kratos migrate sql -e --yes -c /path/to/kratos.yml

Install MySQL

Install MySQL 8.0 or later:

# Ubuntu/Debian
sudo apt-get install mysql-server

# macOS
brew install mysql

Create database and user

CREATE DATABASE kratos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'kratos'@'localhost' IDENTIFIED BY 'your-secure-password';
GRANT ALL PRIVILEGES ON kratos.* TO 'kratos'@'localhost';
FLUSH PRIVILEGES;

Configure Kratos

Update your kratos.yml:

dsn: mysql://kratos:your-secure-password@tcp(localhost:3306)/kratos?max_conns=20&max_idle_conns=4&parseTime=true

Run migrations

kratos migrate sql -e --yes -c /path/to/kratos.yml

Install CockroachDB

Download and install CockroachDB:

# macOS
brew install cockroachdb/tap/cockroach

# Linux
wget -qO- https://binaries.cockroachdb.com/cockroach-latest.linux-amd64.tgz | tar xvz
sudo cp cockroach-latest.linux-amd64/cockroach /usr/local/bin/

Start CockroachDB

cockroach start-single-node --insecure --background

Create database

cockroach sql --insecure -e "CREATE DATABASE kratos;"

Configure Kratos

Update your kratos.yml:

dsn: cockroach://root@localhost:26257/kratos?sslmode=disable&max_conns=20&max_idle_conns=4

Run migrations

kratos migrate sql -e --yes -c /path/to/kratos.yml

Using SQLite

SQLite is suitable for development and testing:

dsn: sqlite:///var/lib/kratos/db.sqlite?_fk=true&mode=rwc

SQLite is NOT recommended for production use. It doesn’t support concurrent writes and lacks features needed for high-availability deployments.

Run migrations

kratos migrate sql -e --yes -c /path/to/kratos.yml

Kubernetes deployment

Deploy Ory Kratos to Kubernetes using Helm.

Add the Ory Helm repository

helm repo add ory https://k8s.ory.sh/helm/charts
helm repo update

Create values file

Create a values.yaml file:

values.yaml

kratos:
  config:
    dsn: postgres://kratos:password@postgres:5432/kratos?sslmode=disable
    
    serve:
      public:
        base_url: https://kratos.example.com/
        cors:
          enabled: true
      admin:
        base_url: https://kratos-admin.example.com/
    
    selfservice:
      default_browser_return_url: https://app.example.com/
      methods:
        password:
          enabled: true
    
    identity:
      default_schema_id: default
      schemas:
        - id: default
          url: base64://ewogICIkaWQiOiAi...  # Base64 encoded schema
    
    secrets:
      cookie:
        - CHANGE-ME-PLEASE
      cipher:
        - 32-CHAR-SECRET-CHANGE-ME-PLEASE

ingress:
  public:
    enabled: true
    className: nginx
    hosts:
      - host: kratos.example.com
        paths:
          - path: /
            pathType: Prefix
  
  admin:
    enabled: true
    className: nginx
    hosts:
      - host: kratos-admin.example.com
        paths:
          - path: /
            pathType: Prefix

deployment:
  replicas: 3
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "500m"

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

Install the chart

helm install kratos ory/kratos -f values.yaml

Or upgrade an existing installation:

helm upgrade kratos ory/kratos -f values.yaml

Run database migrations

Create a migration job:

kubectl create job --from=cronjob/kratos-automigrate kratos-migrate

Or run manually:

kubectl run kratos-migrate --rm -it --restart=Never \
  --image=oryd/kratos:v25.4.0 -- \
  migrate sql -e --yes -c /etc/config/kratos.yml

Verify deployment

Check pod status:

kubectl get pods -l app.kubernetes.io/name=kratos

Test the service:

kubectl port-forward svc/kratos-public 4433:80
curl http://localhost:4433/health/ready

For production deployments, consider using external secrets management like Sealed Secrets or External Secrets Operator.

Build from source

For development or custom modifications, build Kratos from source.

Install prerequisites

You need:

Go 1.21 or later
Git
Make

# Verify Go installation
go version

Clone the repository

git clone https://github.com/ory/kratos.git
cd kratos

Build the binary

make install

This builds and installs the kratos binary to $GOPATH/bin/kratos.Alternatively, build without installing:

go build -o kratos .

Run tests

make test

Run specific tests:

go test -v ./identity/...

Run from source

./kratos serve -c /path/to/kratos.yml

Configuration basics

After installation, configure Kratos for your use case:

Essential configuration options

Database connection (DSN)

Configure the database connection string:

dsn: postgres://user:pass@host:5432/database

Serve endpoints

Configure public and admin API URLs:

serve:
  public:
    base_url: https://auth.example.com/
    port: 4433
  admin:
    base_url: https://auth-admin.example.com/
    port: 4434

Authentication methods

Enable authentication strategies:

selfservice:
  methods:
    password:
      enabled: true
    oidc:
      enabled: true
      config:
        providers:
          - id: google
            provider: google
            client_id: your-client-id
            client_secret: your-client-secret
    webauthn:
      enabled: true
    totp:
      enabled: true

Secrets

Configure secrets for encryption and cookies:

secrets:
  cookie:
    - your-32-char-secret-key-change-me
  cipher:
    - your-32-char-cipher-key-change-me

Use strong, randomly generated secrets. Never commit secrets to version control.

Verify installation

Confirm Kratos is working correctly:

# Check version
kratos version

# Test health endpoints
curl http://localhost:4433/health/alive
curl http://localhost:4433/health/ready

# Check admin API
curl http://localhost:4434/admin/identities

Next steps

Configuration

Configure authentication methods, flows, and identity schemas

Identity schemas

Define custom identity attributes and validation

Self-service flows

Implement login, registration, and account recovery

Security

Production security best practices

For managed hosting with zero infrastructure maintenance, try Ory Network.

Get Started

Concepts

Self-Service Flows

Authentication Methods

Identity Management

Session Management

Deployment

Security

CLI Reference

​Installation

​Docker

​Pull the latest image

​Run Kratos with Docker

​Binary installation

​Using the install script

​Manual download

​Using Homebrew

​Using the install script

​Manual download

​Using Chocolatey

​Manual download

​Run Kratos from binary

​Database setup

​Install PostgreSQL

​Create database and user

​Configure Kratos

​Run migrations

​Install MySQL

​Create database and user

​Configure Kratos

​Run migrations

​Install CockroachDB

​Start CockroachDB

​Create database

​Configure Kratos

​Run migrations

​Using SQLite

​Run migrations

​Kubernetes deployment

​Build from source

​Configuration basics

​Essential configuration options

​Verify installation

​Next steps

Configuration

Identity schemas

Self-service flows

Security

Build docs developers (and LLMs) love

Installation

Docker

Pull the latest image

Run Kratos with Docker

Binary installation

Using the install script

Manual download

Using Homebrew

Using the install script

Manual download

Using Chocolatey

Manual download

Run Kratos from binary

Database setup

Install PostgreSQL

Create database and user

Configure Kratos

Run migrations

Install MySQL

Create database and user

Configure Kratos

Run migrations

Install CockroachDB

Start CockroachDB

Create database

Configure Kratos

Run migrations

Using SQLite

Run migrations

Kubernetes deployment

Build from source

Configuration basics

Essential configuration options

Verify installation

Next steps