Deployment

Deploy IdentityScribe on Docker, Kubernetes, or bare metal. This page covers installation, verification, and platform-specific setup.

Quick install

Download the executable for your platform

Create identity-scribe.conf:

database {
  url = "jdbc:postgresql://localhost:5432/identity_scribe"
  user = "identity_scribe"
  password = ${DB_PASSWORD}
}

ldap {
  url = "ldap://your-ldap-server:389"
  bind-dn = "cn=admin,ou=sa,o=system"
  bind-password = ${LDAP_BIND_PASSWORD}
}

transcribes {
  user {
    ldap {
      base = "ou=users,o=data"
      filter = "(objectClass=Person)"
    }
  }
}

channels.rest.enabled = true

The distribution includes three starter templates: minimal.conf, recommended.conf, and production.conf. See Starter templates for what each one provides.

Run: ./identity-scribe
Verify: curl http://localhost:8080/readyz

Docker Compose

services:
  identity-scribe:
    image: identity-scribe:latest
    environment:
      SCRIBE_LDAP_URL: "ldap://ldap:389"
      SCRIBE_LDAP_BIND_DN: "cn=admin,dc=example,dc=com"
      SCRIBE_LDAP_BIND_PASSWORD: "${LDAP_ADMIN_PASSWORD}"
      SCRIBE_DATABASE_URL: "postgresql://postgres:5432/identity_scribe"
      SCRIBE_DATABASE_USER: "scribe"
      SCRIBE_DATABASE_PASSWORD: "${DB_PASSWORD}"
      SCRIBE_HTTP_PORT: "8080"
      SCRIBE_LOG_LEVEL: "info"

Kubernetes

apiVersion: v1
kind: ConfigMap
metadata:
  name: identity-scribe-config
data:
  SCRIBE_LDAP_URL: "ldap://ldap-service:389"
  SCRIBE_DATABASE_URL: "postgresql://postgres-service:5432/identity_scribe"
  SCRIBE_HTTP_PORT: "8080"
  SCRIBE_LOG_LEVEL: "info"
  SCRIBE_CONCURRENCY: "16"
---
apiVersion: v1
kind: Secret
metadata:
  name: identity-scribe-secrets
type: Opaque
stringData:
  SCRIBE_LDAP_BIND_DN: "cn=admin,dc=example,dc=com"
  SCRIBE_LDAP_BIND_PASSWORD: "secret"
  SCRIBE_DATABASE_USER: "scribe"
  SCRIBE_DATABASE_PASSWORD: "secret"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: identity-scribe
spec:
  template:
    spec:
      containers:
      - name: identity-scribe
        envFrom:
        - configMapRef:
            name: identity-scribe-config
        - secretRef:
            name: identity-scribe-secrets
        livenessProbe:
          httpGet:
            path: /livez
            port: 8080
        readinessProbe:
          httpGet:
            path: /readyz
            port: 8080
        startupProbe:
          httpGet:
            path: /startedz
            port: 8080

Kubernetes probes

Configure startup, liveness, and readiness probes for Kubernetes. Use a dedicated monitoring socket if you’ve set up socket separation (port 8081 in this example).

startupProbe:
  httpGet:
    path: /startedz
    port: 8081
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 90   # 15min max for services + DB init

livenessProbe:
  httpGet:
    path: /livez
    port: 8081
  initialDelaySeconds: 0
  periodSeconds: 10
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /readyz
    port: 8081
  initialDelaySeconds: 0
  periodSeconds: 5
  failureThreshold: 1
  successThreshold: 1

The startup probe has a high failureThreshold because initial sync and index builds can take several minutes on large directories. Once the startup probe passes, liveness and readiness probes take over.

For the full list of health endpoints, see the Endpoints Reference.

Database setup

Collation (recommended)

Use ICU collation for consistent Unicode ordering across environments:

CREATE DATABASE "identity_scribe"
  TEMPLATE template0
  ENCODING = 'UTF8'
  LC_COLLATE = 'und-x-icu'
  LC_CTYPE   = 'und-x-icu'
  CONNECTION LIMIT = -1;

For ASCII-only workloads where locale-aware ordering isn’t needed, C collation is faster:

CREATE DATABASE "identity_scribe"
  TEMPLATE template0
  ENCODING = 'UTF8'
  LC_COLLATE = 'C'
  LC_CTYPE   = 'C'
  CONNECTION LIMIT = -1;

pg_stat_statements (optional)

For slow query analysis, enable the extension:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Requires shared_preload_libraries = 'pg_stat_statements' in postgresql.conf. Managed PostgreSQL services (AWS RDS, Azure, GCP) typically provide a UI setting for this.

Once enabled, IdentityScribe’s monitoring UI and /observe/stats/queries show slow query statistics automatically. See Enabling pg_stat_statements for provider-specific instructions.

When IdentityScribe starts, a banner displays runtime information:

 identity-scribe  v1.2.3 ready in 847ms

┃ Mode        production
┃ License     ACME Corp — expires 2027-01-15 (365d)

┃ Config
┃   /etc/scribe/identity-scribe.conf
┃   environment variables

┃ Auth
┃   Methods    bearer
┃   Anonymous  deny
┃   default    https://auth.example.com

┃ Database    postgresql://db.example.com:5432/scribe (ssl)
┃ LDAP        ldaps://dc01.example.com:636

┃ Transcribes
┃   users     ou=users,dc=example,dc=com  (objectClass=person)
┃   groups    ou=groups,dc=example,dc=com (objectClass=group) [disabled]

┃ Channels
┃   REST API  http://localhost:8080/api
┃   LDAP      ldap://localhost:10389

The sections shown depend on your configuration. Credentials are never displayed — database and LDAP URLs are sanitized to show only scheme, host, port, and path.

Command line options

usage: identity-scribe
-c,--config <file>      use config file (default: 'identity-scribe.conf')
-d,--debug              print debugging information
-D <arg>                key=value to set as property
-f,--logfile <file>     log output destination (default: System.out)
-h,--help               print this message
-k,--license <file>     use license file (default: 'identity-scribe.lic')
-l,--loglevel <level>   trace, debug, info, warn, error, fatal (default: info)
-p,--printconfig        print the resolved config and exit
-q,--quiet              be extra quiet
-r,--readonly           Readonly mode — only channels are started
-s,--sync               Force re-sync of all entries
-t,--trace              print tracing information
-v,--version            print the version information and exit

System requirements

Operating system

Linux: Ubuntu, Debian, RHEL, CentOS, Amazon Linux, Oracle Linux, SLES, OpenSUSE, Alpine
macOS: Big Sur, Catalina, Mojave, Monterey
Windows: Server 2019/2016/2012/2008 R2, Windows 11/10/8/7 SP1+

Database

PostgreSQL 18 (primary) or 17 (fully supported)
PostgreSQL 15/16: deprecated compatibility, reduced CI coverage, not recommended for new deployments
Supports plain, SSL, and mutual-SSL connections

CPU compatibility

The distribution binary is built for compatibility mode: it runs on a wide range of x64 and ARM64 CPUs. If you see illegal instruction or similar errors on older hardware, see CPU Compatibility.

Resources

Memory: Uses up to 80% of available physical memory (4 GB RAM = 3.2 GB max)
CPU: I/O-bound; multiple cores benefit parallel processing

Verification

After starting, verify the deployment:

# Readiness
curl -fsS http://localhost:8080/readyz

# Metrics available
curl -fsS http://localhost:8080/metrics | head

# System health
curl -fsS http://localhost:8080/observe/doctor | jq

Configuration — HOCON, env vars, inheritance patterns
Networking — HTTP sockets, TLS, named sockets
Health and Monitoring — Health checks, dashboards, monitoring bundle
Signals — Golden signals and error classification
PromQL Recipes — Alert queries and dashboards
Upgrading — Version migration and PostgreSQL upgrade paths