Skip to content

Clerk Authentication Setup

This guide will help you set up Clerk authentication for the Diskover application.

Quick Setup (5 minutes)

1. Create a Clerk Account

  1. Go to clerk.com
  2. Sign up for a free account
  3. Create a new application (give it any name, e.g., "Diskover Dev")

2. Get Your API Keys

  1. In your Clerk Dashboard, go to API Keys in the left sidebar
  2. You'll see two keys:
  3. Publishable Key - starts with pk_test_
  4. Secret Key - starts with sk_test_ (click "Show" to reveal it)

3. Configure Your Environment Variables

Backend Configuration (root .env file)

Open /Users/ace/mudah/repos/diskover-app/.env and replace:

CLERK_SECRET_KEY=your_clerk_secret_key_here

With your actual Secret Key:

CLERK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Frontend Configuration (frontend/.env file)

Open /Users/ace/mudah/repos/diskover-app/frontend/.env and replace:

VITE_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key_here

With your actual Publishable Key:

VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4. Configure Clerk URLs (Important!)

In your Clerk Dashboard, go to Paths and configure:

  • Sign-in URL: /login
  • Sign-up URL: /register
  • After sign-in URL: /dashboard
  • After sign-up URL: /dashboard

5. Start Your Application

make dev

The application should now: - Frontend: http://localhost:3000 - Backend: http://localhost:8080 - Display the homepage with working authentication

Staging & Production Setup

For deployed environments you should create two separate Clerk applications so that staging and production have fully isolated user pools and configuration.

1. Create Two Clerk Applications

In the Clerk Dashboard, create:

Application Purpose Key Prefixes
Diskover Staging Testing & QA pk_test_ / sk_test_
Diskover Production Live users pk_live_ / sk_live_

2. Configure Each Application

In both Clerk applications, go to Paths and set:

  • Sign-in URL: /login
  • Sign-up URL: /register
  • After sign-in URL: /dashboard
  • After sign-up URL: /dashboard

3. Set Allowed Origins & Redirect URLs

For each Clerk application, go to Domains and add the allowed origins that match your deployment:

Application Allowed Origins
Diskover Staging https://staging.yourdomain.com
Diskover Production https://yourdomain.com

Important: Keys from different Clerk applications are not interchangeable. The backend CLERK_SECRET_KEY and frontend VITE_CLERK_PUBLISHABLE_KEY must come from the same Clerk application.

Clerk Configuration for Railway

When deploying to Railway, set these environment variables in each service:

Backend Service

CLERK_SECRET_KEY=sk_test_...   # staging (from "Diskover Staging" app)
# or
CLERK_SECRET_KEY=sk_live_...   # production (from "Diskover Production" app)

Frontend Service

VITE_CLERK_PUBLISHABLE_KEY=pk_test_...   # staging (from "Diskover Staging" app)
# or
VITE_CLERK_PUBLISHABLE_KEY=pk_live_...   # production (from "Diskover Production" app)

See DEPLOYMENT.md for the full list of Railway environment variables.

Troubleshooting

Blank Homepage

  • Cause: Missing or invalid VITE_CLERK_PUBLISHABLE_KEY
  • Solution: Check that you've added the correct publishable key in frontend/.env

API Authentication Errors

  • Cause: Missing or invalid CLERK_SECRET_KEY
  • Solution: Check that you've added the correct secret key in root .env

Environment Variables Not Loading

  • Cause: Vite needs to be restarted after .env changes
  • Solution:
  • Stop the dev server (Ctrl+C)
  • Run make dev again

"Invalid Clerk Configuration"

  • Cause: Keys don't match or are from different Clerk applications
  • Solution:
  • Go to your Clerk Dashboard
  • Make sure both keys are from the same application
  • Copy them again carefully

Security Notes

  • ⚠️ Never commit .env files - They contain sensitive keys
  • ✅ .env files are already in .gitignore
  • ✅ Use .env.example files to share configuration templates
  • 🔒 Secret keys should only be used server-side (backend)
  • 🔓 Publishable keys are safe to use client-side (frontend)

Production Deployment

For production deployment to Railway or other platforms:

  1. Add the same environment variables in your platform's dashboard
  2. Use production keys (starting with pk_live_ and sk_live_)
  3. See DEPLOYMENT.md for detailed deployment instructions

Need Help?