Overview

In LobeHub 2.0, we will consolidate to a single authentication solution: BetterAuth. Support for AuthJS (NextAuth) and Clerk will be removed.

Why

• Clerk's customization is not flexible enough; for example, our clerk business requires the login component to support entering discount codes.
• Clerk's login component loads slowly.
• AuthJS has been acquired by Better-Auth and is no longer maintained.

What will be added

• Email/password authentication, this also reduces self-deployment costs
• Magic link sign-in

Related Repositories

• Documentation site: lobehub/lobehub-landing (menu configuration)
• lobe-chat: lobehub/lobe-chat
  • Auth refactoring: src/libs/clerk-auth, src/libs/next-auth
  • Documentation: docs/self-hosting

Task Breakdown

0. Environment Variables Optimization

• Remove NEXT_PUBLIC_AUTH_URL environment variable, client relies on Better Auth default behavior, server uses APP_URL (LOBE-3914)

1. Update BetterAuth Documentation

• Hide NextAuth and Clerk docs from menu, but retain accessibility (don't delete corresponding mdx in lobechat repo)
• Change auth docs to BetterAuth content
• Update auth environment variable configuration in deployment docs
• Remove NEXT_PUBLIC_SERVICE_MODE content
• JWKS
• Remove NEXT_PUBLIC_ENABLE_BETTER_AUTH
• Provide one-click auth secret generation

2. Remove Clerk

• Add migration script (JS script to migrate existing database data to new schema)
• Add migration documentation
• Remove Clerk code

3. Remove NextAuth

• Add migration script (JS script to migrate existing database data to new schema)
• Add migration documentation
• Remove NextAuth code

4. Docker Configuration Optimization

• Change Docker default Auth from Next Auth to Better Auth (modify Dockerfile defaults, update documentation Callout) (LOBE-3915)

5. Docker Compose Optimization

setup.sh improvements:

• Auto-generate JWKS_KEY
• Auto-generate KEY_VAULTS_SECRET (currently hardcoded)
• No longer need to auto-generate lobe-chat user, casdoor admin user

Architecture simplification:

• Remove Casdoor (BetterAuth now supports email/password registration)
• Replace MinIO (no longer maintained, need to find alternative)
• Remove otel and other images (not needed by regular users, keep only lobe, pg, s3)

6. Others

• Show last used auth provider on login page (localStorage record)
• Redis documentation, benefits: session cache, file proxy acceleration, etc.
• Search @deprecated and remove deprecated code

Current Status

• Step 1: Support BetterAuth on the next branch (✨ feat: support better-auth #10215)
• Step 2: Migrate Clerk to BetterAuth (in progress)
• Step 3: Migrate AuthJS to BetterAuth

Important Note

Migrating existing NextAuth or Clerk deployments to better-auth is not yet officially supported. For best results, use better-auth with a clean database on new projects.