docs: add Doppler setup guide for secrets management
Add comprehensive guide for migrating from .env files to Doppler: - Step-by-step instructions for account setup - List of all required secrets - CLI installation for macOS/Linux - PM2 configuration options - Troubleshooting section - Team access and CI/CD integration Note: Manual setup required, not automated. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Sergei
parent
4a4fc5c077
commit
7cb29bd874
294
backend/DOPPLER_SETUP.md
Normal file
294
backend/DOPPLER_SETUP.md
Normal file
@ -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 -- <cmd>` | 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.
|
||||
Loading…
x
Reference in New Issue
Block a user