What Are the Prerequisites for Logto Development? Complete Setup Guide

To develop Logto locally, you need Docker Desktop or Node.js 18+, pnpm 8+, PostgreSQL 13+, Git, and rsync (Linux/macOS), with optional Playwright browsers for UI testing.

Logto is a full-stack open-source authentication platform maintained by the logto-io/logto repository. Before you can build the core services, admin console, or connector ecosystem from source, you must install specific runtime dependencies and tooling. This guide covers the exact prerequisites for Logto development based on the official source code and documentation.

Essential System Requirements

Logto operates as a monorepo containing Node.js backend services and Vite-powered frontend applications. The following tools are mandatory regardless of whether you use containerized or native development workflows.

Docker Desktop or Docker Engine

Docker is required for the Docker Compose quick-start, which launches Postgres, the Logto Core server, and the two Vite front-ends in containers. According to the root README.md, the Docker Compose command pulls the docker-compose.yml file and starts services on ports 3001, 3002, 5001, and 5002.

While you can develop without Docker using the Node.js workflow, the containerized approach is the fastest way to spin up the full stack.

Node.js 18 or Higher

The Node-based development flow requires Node.js 18+ as the minimum version supported by the monorepo. This runtime is used to build Logto from source and execute the backend and front-ends with pnpm.

pnpm Package Manager (Version 8+)

Logto uses a monorepo managed by pnpm workspaces. All package scripts—including pnpm start:dev, pnpm prepack, and test suites—rely on pnpm being installed globally or via corepack. The repository requires pnpm version 8 or higher to resolve workspace dependencies correctly.

PostgreSQL 13+

Logto stores all tenant data in a PostgreSQL database. The Docker Compose setup automatically starts a PostgreSQL container, while the Node-based flow requires a local PostgreSQL instance accessible via the DB_URL environment variable. PostgreSQL 13 is the minimum supported version.

Git and rsync

Git is required to clone the repository and manage branches as outlined in .github/CONTRIBUTING.md. Additionally, rsync (Linux/macOS) is required for specific build steps. For example, the @logto/core package uses rsync in its copy:apidocs script to synchronize API documentation files, as documented in .agents/skills/logto-dev-environment/SKILL.md.

Container-Based Quick Start

The Docker Compose method provides an all-in-one environment without installing Node.js or PostgreSQL locally.

Run the following command from your terminal to download and start the stack:

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

This command pulls the official docker-compose.yml and initializes Postgres, Core (ports 3001/3002), and the two Vite apps (ports 5001/5002).

Node.js Development Workflow

For contributors who need full source control, debugging capabilities, and unit/integration testing, use the native Node.js workflow.

First, enable pnpm via corepack if you haven't already:

corepack enable && corepack prepare pnpm@8.6.0 --activate

Scaffold the repository and install dependencies:

npm init @logto

Start the development server with hot-reload for Core, Console, and Experience:

pnpm start:dev

This workflow is documented in the root README.md and detailed further in packages/core/README.md, which explains environment variables, database migrations, and pre-pack steps.

Optional: UI Testing Prerequisites

If you plan to run the @logto/elements UI test suite, you must install Playwright browsers. The package requires Chromium for end-to-end testing.

Install the browser binaries:

pnpm exec playwright install chromium --with-deps

Execute the test suite:

pnpm test:only packages/elements

This setup is documented in packages/elements/README.md.

Summary

• Docker Desktop provides the fastest path to running Logto via Docker Compose, eliminating the need for local Node.js or PostgreSQL installations.
• Node.js 18+, pnpm 8+, and PostgreSQL 13+ are mandatory for the source-based development workflow.
• Git and rsync are required for repository operations and specific build scripts like copy:apidocs in packages/core.
• Playwright browsers are only necessary when running UI tests for the @logto/elements package.

Frequently Asked Questions

Do I need both Docker and Node.js to develop Logto?

No. You can choose either the Docker Compose workflow (which only requires Docker) or the Node.js workflow (which requires Node.js, pnpm, and PostgreSQL). The Docker approach is ideal for quick evaluation, while the Node.js workflow is preferred for contributing code and running tests.

What is the minimum PostgreSQL version required for Logto?

Logto requires PostgreSQL 13 or higher. The docker-compose.yml file automatically provisions a compatible version, but if you use a local database instance, ensure it meets this minimum version to support the tenant data schemas.

Why does Logto require pnpm instead of npm or yarn?

Logto is organized as a monorepo using pnpm workspaces to manage dependencies across packages like @logto/core, @logto/console, and @logto/experience. The build scripts, dev server commands, and package linking are specifically configured for pnpm, as implemented in the logto-io/logto source code.

How do I verify that my Logto development environment is configured correctly?

For Docker setups, verify that containers for Postgres, Core, and the Vite apps start without errors on ports 3001, 3002, 5001, and 5002. For Node.js setups, run pnpm start:dev and confirm that the Core server connects to PostgreSQL via your configured DB_URL. You can also run pnpm prepack in packages/core to validate that rsync and other build tools are functioning.

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