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

> Run Logto locally effortlessly. Follow our guide for Docker Compose or Node.js setup, connecting to PostgreSQL and seeding your database for a seamless development experience.

- Repository: [Logto/logto](https://github.com/logto-io/logto)
- Tags: how-to-guide
- Published: 2026-06-30

---

**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:

```bash
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`](https://github.com/logto-io/logto/blob/main/README.md), execute the following command to download and start all services:

```bash
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:

```bash
npm init @logto

```

### Configure Environment

Set the database connection string:

```bash
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`](https://github.com/logto-io/logto/blob/main/packages/core/README.md):

```bash
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:

```bash
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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/packages/console/README.md) for UI-specific development details.
- **`packages/experience/`**: Provides the sign-in experience SPA. Consult [`packages/experience/README.md`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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/`.