self_hosting.md

🚀 Self-Hosting & Deployment Guide

This document provides setup instructions for running CommitPulse locally, configuring database tracking, and deploying to production.

---

🚀 Self-Hosting in 4 Steps

# 1. Clone the repository
git clone https://github.com/JhaSourav07/commitpulse.git && cd commitpulse

# 2. Install dependencies
npm install

# 3. Create your environment file
cat > .env.local << 'EOF'
GITHUB_TOKEN=your_github_pat_here

# GITHUB_PAT is also accepted as an alias for GITHUB_TOKEN
# Optional — enables user tracking (see below)
# MONGODB_URI=mongodb+srv://...
EOF

# 4. Start the development server
npm run dev

📌 Token Scope: Your GitHub Personal Access Token needs the read:user scope only. No write permissions required.

Then visit: http://localhost:3000/api/streak?user=YOUR_USERNAME

---

🗄️ Optional: MongoDB User Tracking

CommitPulse records the GitHub username of everyone who generates a monolith from the landing page into a MongoDB collection. This is entirely optional for local development — the app works perfectly without it.

If MONGODB_URI is not set, the /api/track-user endpoint will log a warning and skip the database write gracefully:

WARN: MONGODB_URI is not set. Bypassing user tracking for local development.

To enable tracking locally, add your connection string to .env.local:

MONGODB_URI=mongodb+srv://<user>:<password>@cluster.mongodb.net/commitpulse

For production (Vercel), add MONGODB_URI to your project's Environment Variables settings.

---

🌐 Deploy Your Own

Set the GITHUB_TOKEN environment variable in your Vercel project settings, and you're live.

Note: Both GITHUB_TOKEN and GITHUB_PAT are accepted. GITHUB_TOKEN is the canonical name used throughout the codebase; GITHUB_PAT works as an alias for backwards compatibility.