Self-host Logto on a VPS: your own authentication layer

What Logto actually is — and what it is not

Prerequisites

How Logto works in production

What Logto provides out of the box

• OIDC/OAuth 2.0 compliant tokens — signed JWTs that any standard library (passport.js, python-jose, go-oidc) can verify without custom code.
• Social login connectors — enable Google, GitHub, Apple, Microsoft, Discord and 30+ providers from the admin console in one click; each requires a 5-minute OAuth App setup on the provider side.
• Passwordless authentication — send magic links (email) or OTP codes (SMS via Twilio, SendGrid, Mailgun) without maintaining a separate notification service.
• MFA — TOTP (Google Authenticator, Authy), WebAuthn/FIDO2 hardware keys, and backup codes, enforced by policy from the admin console.
• Role-based access control — define roles and permissions in the console; receive them as scope claims in the JWT and enforce them in your API with a single middleware line.
• SDKs for 20+ frameworks — React, Next.js, Vue, Angular, React Native, Flutter, Python, FastAPI, Go, PHP, Laravel, .NET, Java, Spring Boot and more.

Docker Compose deployment step by step

1. 01

   Create the working directory and Compose file

   Connect to your VPS via SSH and create the working directory:

   mkdir -p /opt/logto && cd /opt/logto

   Create the docker-compose.yml file with the following content. Replace auth.your-domain.com with your own domain:

   version: '3.9'
   services:
     db:
       image: postgres:17-alpine
       restart: unless-stopped
       environment:
         POSTGRES_DB: logto
         POSTGRES_USER: logto
         POSTGRES_PASSWORD: ${DB_PASSWORD}
       volumes:
         - logto_db:/var/lib/postgresql/data
     logto:
       image: svhd/logto:latest
       restart: unless-stopped
       depends_on:
         - db
       ports:
         - '127.0.0.1:3001:3001'
         - '127.0.0.1:3002:3002'
       environment:
         DB_URL: postgresql://logto:${DB_PASSWORD}@db:5432/logto
         ENDPOINT: https://auth.your-domain.com
         ADMIN_ENDPOINT: https://auth.your-domain.com:3002
         SECRET_VAULT_KEK: ${SECRET_VAULT_KEK}
   volumes:
     logto_db:

2. 02

   Generate secrets and create the .env file

   Generate a strong database password and an AES-256 key:

   DB_PASSWORD=$(openssl rand -hex 32)
   SECRET_VAULT_KEK=$(openssl rand -hex 32)
   printf "DB_PASSWORD=%s\nSECRET_VAULT_KEK=%s\n" "$DB_PASSWORD" "$SECRET_VAULT_KEK" > .env
   chmod 600 .env

   Verify that .env contains two non-empty lines before proceeding.

3. 03

   Configure nginx as a reverse proxy

   Create the vhost /etc/nginx/sites-available/logto:

   server {
       listen 443 ssl;
       server_name auth.your-domain.com;
       ssl_certificate /etc/letsencrypt/live/auth.your-domain.com/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/auth.your-domain.com/privkey.pem;
   
       location / {
           proxy_pass http://127.0.0.1:3001;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto https;
       }
   }

   Enable the site and reload nginx:

   ln -s /etc/nginx/sites-available/logto /etc/nginx/sites-enabled/
   nginx -t && systemctl reload nginx

4. 04

   Start the stack and verify

   Launch both containers:

   docker compose up -d

   Follow the logs for 60 seconds to confirm PostgreSQL is ready and Logto has completed its migrations:

   docker compose logs -f --tail=50

   You should see the line App is running at https://auth.your-domain.com — that is the signal the service is operational.

5. 05

   Verify the OIDC discovery document

   From your local machine, check that the OIDC endpoint responds:

   curl -s https://auth.your-domain.com/.well-known/openid-configuration | python3 -m json.tool | head -10

   The response must contain issuer, authorization_endpoint and jwks_uri. If the command returns a 502 error, Logto has not yet completed its migrations — wait 30 seconds and try again.

6. 06

   Set up automatic backups

   Add a cron job to export the database daily:

   crontab -e
   # Add the following line:
   0 3 * * * docker exec $(docker compose -f /opt/logto/docker-compose.yml ps -q db) pg_dump -U logto logto | gzip > /var/backups/logto_$(date +\%Y\%m\%d).sql.gz

   For automated, deduplicated, encrypted backups to S3 or Backblaze B2, mount the logto_db volume to a Backrest instance available in the ServOrbit catalogue.

Logging in for the first time

1. 07

   Open the SSH tunnel to the admin console

   The admin console listens on port 3002, bound to localhost for security. From your local machine, open a tunnel:

   ssh -L 3002:127.0.0.1:3002 root@your-vps-ip

   Keep this terminal open for the duration of your admin session.

2. 08

   Create the administrator account

   Open http://localhost:3002 in your browser. The first-run wizard appears — there are no default credentials. Enter an email address and a strong password, then click Create account. These credentials are yours for administering Logto; store them in a password manager.

3. 09

   Explore the dashboard

   After creating the account, you land on the Logto dashboard. From here you can view the audit log, manage users, configure social connectors, and create Applications — the Logto entity that represents one of your projects.

4. 10

   Create your first Application

   In the console: Applications → Create application. Choose the type that matches your project (Traditional Web, Single Page App, Native, or Machine-to-machine). Give it a name, then fill in the Redirect URI — the URL Logto redirects to after a successful login (for example https://my-app.com/api/logto/sign-in-callback for a Next.js application). Logto then generates an App ID and App Secret that you will use in your SDK.

Integrating Logto into a Next.js application

Enabling Google social login

Logto, Authentik, Authelia, Keycloak — which one to choose?

Scroll the table

For a SaaS product under development, Logto is the natural starting point. Keycloak suits organisations that already have an enterprise directory to integrate. Authelia and Authentik address infrastructure needs rather than application needs.

Common troubleshooting

Backup strategy