Deployment and Usage Guide for prompts.chat

1. Prerequisites

Before deploying prompts.chat, ensure you have the following installed:

Runtime & Tools:

Node.js (version 18 or higher)
npm (comes with Node.js) or yarn or pnpm
Git (for cloning the repository)
Docker (optional, for containerized deployment)
PostgreSQL (version 14 or higher) or compatible database

Accounts (for authentication):

GitHub OAuth App (for GitHub login)
Google Cloud Project (for Google login)
Microsoft Azure AD App (for Azure AD login)
(Optional) Email service provider (SMTP credentials)

AI Integration (optional):

OpenAI API key (for prompt improvement features)
Anthropic Claude API key (optional)
Google Gemini API key (optional)

2. Installation

Quick Start (Recommended)

# Create a new instance with setup wizard
npx prompts.chat new my-prompt-library
cd my-prompt-library

Manual Setup

# Clone the repository
git clone https://github.com/f/prompts.chat.git
cd prompts.chat

# Install dependencies
npm install

# Run setup wizard
npm run setup

The setup wizard will guide you through:

Branding configuration (name, logo, colors)
Theme selection (light/dark mode)
Authentication providers setup
Feature toggles (public/private prompts, voting, comments)
Database configuration

3. Configuration

Environment Variables

Create a .env.local file in the root directory:

# Database
DATABASE_URL="postgresql://username:password@localhost:5432/prompts_chat"

# Authentication
GITHUB_CLIENT_ID="your_github_client_id"
GITHUB_CLIENT_SECRET="your_github_client_secret"
GOOGLE_CLIENT_ID="your_google_client_id"
GOOGLE_CLIENT_SECRET="your_google_client_secret"
AZURE_AD_CLIENT_ID="your_azure_client_id"
AZURE_AD_CLIENT_SECRET="your_azure_client_secret"
AZURE_AD_TENANT_ID="your_azure_tenant_id"

# API Keys (optional)
OPENAI_API_KEY="sk-..."
ANTHROPIC_API_KEY="sk-ant-..."
GOOGLE_GEMINI_API_KEY="AIza..."

# App Configuration
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your_nextauth_secret_here"
NEXT_PUBLIC_APP_NAME="My Prompt Library"
NEXT_PUBLIC_APP_DESCRIPTION="Private prompt library for our organization"

# Email (optional)
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="your-email@gmail.com"
SMTP_PASSWORD="your-app-password"
SMTP_FROM="noreply@yourdomain.com"

# Feature Flags
NEXT_PUBLIC_ENABLE_PUBLIC_PROMPTS="true"
NEXT_PUBLIC_ENABLE_VOTING="true"
NEXT_PUBLIC_ENABLE_COMMENTS="true"
NEXT_PUBLIC_MCP_ENABLED="true"

Database Schema

Initialize the database:

# Generate Prisma client
npx prisma generate

# Push schema to database
npx prisma db push

# (Optional) Seed with sample data
npm run db:seed

Authentication Providers Setup

GitHub:

Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
Set Homepage URL: http://localhost:3000 (or your domain)
Set Authorization callback URL: http://localhost:3000/api/auth/callback/github
Copy Client ID and Client Secret to .env.local

Google:

Go to Google Cloud Console → APIs & Services → Credentials
Create OAuth 2.0 Client ID (Web application)
Add authorized redirect URI: http://localhost:3000/api/auth/callback/google
Copy credentials to .env.local

Azure AD:

Go to Azure Portal → Azure Active Directory → App registrations → New registration
Set redirect URI: http://localhost:3000/api/auth/callback/azure-ad
Copy credentials to .env.local

4. Build & Run

Development Mode

# Start development server
npm run dev

# The app will be available at http://localhost:3000

Production Build

# Build the application
npm run build

# Start production server
npm start

# Or use the optimized production server
npm run start:prod

Docker Development

# Using Docker Compose (includes PostgreSQL)
docker-compose up -d

# Build and run with Docker
docker build -t prompts-chat .
docker run -p 3000:3000 --env-file .env.local prompts-chat

5. Deployment

Platform Recommendations

Vercel (Recommended for Next.js):

# Install Vercel CLI
npm i -g vercel

# Deploy
vercel

# Set environment variables in Vercel dashboard:
# DATABASE_URL, NEXTAUTH_SECRET, etc.

Railway.app:

# Install Railway CLI
npm i -g @railway/cli

# Link and deploy
railway login
railway init
railway up

Docker Containers:

# Build and push to container registry
docker build -t your-registry/prompts-chat:latest .
docker push your-registry/prompts-chat:latest

# Deploy to Kubernetes
kubectl apply -f k8s/

Traditional Hosting:

# Build on server
npm run build

# Use PM2 for process management
npm install -g pm2
pm2 start npm --name "prompts-chat" -- start
pm2 save
pm2 startup

Database Deployment Options

Managed PostgreSQL:
- AWS RDS
- Google Cloud SQL
- Azure Database for PostgreSQL
- Supabase
- Neon.tech

Connection String Format:

# AWS RDS example
DATABASE_URL="postgresql://username:password@your-rds-endpoint:5432/database?sslmode=require"

MCP Server Deployment

For MCP (Model Context Protocol) integration:

Remote MCP Server:

{
  "mcpServers": {
    "prompts.chat": {
      "url": "https://your-domain.com/api/mcp"
    }
  }
}

Local MCP Server:

{
  "mcpServers": {
    "prompts.chat": {
      "command": "npx",
      "args": ["-y", "prompts.chat", "mcp"]
    }
  }
}

6. Troubleshooting

Common Issues and Solutions

1. Database Connection Failed

# Check if PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -h localhost -U username -d prompts_chat

# If using Docker, ensure container is running
docker ps | grep postgres

2. Authentication Not Working

Verify callback URLs match exactly in OAuth provider settings
Check that NEXTAUTH_URL matches your deployment URL
Ensure NEXTAUTH_SECRET is set and consistent
Check browser console for CORS errors

3. Build Failures

# Clear Next.js cache
rm -rf .next
rm -rf node_modules/.cache

# Reinstall dependencies
npm ci

# Check Node.js version (requires 18+)
node --version

4. MCP Server Not Responding

# Test MCP endpoint
curl -X POST https://your-domain.com/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_api_key" \
  -d '{"method":"tools/list"}'

# Check API key format
# API keys should be generated via user settings in the app

5. Missing Environment Variables

# Generate NEXTAUTH_SECRET
openssl rand -base64 32

# Verify all required variables are set
npm run env:check

6. Performance Issues

# Enable database connection pooling
# Add to DATABASE_URL:
?connection_limit=5&pool_timeout=10

# Optimize Next.js build
NODE_OPTIONS='--max-old-space-size=4096' npm run build

# Enable caching
NEXT_PUBLIC_ENABLE_CACHE="true"

7. Prompt Import/Export Issues

# Export prompts
npm run prompts:export -- --format=csv

# Import prompts
npm run prompts:import -- --file=prompts.csv

# Check file permissions
chmod 644 prompts.csv

Getting Help:

Check logs: npm run logs or docker logs <container_id>
Enable debug mode: DEBUG=* npm run dev
View Prisma logs: PRISMA_LOG_LEVEL=info npm run dev
Consult documentation: npm run docs:generate then view /docs/api.md

For additional support, refer to the SELF-HOSTING.md and DOCKER.md files in the repository, or open an issue on the GitHub repository.

How to Deploy & Use prompts.chat