How to Install Logto Docker: Complete Setup Guide

Install Logto Docker by cloning the logto-io/logto repository and running docker compose up -d, which starts the Logto application on port 3001 and the admin console on port 3002 alongside a PostgreSQL database.

The logto-io/logto repository provides first-class Docker support with multi-stage builds and pre-configured compose files. Whether you need a quick local demo or a production-ready identity provider, the Docker setup handles the complete Logto stack including the CLI, official connectors, and database migrations.

Understanding the Logto Docker Architecture

The Docker implementation follows a builder → seal pattern designed for lean production images. The setup consists of two primary containers: an app service running the Logto Node.js application and a postgres service providing the required PostgreSQL store.

Multi-Stage Dockerfile Structure

The Dockerfile in the repository root uses Node.js 22 Alpine for both build and runtime:

1. Builder stage – Installs pnpm, pulls source dependencies, builds all packages (pnpm -r build), links official connectors, and prunes development dependencies
2. Seal stage – Copies compiled output into a fresh node:22-alpine image, creates a writable directory for CLI alteration scripts, exposes port 3001, and sets the entrypoint to npm run start

This approach ensures the final image contains only compiled assets and runtime dependencies, excluding build tooling.

Container Orchestration and Health Checks

The docker-compose.yml file configures container dependencies using service_healthy conditions. PostgreSQL must pass its health check before Logto starts, and Logto exposes its own health endpoint on port 3001 to verify readiness.

Quick Start: Install Logto Docker Locally

For a local demonstration using the pre-built image, run these commands:

git clone https://github.com/logto-io/logto.git
cd logto
docker compose up -d

This command pulls the svhd/logto:${TAG-latest} image and starts both services. Access the application at:

• User API/OIDC endpoints: http://localhost:3001
• Admin Console: http://localhost:3002

Configuration and Environment Variables

Logto reads configuration from container environment variables. The docker-compose.yml sets sensible defaults, but you can override these for production deployments.

Core Database Configuration

The DB_URL variable specifies the PostgreSQL connection string. The default compose file uses:

DB_URL=postgres://postgres:p0stgr3s@localhost:5432/logto

Reverse Proxy and Endpoint Settings

When running behind a reverse proxy, set TRUST_PROXY_HEADER to 1 to enable trust for X-Forwarded-* headers.

Additional optional variables include:

• ENDPOINT – Public URL for the Logto user API (e.g., https://auth.example.com)
• ADMIN_ENDPOINT – Public URL for the admin console (e.g., https://admin.example.com)
• PRIVATE_KEY_ROTATION_GRACE_PERIOD – Rotation period in seconds (default: 86400)

Create a docker-compose.override.yml file to customize these values:

services:
  app:
    environment:
      - ENDPOINT=https://my-logto.example.com
      - ADMIN_ENDPOINT=https://my-logto-admin.example.com
      - TRUST_PROXY_HEADER=1
      - PRIVATE_KEY_ROTATION_GRACE_PERIOD=86400

Apply changes with:

docker compose up -d --force-recreate

Running the Integration Test Stack

For CI pipelines or integration testing, use the docker-compose.integration.yml file. This configuration adds a Redis container and mounts temporary volumes for test data:

docker compose -f docker-compose.integration.yml up -d

This stack exposes ports 3001 and 3002 while injecting a test SECRET_VAULT_KEK environment variable required for the test suite.

Production Deployment Considerations

When deploying Logto Docker to production environments:

• Persist data by mounting volumes for PostgreSQL or using an external managed database
• Add TLS termination via reverse proxy (nginx, Traefik, or cloud load balancers) and configure TRUST_PROXY_HEADER accordingly
• Update image tags from latest to specific versions (e.g., svhd/logto:1.15.0) to ensure reproducible builds
• Review .dockerignore to ensure your build context excludes unnecessary files that could bloat the image

Summary

• Logto Docker installation requires the docker-compose.yml from the logto-io/logto repository, which orchestrates the Logto app and PostgreSQL database.
• The Dockerfile uses a multi-stage build with node:22-alpine, pnpm, and npm run start to create lean production images.
• Default ports are 3001 for user/OIDC endpoints and 3002 for the admin console.
• Configure environment variables like DB_URL, ENDPOINT, and TRUST_PROXY_HEADER via docker-compose.override.yml or direct container injection.
• Use docker-compose.integration.yml for testing scenarios that require Redis and additional test volumes.

Frequently Asked Questions

What ports does Logto Docker expose?

Logto Docker exposes port 3001 for the user-facing API and OIDC endpoints, and port 3002 for the administrative console. These are defined in the Dockerfile via the EXPOSE 3001 directive and mapped in the compose files.

How do I customize Logto Docker environment variables?

Create a docker-compose.override.yml file in the project root and define your variables under the app service's environment section. Docker Compose automatically merges this with the base docker-compose.yml. Run docker compose up -d --force-recreate to apply changes.

Can I use an external database with Logto Docker?

Yes. Set the DB_URL environment variable to your external PostgreSQL connection string (e.g., postgres://user:pass@db.example.com:5432/logto) and remove or disable the postgres service from your compose file. Ensure the external database accepts connections from the Logto container.

What is the difference between docker-compose.yml and docker-compose.integration.yml?

The standard docker-compose.yml provides a minimal two-container setup (Logto + PostgreSQL) for local development and demos. The docker-compose.integration.yml file includes a Redis container, temporary test volumes, and specific environment variables like SECRET_VAULT_KEK required for running the repository's automated integration test suite.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}