Logto

Overview

Logto is an open-source sign-in and user-management platform. Your apps send users to Logto for sign-in and sign-up over OIDC or OAuth, and Logto provides users, roles, organizations, social and passwordless connectors, MFA, and a Management API, with an Admin Console to manage them. This template runs two interchangeable Logto replicas on a bundled highly available PostgreSQL by default, serves the Admin Console from its own workload, and creates the Admin Console account from a secret you provide. All state, including signing keys and the admin account, lives in PostgreSQL. Replicas share only the database.

This template deploys into an existing GVC. It does not create or manage one. Every resource lands in the GVC you install into. Use a single-location GVC: the bundled database runs in one location.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-logto`	Sign-in pages, OIDC and the Management API on port 3001 (standard, 2 replicas)	—
Workload	`RELEASE_NAME-logto-admin`	Admin Console on port 3002 and its own public URL (standard, 1 replica)	`adminConsole.publicAccess.enabled: true`
Workload	`RELEASE_NAME-postgres-ha`	PostgreSQL cluster managed by Patroni (stateful, 3 replicas)	default store (`postgresHA.enabled: true`)
Workload	`RELEASE_NAME-postgres-ha-proxy`	HAProxy leader endpoint that Logto connects through	default store
Workload	`RELEASE_NAME-etcd`	Consensus store for Patroni (stateful, 3 replicas)	default store
Workload	`RELEASE_NAME-postgres`	Single-instance PostgreSQL (stateful, 1 replica)	`postgres.enabled: true`
Volume set	`RELEASE_NAME-postgres-ha-vs`, `RELEASE_NAME-etcd-vs`	Persistent data for the Patroni and etcd replicas	default store
Volume set	`RELEASE_NAME-pg-vs`	Persistent data for the single-instance store	`postgres.enabled: true`
Domain	your `customDomain.core` and `customDomain.adminConsole` hostnames	Custom hostnames routed to the matching workload	`customDomain.core` or `customDomain.adminConsole` set
Secret	your `admin.secretName`	Admin account `username` and `password`. Created by you — see Prerequisites	—
Workload	`RELEASE_NAME-postgres-ha-backup`	Scheduled logical backups of the HA store	`postgresHA.backup.enabled: true` with `mode: logical`
Workload	`RELEASE_NAME-postgres-backup`	Scheduled backups of the single-instance store	`postgres.backup.enabled: true`
Secret	`RELEASE_NAME-postgres-config`	Non-sensitive backup destination settings for the HA store	`postgresHA.backup.enabled: true`
Secret	your `postgresHA.config.credentialsSecretName` or `postgres.config.credentialsSecretName`	Database `username`, `password` and `database`. Created by you — see Prerequisites	—
Secret	`RELEASE_NAME-patroni-startup`, `RELEASE_NAME-postgres-proxy-startup`, `RELEASE_NAME-etcd-startup`, `RELEASE_NAME-wal-g-backup-script`	Startup and backup scripts for the HA store	default store
Identity + Policy	`RELEASE_NAME-logto-identity`, `RELEASE_NAME-logto-policy`	Grants Logto `reveal` on exactly two secrets: your admin secret and your database credentials secret	—
Identity + Policy	`RELEASE_NAME-pg-identity`, `RELEASE_NAME-pg-policy`	Least-privilege access for the single-instance store	`postgres.enabled: true`
Identity + Policy	`RELEASE_NAME-postgres-ha-identity`, `RELEASE_NAME-postgres-ha-policy`, `RELEASE_NAME-etcd-identity`, `RELEASE_NAME-etcd-policy`	Least-privilege access for the HA store’s own workloads	default store

Prerequisites

Two dictionary secrets must exist before you install. The template creates neither; it references yours by name and grants Logto reveal on exactly those secrets.

Create the admin account secret

A dictionary secret with exactly the keys username and password. Logto creates the Admin Console account from it on first boot:

cpln secret create-dictionary --name ADMIN_SECRET_NAME \
  --entry username=admin \
  --entry password="$(openssl rand -hex 32)"

The username may contain letters, digits and _, and must start with a letter or _. The password needs 8 or more characters and must not be a known breached password. Set admin.secretName to this name.

Create the database credentials secret

A dictionary secret holding username, password and database. The bundled PostgreSQL initializes with them and Logto connects with them:

cpln secret create-dictionary --name DB_CREDENTIALS_SECRET_NAME \
  --entry username=logto \
  --entry password="$(openssl rand -hex 32)" \
  --entry database=logto

All three values must be URL-safe (letters, digits, -, _, .). Set postgresHA.config.credentialsSecretName (HA, the default) or postgres.config.credentialsSecretName (single-instance) to this name. Secret names are org-wide, so give each release its own secrets.

Read the admin password back when you need it

-o yaml is required; without it the command prints only a summary table:

cpln secret reveal ADMIN_SECRET_NAME -o yaml

A missing prerequisite secret wedges the install silently. The install exits 0, every resource is created, and Logto then waits. Because the container never ran, cpln logs returns nothing.The only place the missing secret is named is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-logto --gvc GVC_NAME -o yaml

The secret ADMIN_SECRET_NAME no longer exists. Workload updates are paused until
the secret is added or the reference to the secret removed.

It is get-deployments — plain cpln workload get has no versions key. Once you create the secret the deployment recovers on its own; to skip the wait, force a redeployment:

cpln workload force-redeployment RELEASE_NAME-logto --gvc GVC_NAME

Custom domains (optional). The apex domain must be registered with Control Plane, and each hostname needs a CNAME to the GVC endpoint before you install. See Custom Domains. Backups (optional). A cloud account and bucket, set up as described on the postgres-highly-available page. See Backing Up.

Installation

Install from the marketplace registry, naming your two secrets:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/logto \
  --version 1.0.0 --gvc GVC_NAME \
  --set admin.secretName=ADMIN_SECRET_NAME \
  --set postgresHA.config.credentialsSecretName=DB_CREDENTIALS_SECRET_NAME

For the single-instance store set postgresHA.enabled=false, postgres.enabled=true and postgres.config.credentialsSecretName instead. Choose publicAccess and the custom domains now: the public URL is the OIDC issuer. To install using another method, follow the instructions for your preferred tool:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

image: ghcr.io/logto-io/logto:1.45.0

# Logto replicas (sign-in pages, OIDC and the Management API). All state lives in
# PostgreSQL, so replicas are interchangeable. 2 keeps sign-in up through restarts and
# upgrades; 1 is the lighter shape. Allowed: 1-4.
replicas: 2

resources: # per Logto process (each replica, and the Admin Console workload)
  minCpu: 250m
  minMemory: 512Mi
  maxCpu: 1000m
  maxMemory: 1Gi

Admin account

# ─── Admin Account ────────────────────────────────────────────────────────────
# REQUIRED PREREQUISITE SECRET — CREATE IT BEFORE YOU INSTALL. A `dictionary`
# secret with exactly two keys, `username` (letters, digits, _; starts with a
# letter or _) and `password` (8+ characters; use `openssl rand -hex 32`). Logto
# creates the Admin Console account from it on FIRST boot only; later changes to
# the secret change nothing. If it does not exist the deployment WEDGES silently.
admin:
  secretName: my-logto-admin

Access

publicAccess:
  enabled: true # sign-in pages + OIDC on the canonical *.cpln.app URL; false = reach Logto only via cpln port-forward

adminConsole:
  publicAccess:
    # true = a second workload serves the Admin Console on its own *.cpln.app URL (sign-in only).
    # false = no public Console; use `cpln port-forward RELEASE_NAME-logto 3002:3002` instead.
    enabled: true

Custom Domains

Bare hostnames; the chart creates the domains. The core hostname becomes the OIDC issuer, so set it at install.

customDomain: # bare hostnames; the chart creates the domains (apex must be verified, CNAME required — see Custom Domains)
  core: ""         # e.g. auth.example.com; empty = canonical *.cpln.app. Becomes the OIDC issuer — set it at install
  adminConsole: "" # e.g. auth-admin.example.com; needs adminConsole.publicAccess.enabled

Internal Access and Webhooks

internalAccess: # which workloads inside Control Plane can call Logto
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads: [] # used with workload-list
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

webhooks:
  # true = webhooks may call workloads inside Control Plane (*.cpln.local URLs). Off, Logto
  # refuses internal addresses and sends webhooks only to public URLs.
  allowInternalTargets: false

webhooks.allowInternalTargets is a security trade-off. By default Logto sends webhooks only to public URLs. Turning it on lets anyone who can manage webhooks (a Console admin, or an app with Management API access) make Logto call any workload it can reach inside Control Plane. Leave it off unless you need internal receivers.

Database

Highly available PostgreSQL is the default. For a lighter install, set postgresHA.enabled: false and postgres.enabled: true. The backup blocks pass through to the postgres-highly-available and postgres templates.

# ─── Database: Highly Available PostgreSQL (default) ──────────────────────────
# Deploys the postgres-highly-available template: 3 Patroni replicas, 3 etcd
# replicas, and an HAProxy leader endpoint Logto connects to.
postgresHA:
  enabled: true
  config:
    # REQUIRED PREREQUISITE SECRET (HA mode) — CREATE IT BEFORE YOU INSTALL. If it
    # does not exist the deployment WEDGES silently and looks like a platform fault.
    # A `dictionary` secret with exactly three URL-safe keys: username, password,
    # database. PostgreSQL reads it once, when its data is first initialized, and
    # Logto connects with the same keys. See Prerequisites for the command.
    credentialsSecretName: my-logto-db-credentials
  replicas: 3
  image: controlplanecorporation/patroni-postgres:0.8 # pgvector 0.8.7 (CVE-2026-103484); tags 0.1-0.7 are refused
  volumeset:
    capacity: 10 # initial capacity in GiB per replica (minimum is 10)

  backup: # pass-through to the postgres-highly-available template's backup feature
    enabled: false
    mode: logical # logical or wal-g
    resources:
      cpu: 100m
      memory: 512Mi # 128Mi OOM-kills wal-g mid-backup
    logical:
      image: ghcr.io/controlplane-com/backup-images/postgres-backup:17.1.0
      schedule: "0 2 * * *" # daily at 2am UTC
    walg:
      intervalSeconds: 21600 # every 6 hours
    provider: aws # Options: aws, gcp, or minio
    aws:
      bucket: my-logto-backup-bucket
      region: us-east-1
      cloudAccountName: my-logto-backup-cloudaccount
      policyName: my-logto-backup-policy
      prefix: postgres/backups
    gcp:
      bucket: my-logto-backup-bucket
      cloudAccountName: my-logto-backup-cloudaccount
      prefix: postgres/backups
    minio: # any S3-compatible endpoint, e.g. an internal MinIO template deployment
      endpoint: http://my-minio-workload:9000
      bucket: my-logto-backup-bucket
      # REQUIRED PREREQUISITE SECRET when provider is `minio` — a `dictionary`
      # secret holding exactly `accessKey` and `secretKey` (see the postgres-highly-available docs).
      credentialsSecretName: my-logto-minio-credentials
      prefix: postgres/backups

# ─── Database: Single-instance PostgreSQL (dev/lightweight) ───────────────────
# Enable this and disable postgresHA for a lighter non-HA deployment.
postgres:
  enabled: false
  config:
    # REQUIRED PREREQUISITE SECRET (single-instance mode) — the same kind of
    # `dictionary` secret as postgresHA.config.credentialsSecretName above
    # (keys: username, password, database). Create it BEFORE you install.
    credentialsSecretName: my-logto-db-credentials
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)

  backup: # pass-through to the postgres template's backup feature (Postgres 17+)
    enabled: false
    image: ghcr.io/controlplane-com/backup-images/postgres-backup:18.1.0
    schedule: "0 2 * * *" # daily at 2am UTC
    resources:
      cpu: 100m
      memory: 128Mi
    provider: aws # Options: aws, gcp, or minio
    aws:
      bucket: my-logto-backup-bucket
      region: us-east-1
      cloudAccountName: my-logto-backup-cloudaccount
      policyName: my-logto-backup-policy
      prefix: postgres/backups
    gcp:
      bucket: my-logto-backup-bucket
      cloudAccountName: my-logto-backup-cloudaccount
      prefix: postgres/backups
    minio:
      endpoint: http://my-minio-workload:9000
      bucket: my-logto-backup-bucket
      # REQUIRED prerequisite dictionary secret holding `accessKey` and `secretKey`,
      # only when backup is enabled with provider: minio (see the postgres template docs).
      credentialsSecretName: my-logto-minio-credentials
      prefix: postgres/backups

Connecting

Logto serves two URLs. Give each audience only its own:

Who	URL	What they do there
Administrators	`https://CUSTOM_ADMIN_HOSTNAME/console` when `customDomain.adminConsole` is set; otherwise the canonical endpoint of `RELEASE_NAME-logto-admin` + `/console`	The Admin Console: applications, users, sign-in experience, connectors, MFA, roles. Sign in with the admin secret’s `username` and `password`.
Your app’s end users	`https://CUSTOM_CORE_HOSTNAME` when `customDomain.core` is set; otherwise the canonical endpoint of `RELEASE_NAME-logto`	Nothing directly: your app redirects them to Logto’s sign-in and sign-up pages here and back. Opened on its own, the URL shows an error page, because no app started a sign-in. To try sign-in as a user, open `/demo-app` on this URL.
Your applications (OIDC)	Issuer: the end users’ URL above (the core hostname when set) + `/oidc` (discovery at `/oidc/.well-known/openid-configuration`)	Paste the issuer, App ID and App secret from Admin Console, Applications into your app.
Workloads in the same GVC	`http://RELEASE_NAME-logto.GVC_NAME.cpln.local:3001`	The same endpoints over the internal network.
Admin Console without public access	`http://localhost:3002/console` through the port-forward below	Only with `adminConsole.publicAccess.enabled: false`.

Find a canonical endpoint in status.canonicalEndpoint:

cpln workload get RELEASE_NAME-logto --gvc GVC_NAME -o yaml
cpln workload get RELEASE_NAME-logto-admin --gvc GVC_NAME -o yaml

For a private Admin Console, open a tunnel and browse to http://localhost:3002/console:

cpln port-forward RELEASE_NAME-logto 3001:3001 3002:3002 --gvc GVC_NAME

First Run

Open the Administrators URL from the table above, sign in with the admin secret’s username and password, then create an application under Applications and copy its App ID, App secret and the issuer into your app. The Admin Console serves nothing until the admin account has been created from your secret.

Operations

Backing Up

Enable the backup block of the database you use (postgresHA.backup or postgres.backup). Bucket and cloud-account setup is on the postgres-highly-available and postgres pages. Restoring a Logto database from a backup is not documented for this template.

Scaling and Availability

replicas (1 to 4) sets the number of Logto replicas; they are interchangeable because all state is in PostgreSQL. Two keep sign-in up through restarts and upgrades. A database failover interrupts sign-in for about a minute while PostgreSQL promotes a new leader; Logto reconnects on its own.

Troubleshooting

Logto never starts and cpln logs returns nothing

Cause: the admin secret or the database credentials secret does not exist.Fix: read status.versions[].message as shown in Prerequisites, create the secret, then run cpln workload force-redeployment RELEASE_NAME-logto --gvc GVC_NAME.

The Admin Console workload is ready but its URL returns 503

Cause: the Admin Console workload waits for the admin account (waiting for the first admin account in its log). The account is created by the RELEASE_NAME-logto workload.Fix: look for FATAL bootstrap in the RELEASE_NAME-logto logs:

cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-logto"} |= "FATAL"' --limit 50 --since 10m

FATAL bootstrap with password.rejected

Cause: the admin password is a known breached password, is too weak, or api.pwnedpasswords.com is unreachable; Logto refuses the password when the check cannot run.Fix: correct the password in the admin secret (and allow outbound HTTPS to api.pwnedpasswords.com), then run cpln workload force-redeployment RELEASE_NAME-logto --gvc GVC_NAME.

A port-forwarded Admin Console signs in but shows no data

Cause: with the public Admin Console on, Logto accepts only the public Console origin.Fix: use the public Console URL, or set adminConsole.publicAccess.enabled: false and use the port-forward.

Important Notes

The admin secret is read once, when the database is first initialized. Afterwards change the admin password in the Admin Console; editing the secret changes nothing. There is no supported reset for a lost admin password, so store it safely.
Choose publicAccess and the custom domains at install. The public URL is the OIDC issuer, and changing it later breaks every app configured against it.
First boot needs outbound HTTPS to api.pwnedpasswords.com. Logto checks the admin password against known breaches and refuses it if the check cannot run.
To send verification and sign-in emails, add an email connector (SMTP or a provider) under Admin Console, Connectors. Logto reaches the mail server over outbound TCP, which the template allows.
Leave webhooks.allowInternalTargets off unless you need internal receivers. Turning it on lets anyone who can manage webhooks make Logto call any workload it can reach inside Control Plane.
With custom domains set, give administrators and users only the domain URLs. The *.cpln.app Admin Console URL then serves the sign-in service instead of the Console.
Uninstalling removes the domain resources. Reinstalling recreates them, and no re-verification is needed while the apex domain stays registered.
The first helm upgrade after an install can restart the bundled database, which briefly interrupts sign-in.
Uninstalling deletes the database volumes, and with them every user and signing key. Enable backups.
The open-source edition has one Admin Console account. Inviting more admins is a paid Logto feature.

External References

Logto Documentation

Official Logto documentation

Logto OSS Configuration

Core service configuration reference

Integrate an App

Quick starts for connecting your app to Logto

Logto on GitHub

Upstream source and releases

Logto Template

View the source files, default values, and chart definition

Template Catalog

Templates

Logto

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Logto

Admin account

Access

Custom Domains

Internal Access and Webhooks

Database

Connecting

First Run

Operations

Backing Up

Scaling and Availability

Troubleshooting

Important Notes

External References

Logto Documentation

Logto OSS Configuration

Integrate an App

Logto on GitHub

Logto Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Logto

​Admin account

​Access

​Custom Domains

​Internal Access and Webhooks

​Database

​Connecting

​First Run

​Operations

​Backing Up

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Logto Documentation

Logto OSS Configuration

Integrate an App

Logto on GitHub

Logto Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Logto

Admin account

Access

Custom Domains

Internal Access and Webhooks

Database

Connecting

First Run

Operations

Backing Up

Scaling and Availability

Troubleshooting

Important Notes

External References