161 lines
4.2 KiB
Markdown
161 lines
4.2 KiB
Markdown
# 🛠️ Development Setup Guide
|
|
|
|
## 🔒 Environment Files Security
|
|
|
|
### ✅ Safe for Development
|
|
|
|
Your `.env` files are **automatically excluded** from git commits via `.gitignore`. This means you can:
|
|
|
|
- ✅ Keep real credentials in `.env` files locally
|
|
- ✅ Develop with actual API connections
|
|
- ✅ Test with real data safely
|
|
- ✅ Never worry about committing secrets
|
|
|
|
### 📁 Environment File Structure
|
|
|
|
```
|
|
apps/bff/
|
|
├── .env # Your actual credentials (git ignored)
|
|
├── .env.example # Template with placeholder values (committed)
|
|
├── .env.production # Production template (committed)
|
|
└── .env.production.example # Production example (committed)
|
|
|
|
apps/portal/
|
|
├── .env.local # Your local overrides (git ignored)
|
|
├── .env.example # Template (committed)
|
|
└── .env.production # Production template (committed)
|
|
```
|
|
|
|
## 🚀 Quick Setup
|
|
|
|
### 1. Backend Environment Setup
|
|
|
|
```bash
|
|
cd apps/bff
|
|
cp .env.example .env
|
|
nano .env # Update with your actual values
|
|
```
|
|
|
|
### 2. Frontend Environment Setup
|
|
|
|
```bash
|
|
cd apps/portal
|
|
cp .env.example .env.local
|
|
nano .env.local # Update if needed (usually defaults are fine)
|
|
```
|
|
|
|
### 3. Salesforce Private Key
|
|
|
|
```bash
|
|
# Create secrets directory if not exists
|
|
mkdir -p secrets
|
|
|
|
# Add your Salesforce private key
|
|
nano secrets/sf-private.key
|
|
chmod 600 secrets/sf-private.key
|
|
```
|
|
|
|
## 🔧 Configuration Checklist
|
|
|
|
### Backend (.env)
|
|
- [ ] `DATABASE_URL` - Your PostgreSQL connection
|
|
- [ ] `REDIS_URL` - Your Redis connection
|
|
- [ ] `WHMCS_BASE_URL` - Your WHMCS installation URL
|
|
- [ ] `WHMCS_API_IDENTIFIER` - Your WHMCS API identifier
|
|
- [ ] `WHMCS_API_SECRET` - Your WHMCS API secret
|
|
- [ ] `SF_LOGIN_URL` - Salesforce login URL
|
|
- [ ] `SF_CLIENT_ID` - Salesforce Connected App consumer key
|
|
- [ ] `SF_USERNAME` - Salesforce integration user email
|
|
- [ ] `JWT_SECRET` - Generate with: `openssl rand -hex 64`
|
|
|
|
### Frontend (.env.local)
|
|
- [ ] `NEXT_PUBLIC_API_BASE` - Usually `http://localhost:4000` for development
|
|
|
|
## 🎯 Development Commands
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pnpm install
|
|
|
|
# Start development servers
|
|
pnpm dev
|
|
|
|
# Type checking
|
|
pnpm type-check
|
|
|
|
# Build for production test
|
|
pnpm build
|
|
```
|
|
|
|
## 🔒 Security Best Practices
|
|
|
|
### ✅ DO:
|
|
- Keep `.env` files for local development
|
|
- Use strong, unique passwords
|
|
- Generate secure JWT secrets
|
|
- Set proper file permissions (`chmod 600`) for private keys
|
|
- Test with real but non-production data when possible
|
|
|
|
### ❌ DON'T:
|
|
- Ever commit `.env` files to git
|
|
- Share credentials in chat/email
|
|
- Use production secrets in development
|
|
- Hardcode secrets in source code
|
|
- Use weak or default passwords
|
|
|
|
## 🚨 If You Accidentally Commit Secrets
|
|
|
|
1. **Immediately rotate** all exposed credentials
|
|
2. **Remove from git history**:
|
|
```bash
|
|
git filter-branch --force --index-filter \
|
|
"git rm --cached --ignore-unmatch path/to/secret/file" \
|
|
--prune-empty --tag-name-filter cat -- --all
|
|
```
|
|
3. **Force push** to overwrite history: `git push --force`
|
|
4. **Update** all team members
|
|
|
|
## 🌍 Environment-Specific Configuration
|
|
|
|
### Development
|
|
- Uses `.env` files
|
|
- Connects to local/development services
|
|
- Verbose logging enabled
|
|
- CORS permissive for localhost
|
|
|
|
### Production
|
|
- Uses environment variables from deployment platform
|
|
- Connects to production services
|
|
- Structured logging
|
|
- Strict CORS and security headers
|
|
|
|
## 🛠️ Troubleshooting
|
|
|
|
### "Environment variable not found"
|
|
1. Check `.env` file exists and has the variable
|
|
2. Restart development server
|
|
3. Check variable name spelling
|
|
|
|
### "Database connection failed"
|
|
1. Verify PostgreSQL is running
|
|
2. Check `DATABASE_URL` format
|
|
3. Test connection manually
|
|
|
|
### "Salesforce authentication failed"
|
|
1. Verify private key file exists and permissions
|
|
2. Check Connected App configuration
|
|
3. Verify user permissions in Salesforce
|
|
|
|
### "WHMCS API errors"
|
|
1. Verify API credentials are correct
|
|
2. Check IP whitelist in WHMCS
|
|
3. Test API endpoints manually with curl
|
|
|
|
## 📖 Additional Resources
|
|
|
|
- [Environment Configuration Guide](./ENVIRONMENT_CONFIGURATION.md)
|
|
- [Quick Start Deployment Guide](./QUICK_START.md)
|
|
- [Plesk Deployment Guide](./PLESK_DEPLOYMENT.md)
|
|
- [Salesforce Setup Guide](./SALESFORCE_SETUP.md)
|
|
- [WHMCS Integration Guide](./WHMCS_INTEGRATION.md)
|