⚡ Get started

There are some nuanced differences in accessing Logto Console between the Logto OSS (open-source software) and Logto Cloud.

Logto Cloud

Logto Cloud is a Software-as-a-Service (SaaS) version of Logto. It offers users more options for account creation and basic cloud operations than the open-source version.

Users can sign up and sign in using Google, GitHub, email with a password, or a verification code. Once you've entered the cloud, you can manage your resources and profile information within the platform.

During sign-up, you'll go through an onboarding flow that helps Logto understand your needs and preferences to personalize your experience. Although it only takes a few steps, the onboarding flow can be incredibly helpful in quickly getting started and successfully building authentication and authorization.

Logto OSS (self-hosted)

GitPod

To start an online GitPod workspace for Logto, click here. Wait a few moment, you'll see the message like:

Logto uses port 3001 for its core service and port 3002 for the interactive Admin Console by default.

To continue your Logto journey, press Ctrl (or Cmd) and click the link that starts with https://3002-.... Enjoy!

Local

Docker Compose

Docker Compose CLI usually comes with Docker Desktop.

caution

Do not use our docker compose command for production! Since we currently have a built-in Postgres database bundled together with the Logto app in docker-compose.yml, every time you re-execute the command a new database instance will be created, and any data persisted previously will be lost.

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

After a successful composition, you will see the message like:

Docker

Step 1

Prepare a PostgreSQL@^14.0 instance, and using Logto CLI to seed a database for Logto:

CLI

logto db seed

npx

npx @logto/cli db seed

Step 2

Pull the image:

# ghcr
docker pull ghcr.io/logto-io/logto:latest
# DockerHub
docker pull svhd/logto:latest

Step 3

Map the container ports to Logto core and admin app, e.g., 3001:3001 and 3002:3002; and set the following environment variables to the container:

TRUST_PROXY_HEADER: 1 # Set to 1 if you have an HTTPS proxy (e.g. Nginx) in front of Logto
ENDPOINT: https://<your-logto-domain> # (Optional) Replace with your Logto endpoint URL if you are using a custom domain
ADMIN_ENDPOINT: https://<your-logto-admin-domain> # (Optional) Replace with your Logto admin URL if you are using a custom domain
DB_URL: postgres://username:password@your_postgres_url:port/db_name # Replace with your Postgres DSN

Run the container with all the environment variables above:

docker run \
  --name logto \
  -p 3001:3001 \
  -p 3002:3002 \
  -e TRUST_PROXY_HEADER=1 \
  -e ENDPOINT=https://<your-logto-domain> \
  -e ADMIN_ENDPOINT=https://<your-logto-admin-domain> \
  -e DB_URL=postgres://username:password@your_postgres_url:port/db_name \
  ghcr.io/logto-io/logto:latest

tip

• If you are using Docker Hub, use svhd/logto:latest instead of ghcr.io/logto-io/logto:latest.
• Use host.docker.internal or 172.17.0.1 in DB_URL to refer to the host IP.

Finally, you will see the message like:

npm-init

Prerequisites

• Node.js ^18.12.0

• PostgreSQL ^14.0

  Install PostgreSQL on Mac

  In case we would like to test a deployment, we could install a local PostgreSQL on, for example, Mac with homebrew:

  brew install postgresql@15
  echo 'export PATH="/usr/local/opt/postgresql@15/bin:$PATH"' >> /Users/.../.bash_profile
  brew services start postgresql@15

  Let's create a DB with

  $ psql postgres
  psql (15.5 (Homebrew))
  Type "help" for help.
  
  postgres=# CREATE DATABASE logto;

  This database will be accessible via postgresql://localhost:5432/logto

Higher versions usually work but are not guaranteed.

We recommend using a new empty database which is dedicated for Logto, while it's not a hard requirement.

Download and start

In your terminal:

npm init @logto@latest

Once you complete the init process and start Logto, you will see the message like:

Core app is running at http://localhost:3001
Core app is running at https://your-domain-url
Admin app is running at http://localhost:3002
Admin app is running at https://your-admin-domain-url

Heading to http://localhost:3002/ to continue your Logto journey. Enjoy!

Using an alternative URL for downloading

If you want to specify a URL for the Logto zip file, use the --download-url option. For example:

npm init @logto@latest -- --download-url=https://github.com/logto-io/logto/releases/download/v1.2.2/logto.tar.gz

Note the extra -- is needed for NPM to pass the arguments.

Configuration (optional)

Logto uses environment variables for configuration, along with .env file support. See Configuration for detailed usage and full variable list.

Check out Core Service if you want more advanced controls or programmatic access to Logto.

Quick troubleshooting

My browser cannot load Admin Console (showing error Crypto.subtle is unavailable...)

Admin Console uses Web Crypto API, which requires secure contexts, i.e. HTTPS or HTTP with localhost.

If you use HTTP with an IP address or custom domain, then the browser cannot load Admin Console.

I'm using a custom domain, but my browser cannot load Admin Console (showing error "code": "oidc.invalid_redirect_uri")

If you are using a custom domain rather than localhost, you need to set the environment variable ENDPOINT to the Logto URL. It is because of the strict requirement of Redirect URI in OIDC. See Configuration for details.

I'm using an HTTPS proxy (e.g., Nginx) in front of Logto, but I failed on sign-in (showing error TypeError: Failed to fetch)

• First, make sure you have set the node environment variable TRUST_PROXY_HEADER to true. See Configuration for details.
• Also, you need to set X-Forwarded-Proto header to https in your proxy config. See Trusting TLS offloading proxies for details.

I'm facing CORS issues.

• If ADMIN_ENDPOINT is not specified, localhost:[admin-port] will be allowed to perform Cross-Origin Resource Sharing (CORS) in Logto.
• If ADMIN_ENDPOINT is specified, only requests from the origin of ADMIN_ENDPOINT will be allowed.

What is this again? Error: Invalid id token

If you are not messing up with your tokens, then in most cases this is caused by a mismatch of your server time and client time. Sync the time on both your server and client and try again.

Create an account

Once you have successfully hosted Logto on your server, click on "Create Account" on the welcome page. Keep in mind that the open-source version of Logto only allows for one account creation during the initial launch and does not support multiple accounts. The account creation process is limited to username and password combinations.