How to Run Logto Locally: Docker Compose and Node.js Setup Guide

You can run Logto locally using either Docker Compose for a containerized environment or Node.js with pnpm for development, both requiring a PostgreSQL database and initial seeding with pnpm cli db seed.

Logto is a modular, open-source authentication platform maintained by logto-io/logto that provides OIDC/OAuth 2.1 capabilities through multiple interconnected packages. To run Logto locally, you must provision a PostgreSQL database, start the core services, and optionally seed initial data. This guide covers both the Docker Compose approach for production parity and the Node.js workflow for active development.

Prerequisites: PostgreSQL Database

Logto stores all tenant, user, and configuration data in PostgreSQL. Before starting any services, export the DB_URL environment variable with your connection string:

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

The core server reads this variable during startup to establish database connections.

Method 1: Run Logto Locally with Docker Compose

The Docker Compose approach pulls pre-built images for the core server and the Vite-based admin/experience front-ends, wiring them together with an automatically created database container. This method mirrors production environments and requires no local Node.js installation.

According to the root README.md, execute the following command to download and start all services:

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

This single command provisions the PostgreSQL instance, starts the OIDC/OAuth 2.1 core server, and serves the Console and Experience UIs.

Method 2: Run Logto Locally with Node.js

For debugging or extending individual packages in packages/core, packages/console, or packages/experience, use the Node.js workspace approach. The repository is built as a monorepo using pnpm workspaces.

Initialize and Install

First, initialize a new Logto project and install dependencies:

npm init @logto

Configure Environment

Set the database connection string:

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

Seed the Database

On first launch, the database must be seeded with default schemas and admin data. The repository provides CLI commands documented in packages/core/README.md:

pnpm cli db seed
pnpm cli connector link -p .

The db seed command creates the necessary tables and admin user, while connector link -p . registers the built-in connectors located in the repository root.

Start Development Servers

Launch all services simultaneously:

pnpm start:dev

This command starts the Core authentication server, the Console admin UI, and the Experience sign-in interface against your local PostgreSQL instance.

Understanding the Package Architecture

The Logto repository organizes functionality into separate npm workspaces:

• packages/core/: Contains the OIDC/OAuth 2.1 authentication server and CLI tools. See packages/core/README.md for environment variables and database alteration commands.
• packages/console/: Houses the React-based admin dashboard. Refer to packages/console/README.md for UI-specific development details.
• packages/experience/: Provides the sign-in experience SPA. Consult packages/experience/README.md for front-end build configurations.
• packages/elements/: Contains reusable UI components used by both Console and Experience packages, documented in packages/elements/README.md.
• packages/api/: Defines the OpenAPI specifications for the RESTful management API that the core server exposes.

When running pnpm start:dev, the workspace scripts orchestrate these packages to provide a fully functional authentication platform.

Summary

• PostgreSQL is mandatory: Logto persists all tenant and user data in PostgreSQL, configured exclusively via the DB_URL environment variable.
• Two installation paths: Use Docker Compose for quick, production-like deployment or Node.js with pnpm for active development and debugging.
• Database seeding required: First-time setups must run pnpm cli db seed and pnpm cli connector link -p . to initialize schemas and register connectors.
• Modular architecture: The repository separates concerns into distinct packages (core, console, experience) within a unified workspace.

Frequently Asked Questions

What are the system requirements to run Logto locally?

You need Docker Desktop for the containerized approach, or Node.js 18+ and pnpm for development. A running PostgreSQL 14+ instance is mandatory for both methods, with connection details passed via the DB_URL environment variable as specified in packages/core/README.md.

Can I run Logto locally without Docker?

Yes. The Node.js workflow allows you to run Logto directly using pnpm start:dev after initializing the project with npm init @logto and seeding the database. This method is documented in the root README.md under the local development section and provides fine-grained control for debugging individual packages.

How do I reset the Logto database during development?

Drop and recreate the PostgreSQL database, then rerun the seeding commands: pnpm cli db seed followed by pnpm cli connector link -p .. This clears all tenant data and restores the default admin account and built-in connectors according to the CLI implementation in the core package.

Which Logto services start when I run the development command?

The pnpm start:dev command launches three main services defined in the workspace: the Core authentication server handling OIDC/OAuth 2.1 flows, the Console admin dashboard UI, and the Experience sign-in interface. Each corresponds to its respective package directory under packages/.

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