# How to Install Logto Docker: Complete Setup Guide

> Install Logto Docker easily with our complete setup guide. Clone the repository and run a single command to get Logto and its admin console running on ports 3001 and 3002.

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

---

**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`](https://github.com/logto-io/logto/blob/main/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:

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

```yaml
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`](https://github.com/logto-io/logto/blob/main/docker-compose.override.yml) file to customize these values:

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

```bash
docker compose up -d --force-recreate

```

## Running the Integration Test Stack

For CI pipelines or integration testing, use the [`docker-compose.integration.yml`](https://github.com/logto-io/logto/blob/main/docker-compose.integration.yml) file. This configuration adds a **Redis** container and mounts temporary volumes for test data:

```bash
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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/docker-compose.override.yml) or direct container injection.
- Use **[`docker-compose.integration.yml`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/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`](https://github.com/logto-io/logto/blob/main/docker-compose.yml)** provides a minimal two-container setup (Logto + PostgreSQL) for local development and demos. The **[`docker-compose.integration.yml`](https://github.com/logto-io/logto/blob/main/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.