Requirements for Running Logto: Docker, Node.js, and PostgreSQL Setup Guide

To run Logto on-premise, you need Docker Desktop (or Docker Engine) with Docker Compose for containerized deployment, or Node.js ≥16 with pnpm and a PostgreSQL ≥13 database for local development.

Logto is an open-source identity infrastructure maintained by the logto-io/logto repository. You can deploy it using three methods: Docker Compose, Node.js with pnpm, or the managed Logto Cloud service. Each on-premise option requires specific dependencies to run the Core OIDC provider, Console, and Experience services.

Core Requirements for Running Logto

All on-premise deployment methods share fundamental dependencies defined in the repository’s README.md and configuration files.

Docker and Docker Compose (Recommended)

The fastest way to satisfy the requirements for running Logto is using Docker Compose. This approach automatically handles the PostgreSQL database and all service containers.

• Docker Desktop (or Docker Engine): Provides the container runtime for the logto services (core, console, experience) and the PostgreSQL database.
• Docker Compose: Orchestrates the multi-container setup defined in docker-compose.yml with a single command.

Node.js Development Stack

For local development or custom builds, you must install the Node.js toolchain manually:

• Node.js ≥16: Required to run npm init @logto, build packages, and execute the source code directly.
• pnpm: The mandatory package manager for the monorepo’s workspace dependencies. Logto uses pnpm to run build scripts like pnpm prepack and pnpm start:dev.
• PostgreSQL ≥13: Logto stores all identity data in PostgreSQL. When running without Docker, you must provide a live instance (e.g., via Homebrew, apt, or a local container).

Optional Development Tools

Certain workflows require additional utilities:

• Git: Needed if you clone the repository and run local development scripts.
• rsync: Required by @logto/core for copying API docs during the prepack step. Install via sudo apt-get install -y rsync if missing, as noted in .agents/skills/logto-dev-environment/SKILL.md.

Deployment Methods

Choose one of the following approaches based on your environment.

Docker Compose Quick Start

This method pulls official images and creates a PostgreSQL container automatically. Execute the one-liner from the README.md:

curl -fsSL https://raw.githubusercontent.com/logto-io/logto/HEAD/docker-compose.yml \
  | docker compose -p logto -f - up

The docker-compose.yml file defines the service orchestration, including database initialization and port mappings.

Local Development with Node.js

For development or debugging, scaffold a new instance and run the source code:

# Scaffold a new Logto instance

npm init @logto

# Install workspace dependencies

pnpm i

# Seed the database (first run only)

pnpm db seed

# Start Core, Console, and Experience services

pnpm start:dev

This workflow requires a running PostgreSQL instance accessible from your development machine.

Logto Cloud

The Logto Cloud SaaS offering requires no local installation or dependency management, as the infrastructure is managed externally.

Key Configuration Files

The following files in the logto-io/logto repository define the requirements and setup procedures:

• README.md: Contains the high-level installation guide, Docker Compose command, and Node.js setup instructions.
• docker-compose.yml: Defines the multi-container setup including PostgreSQL and Logto services.
• packages/core/README.md: Documents building and running the Core OIDC service.
• .agents/skills/logto-dev-environment/SKILL.md: Lists required development tools including rsync.
• package.json and pnpm-lock.yaml: Configure the monorepo’s pnpm workspace structure.

Summary

• Docker Compose is the fastest method, requiring only Docker Desktop and Docker Compose.
• Node.js development requires Node.js ≥16, pnpm, and PostgreSQL ≥13 running locally.
• PostgreSQL ≥13 is mandatory for all on-premise deployments to store identity data.
• rsync is optionally required for API documentation generation in the Core package.
• Logto Cloud eliminates local requirements for production deployments.

Frequently Asked Questions

What is the minimum Node.js version required for Logto?

The minimum Node.js version is 16 or higher, as specified in the README.md Node.js section. This version is required to run the initialization scripts, build the monorepo packages with pnpm, and execute the development server.

Can I run Logto without Docker?

Yes, you can run Logto without Docker by using the Node.js + pnpm workflow. However, you must provide a separate PostgreSQL ≥13 database instance, as Logto does not support SQLite or other database engines for identity data storage.

Why is PostgreSQL required for Logto?

Logto stores all identity data, authentication sessions, and configuration in PostgreSQL. The database is a hard dependency for all on-premise deployments, whether using Docker Compose (which creates a PostgreSQL container automatically) or running Node.js locally (which requires you to connect to an existing instance).

What is rsync used for in Logto development?

According to the source code in .agents/skills/logto-dev-environment/SKILL.md, rsync is required by the @logto/core package to copy API documentation files during the pnpm prepack build step. If this utility is missing from your system, the build process will fail when generating the Core package.

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