diff --git a/backend/DOPPLER_SETUP.md b/backend/DOPPLER_SETUP.md new file mode 100644 index 0000000..3ae709e --- /dev/null +++ b/backend/DOPPLER_SETUP.md @@ -0,0 +1,294 @@ +# Doppler Setup Guide for WellNuo Backend + +This guide explains how to migrate from `.env` files to Doppler for secrets management. + +## Why Doppler? + +- **Security**: Secrets are encrypted and never stored in files +- **Audit**: Track who accessed what secrets and when +- **Rotation**: Easy secret rotation without redeployment +- **Environment sync**: Dev, staging, prod secrets in one place + +## Step 1: Create Doppler Account + +1. Go to [doppler.com](https://doppler.com) +2. Sign up with your email or GitHub +3. Create an organization (e.g., "WellNuo" or your company name) + +## Step 2: Create Project + +1. In Doppler dashboard, click **"+ Project"** +2. Name it: `wellnuo-api` +3. Doppler will create default environments: `dev`, `stg`, `prd` + +## Step 3: Add Secrets + +Navigate to your project and add the following secrets for each environment: + +### Required Secrets + +| Secret Name | Description | Example | +|-------------|-------------|---------| +| `DB_HOST` | PostgreSQL host | `91.98.205.156` | +| `DB_PORT` | PostgreSQL port | `5432` | +| `DB_NAME` | Database name | `wellnuo` | +| `DB_USER` | Database username | `wellnuo_user` | +| `DB_PASSWORD` | Database password | `your-secure-password` | +| `JWT_SECRET` | JWT signing key (min 32 chars) | `your-random-secret-key-here` | +| `JWT_EXPIRES_IN` | Token expiration | `7d` | +| `BREVO_API_KEY` | Brevo (Sendinblue) API key | `xkeysib-...` | +| `STRIPE_SECRET_KEY` | Stripe secret key | `sk_live_...` or `sk_test_...` | +| `STRIPE_WEBHOOK_SECRET` | Stripe webhook signing secret | `whsec_...` | +| `ADMIN_API_KEY` | Admin endpoints auth key | `your-admin-key` | + +### Optional Secrets (if used) + +| Secret Name | Description | +|-------------|-------------| +| `LEGACY_API_PASSWORD` | Legacy API auth password | +| `LIVEKIT_API_KEY` | LiveKit API key | +| `LIVEKIT_API_SECRET` | LiveKit API secret | +| `PORT` | Server port (default: 3000) | + +### How to Add Secrets + +1. Go to your project → select environment (e.g., `prd`) +2. Click **"+ Add Secret"** +3. Enter name and value +4. Click **Save** + +**Tip**: Use "Import" to bulk import from existing `.env` file. + +## Step 4: Install Doppler CLI + +### macOS +```bash +brew install dopplerhq/cli/doppler +``` + +### Linux +```bash +curl -Ls https://cli.doppler.com/install.sh | sh +``` + +### Verify installation +```bash +doppler --version +``` + +## Step 5: Authenticate CLI + +```bash +doppler login +``` + +This will open browser for authentication. + +## Step 6: Configure Project on Server + +SSH into your server: + +```bash +ssh root@91.98.205.156 +cd /var/www/wellnuo-api +``` + +Setup Doppler for the project: + +```bash +# Login to Doppler +doppler login + +# Link project to this directory +doppler setup + +# Select project: wellnuo-api +# Select config: prd (production) +``` + +Verify secrets are accessible: + +```bash +doppler secrets +``` + +## Step 7: Update PM2 Configuration + +### Option A: Direct command + +Stop the current process and start with Doppler: + +```bash +pm2 stop wellnuo-api +pm2 delete wellnuo-api + +# Start with Doppler +doppler run -- pm2 start index.js --name wellnuo-api +pm2 save +``` + +### Option B: Using ecosystem.config.js + +Create or update `ecosystem.config.js`: + +```javascript +module.exports = { + apps: [{ + name: 'wellnuo-api', + script: 'index.js', + interpreter: 'doppler', + interpreter_args: 'run --', + env: { + NODE_ENV: 'production' + } + }] +}; +``` + +Then: + +```bash +pm2 start ecosystem.config.js +pm2 save +``` + +### Option C: Shell wrapper script + +Create `start.sh`: + +```bash +#!/bin/bash +doppler run -- node index.js +``` + +Then: + +```bash +chmod +x start.sh +pm2 start ./start.sh --name wellnuo-api +pm2 save +``` + +## Step 8: Verify It Works + +```bash +# Check PM2 status +pm2 status + +# Check logs for startup errors +pm2 logs wellnuo-api --lines 50 + +# Test API endpoint +curl https://wellnuo.smartlaunchhub.com/api/health +``` + +## Step 9: Remove .env File + +**IMPORTANT**: Only after verifying everything works! + +```bash +# Backup first (optional, store securely) +cp .env ~/.env.wellnuo-backup + +# Remove from project +rm .env + +# Commit the removal +git add -A +git commit -m "chore: remove .env file, migrated to Doppler" +``` + +## Troubleshooting + +### "doppler: command not found" in PM2 + +PM2 might not have Doppler in PATH. Use full path: + +```bash +which doppler +# e.g., /usr/local/bin/doppler + +# Use in PM2 +pm2 start "/usr/local/bin/doppler run -- node index.js" --name wellnuo-api +``` + +### Secrets not loading + +```bash +# Verify Doppler is configured +doppler configs + +# Check if secrets are accessible +doppler secrets + +# Run app directly to test +doppler run -- node index.js +``` + +### PM2 restart on server reboot + +Ensure Doppler is authenticated for the startup user: + +```bash +# If running as root +doppler login + +# Save PM2 config +pm2 save +pm2 startup +``` + +## Team Access + +To give team members access to secrets: + +1. Go to Doppler dashboard → Project settings +2. Click **"Access"** +3. Invite team members with appropriate roles: + - **Admin**: Full access + - **Developer**: Read/write dev & stg, read-only prd + - **Viewer**: Read-only + +## Secret Rotation + +To rotate a secret (e.g., JWT_SECRET): + +1. Generate new secret value +2. Update in Doppler dashboard +3. Restart the application: + ```bash + pm2 restart wellnuo-api + ``` + +No code changes or redeployment needed! + +## CI/CD Integration + +For GitHub Actions, add Doppler service token: + +```yaml +- name: Install Doppler CLI + uses: dopplerhq/cli-action@v3 + +- name: Run tests + run: doppler run -- npm test + env: + DOPPLER_TOKEN: ${{ secrets.DOPPLER_TOKEN }} +``` + +--- + +## Quick Reference + +| Command | Description | +|---------|-------------| +| `doppler login` | Authenticate CLI | +| `doppler setup` | Link project to directory | +| `doppler secrets` | List all secrets | +| `doppler run -- ` | Run command with secrets injected | +| `doppler secrets set KEY=value` | Set a secret | +| `doppler secrets get KEY` | Get a secret value | + +--- + +**Note**: This is a manual setup process. Do not run these commands automatically without understanding each step.