Self-Hosting prompts.chat: Environment Variables and Authentication Provider Setup

To self-host prompts.chat, configure a PostgreSQL connection string, a session encryption secret, and at least one OAuth provider credential set in your .env file, then restart the server.

Self-hosting prompts.chat requires setting specific environment variables to connect your PostgreSQL database, secure user sessions via NextAuth.js, and enable third-party authentication. The application reads these variables at runtime from process.env, allowing you to modify behavior without rebuilding the application. This guide covers every variable defined in the project's SELF-HOSTING.md and explains how each is consumed by the Prisma client and authentication modules.

Required Core Environment Variables

Database Connection

The Prisma client requires DATABASE_URL to connect to your PostgreSQL instance. In src/lib/db.ts, the client initializes using this connection string directly from process.env.DATABASE_URL.

Set the variable to a standard PostgreSQL connection URI:

DATABASE_URL="postgresql://myuser:mypassword@localhost:5432/prompts"

Session Encryption

NextAuth.js uses AUTH_SECRET to encrypt session cookies and secure tokens. In src/lib/auth/index.ts, this value is passed to the secret option of the NextAuth configuration.

Generate a cryptographically strong value and add it to your environment:

openssl rand -base64 32

AUTH_SECRET="your-generated-secret-here"

Configuring Authentication Providers

The authentication system in src/lib/auth/index.ts dynamically builds its provider list based on which AUTH_* variables are present. Each provider module lives under src/lib/plugins/auth/ and reads its specific credentials from the environment.

GitHub OAuth

To enable GitHub sign-in, set the client credentials from your GitHub App:

AUTH_GITHUB_ID="your-github-client-id"
AUTH_GITHUB_SECRET="your-github-client-secret"

These variables are consumed by src/lib/plugins/auth/github.ts to initialize the GitHub provider.

Google OAuth

For Google authentication, configure the OAuth 2.0 credentials:

AUTH_GOOGLE_ID="your-google-client-id"
AUTH_GOOGLE_SECRET="your-google-client-secret"

The Google provider implementation in src/lib/plugins/auth/google.ts references these variables.

Azure AD and Apple

For enterprise or Apple ecosystem deployments, configure the respective variable sets:

Azure AD:

AUTH_AZURE_AD_CLIENT_ID="your-azure-client-id"
AUTH_AZURE_AD_CLIENT_SECRET="your-azure-client-secret"
AUTH_AZURE_AD_ISSUER="https://login.microsoftonline.com/<tenant-id>/v2.0"

Apple Sign-In:

AUTH_APPLE_ID="your-apple-id"
AUTH_APPLE_TEAM_ID="your-team-id"
AUTH_APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."
AUTH_APPLE_KEY_ID="your-key-id"

Azure configuration is handled in src/lib/plugins/auth/azure.ts.

Email and Password Credentials

For simple deployments without OAuth, enable the credentials provider:

AUTH_CREDENTIALS_USERNAME="admin@example.com"
AUTH_CREDENTIALS_PASSWORD="super-secret-pwd"

The module at src/lib/plugins/auth/credentials.ts validates these values against user submissions.

Enabling Optional AI Features

To power semantic search with OpenAI embeddings, provide an API key:

OPENAI_API_KEY="sk-your-openai-key"

The AI utilities in src/lib/ai/embeddings.ts import this key when calling the OpenAI API. Without this variable, the embedding functionality remains disabled but the core application functions normally.

Step-by-Step Setup Process

Follow these steps to configure your self-hosted instance:

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and set the Database section with your PostgreSQL credentials.

3. Generate and set AUTH_SECRET using openssl rand -base64 32 or a similar secure random generator.

4. Uncomment and fill in at least one Authentication section (GitHub or Google recommended for production).

5. Optionally add OPENAI_API_KEY for AI-powered features.

6. Restart the Node process:

   npm run dev

   Upon restart, sign-in buttons for your configured providers automatically appear on the login page.

Adding Custom Authentication Providers

If you require an OAuth provider not pre-bundled in src/lib/plugins/auth/, create a new module:

// src/lib/plugins/auth/example.ts
import { OAuthProvider } from "next-auth/providers";

export const ExampleProvider = OAuthProvider({
  clientId: process.env.AUTH_EXAMPLE_ID!,
  clientSecret: process.env.AUTH_EXAMPLE_SECRET!,
  // provider-specific configuration …
});

Import this provider in src/lib/auth/index.ts and add AUTH_EXAMPLE_ID and AUTH_EXAMPLE_SECRET to your .env file. The modular architecture ensures new providers integrate seamlessly with the existing session management.

Summary

• Database: Set DATABASE_URL in src/lib/db.ts to connect PostgreSQL.
• Security: Configure AUTH_SECRET in src/lib/auth/index.ts for session encryption.
• Providers: Choose one or more OAuth providers (GitHub, Google, Azure, Apple) or use credentials auth; each reads specific AUTH_* variables from its module in src/lib/plugins/auth/.
• AI Features: Optionally supply OPENAI_API_KEY for embeddings in src/lib/ai/embeddings.ts.
• Runtime Changes: Modify .env variables without rebuilding; restart the Node process to apply changes.

Frequently Asked Questions

What is the minimum set of environment variables required to run prompts.chat?

You must provide DATABASE_URL for PostgreSQL connectivity, AUTH_SECRET for session security, and at least one authentication provider set such as AUTH_GITHUB_ID and AUTH_GITHUB_SECRET. Without these, the application cannot establish database connections or authenticate users.

Do I need to rebuild the application after changing environment variables?

No. Because the codebase reads process.env at runtime, you can modify any variable in your .env file and simply restart the Node process (npm run start or npm run dev) to apply changes. No rebuild step is required.

Can I enable multiple authentication providers simultaneously?

Yes. The NextAuth configuration in src/lib/auth/index.ts dynamically constructs the provider array based on which AUTH_* variables are present. You can configure GitHub, Google, and Azure AD concurrently, and all will appear as options on the sign-in page.

Where are the official self-hosting instructions maintained?

The definitive documentation resides in SELF-HOSTING.md at the repository root. This file contains the complete environment variable reference, deployment architecture diagrams, and troubleshooting steps specific to the f/prompts.chat codebase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}