add changes
This commit is contained in:
AD2025
348
backend/ENVIRONMENT_GUIDE.md
Normal file
348
backend/ENVIRONMENT_GUIDE.md
Normal file
@@ -0,0 +1,348 @@
|
||||
# Environment Configuration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide explains all environment variables used in the Interview Quiz Backend application and how to configure them properly.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. **Copy the example file:**
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
2. **Generate a secure JWT secret:**
|
||||
```bash
|
||||
npm run generate:jwt
|
||||
```
|
||||
|
||||
3. **Update database credentials in `.env`:**
|
||||
```env
|
||||
DB_USER=root
|
||||
DB_PASSWORD=your_mysql_password
|
||||
```
|
||||
|
||||
4. **Validate your configuration:**
|
||||
```bash
|
||||
npm run validate:env
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
### Server Configuration
|
||||
|
||||
#### `NODE_ENV`
|
||||
- **Type:** String
|
||||
- **Required:** Yes
|
||||
- **Default:** `development`
|
||||
- **Values:** `development`, `test`, `production`
|
||||
- **Description:** Application environment mode
|
||||
|
||||
#### `PORT`
|
||||
- **Type:** Number
|
||||
- **Required:** Yes
|
||||
- **Default:** `3000`
|
||||
- **Range:** 1000-65535
|
||||
- **Description:** Port number for the server
|
||||
|
||||
#### `API_PREFIX`
|
||||
- **Type:** String
|
||||
- **Required:** Yes
|
||||
- **Default:** `/api`
|
||||
- **Description:** API route prefix
|
||||
|
||||
---
|
||||
|
||||
### Database Configuration
|
||||
|
||||
#### `DB_HOST`
|
||||
- **Type:** String
|
||||
- **Required:** Yes
|
||||
- **Default:** `localhost`
|
||||
- **Description:** MySQL server hostname
|
||||
|
||||
#### `DB_PORT`
|
||||
- **Type:** Number
|
||||
- **Required:** Yes
|
||||
- **Default:** `3306`
|
||||
- **Description:** MySQL server port
|
||||
|
||||
#### `DB_NAME`
|
||||
- **Type:** String
|
||||
- **Required:** Yes
|
||||
- **Default:** `interview_quiz_db`
|
||||
- **Description:** Database name
|
||||
|
||||
#### `DB_USER`
|
||||
- **Type:** String
|
||||
- **Required:** Yes
|
||||
- **Default:** `root`
|
||||
- **Description:** Database username
|
||||
|
||||
#### `DB_PASSWORD`
|
||||
- **Type:** String
|
||||
- **Required:** Yes (in production)
|
||||
- **Default:** Empty string
|
||||
- **Description:** Database password
|
||||
- **Security:** Never commit this to version control!
|
||||
|
||||
#### `DB_DIALECT`
|
||||
- **Type:** String
|
||||
- **Required:** Yes
|
||||
- **Default:** `mysql`
|
||||
- **Values:** `mysql`, `postgres`, `sqlite`, `mssql`
|
||||
- **Description:** Database type
|
||||
|
||||
---
|
||||
|
||||
### Database Connection Pool
|
||||
|
||||
#### `DB_POOL_MAX`
|
||||
- **Type:** Number
|
||||
- **Required:** No
|
||||
- **Default:** `10`
|
||||
- **Description:** Maximum number of connections in pool
|
||||
|
||||
#### `DB_POOL_MIN`
|
||||
- **Type:** Number
|
||||
- **Required:** No
|
||||
- **Default:** `0`
|
||||
- **Description:** Minimum number of connections in pool
|
||||
|
||||
#### `DB_POOL_ACQUIRE`
|
||||
- **Type:** Number
|
||||
- **Required:** No
|
||||
- **Default:** `30000` (30 seconds)
|
||||
- **Description:** Max time (ms) to get connection before error
|
||||
|
||||
#### `DB_POOL_IDLE`
|
||||
- **Type:** Number
|
||||
- **Required:** No
|
||||
- **Default:** `10000` (10 seconds)
|
||||
- **Description:** Max idle time (ms) before releasing connection
|
||||
|
||||
---
|
||||
|
||||
### JWT Authentication
|
||||
|
||||
#### `JWT_SECRET`
|
||||
- **Type:** String
|
||||
- **Required:** Yes
|
||||
- **Min Length:** 32 characters (64+ recommended)
|
||||
- **Description:** Secret key for signing JWT tokens
|
||||
- **Security:**
|
||||
- Generate with: `npm run generate:jwt`
|
||||
- Must be different for each environment
|
||||
- Rotate regularly in production
|
||||
- Never commit to version control!
|
||||
|
||||
#### `JWT_EXPIRE`
|
||||
- **Type:** String
|
||||
- **Required:** Yes
|
||||
- **Default:** `24h`
|
||||
- **Format:** Time string (e.g., `24h`, `7d`, `1m`)
|
||||
- **Description:** JWT token expiration time
|
||||
|
||||
---
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
#### `RATE_LIMIT_WINDOW_MS`
|
||||
- **Type:** Number
|
||||
- **Required:** No
|
||||
- **Default:** `900000` (15 minutes)
|
||||
- **Description:** Time window for rate limiting (ms)
|
||||
|
||||
#### `RATE_LIMIT_MAX_REQUESTS`
|
||||
- **Type:** Number
|
||||
- **Required:** No
|
||||
- **Default:** `100`
|
||||
- **Description:** Max requests per window per IP
|
||||
|
||||
---
|
||||
|
||||
### CORS Configuration
|
||||
|
||||
#### `CORS_ORIGIN`
|
||||
- **Type:** String
|
||||
- **Required:** Yes
|
||||
- **Default:** `http://localhost:4200`
|
||||
- **Description:** Allowed CORS origin (frontend URL)
|
||||
- **Examples:**
|
||||
- Development: `http://localhost:4200`
|
||||
- Production: `https://yourapp.com`
|
||||
|
||||
---
|
||||
|
||||
### Guest User Configuration
|
||||
|
||||
#### `GUEST_SESSION_EXPIRE_HOURS`
|
||||
- **Type:** Number
|
||||
- **Required:** No
|
||||
- **Default:** `24`
|
||||
- **Description:** Guest session expiry time in hours
|
||||
|
||||
#### `GUEST_MAX_QUIZZES`
|
||||
- **Type:** Number
|
||||
- **Required:** No
|
||||
- **Default:** `3`
|
||||
- **Description:** Maximum quizzes a guest can take
|
||||
|
||||
---
|
||||
|
||||
### Logging
|
||||
|
||||
#### `LOG_LEVEL`
|
||||
- **Type:** String
|
||||
- **Required:** No
|
||||
- **Default:** `info`
|
||||
- **Values:** `error`, `warn`, `info`, `debug`
|
||||
- **Description:** Logging verbosity level
|
||||
|
||||
---
|
||||
|
||||
## Environment-Specific Configurations
|
||||
|
||||
### Development
|
||||
|
||||
```env
|
||||
NODE_ENV=development
|
||||
PORT=3000
|
||||
DB_HOST=localhost
|
||||
DB_PASSWORD=your_dev_password
|
||||
JWT_SECRET=dev_jwt_secret_generate_with_npm_run_generate_jwt
|
||||
CORS_ORIGIN=http://localhost:4200
|
||||
LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
### Production
|
||||
|
||||
```env
|
||||
NODE_ENV=production
|
||||
PORT=3000
|
||||
DB_HOST=your_production_host
|
||||
DB_PASSWORD=strong_production_password
|
||||
JWT_SECRET=production_jwt_secret_must_be_different_from_dev
|
||||
CORS_ORIGIN=https://yourapp.com
|
||||
LOG_LEVEL=warn
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```env
|
||||
NODE_ENV=test
|
||||
PORT=3001
|
||||
DB_NAME=interview_quiz_db_test
|
||||
DB_PASSWORD=test_password
|
||||
JWT_SECRET=test_jwt_secret
|
||||
LOG_LEVEL=error
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
The application automatically validates all environment variables on startup.
|
||||
|
||||
### Manual Validation
|
||||
|
||||
Run validation anytime:
|
||||
```bash
|
||||
npm run validate:env
|
||||
```
|
||||
|
||||
### Validation Checks
|
||||
|
||||
- ✅ All required variables are set
|
||||
- ✅ Values are in correct format (string, number)
|
||||
- ✅ Numbers are within valid ranges
|
||||
- ✅ Enums match allowed values
|
||||
- ✅ Minimum length requirements met
|
||||
- ⚠️ Warnings for weak configurations
|
||||
|
||||
---
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### 1. JWT Secret
|
||||
- Generate strong, random secrets: `npm run generate:jwt`
|
||||
- Use different secrets for each environment
|
||||
- Store securely (never in code)
|
||||
- Rotate periodically
|
||||
|
||||
### 2. Database Password
|
||||
- Use strong, unique passwords
|
||||
- Never commit to version control
|
||||
- Use environment-specific passwords
|
||||
- Restrict database user permissions
|
||||
|
||||
### 3. CORS Origin
|
||||
- Set to exact frontend URL
|
||||
- Never use `*` in production
|
||||
- Use HTTPS in production
|
||||
|
||||
### 4. Rate Limiting
|
||||
- Adjust based on expected traffic
|
||||
- Lower limits for auth endpoints
|
||||
- Monitor for abuse patterns
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Validation Fails
|
||||
|
||||
Check the error messages and fix invalid values:
|
||||
```bash
|
||||
npm run validate:env
|
||||
```
|
||||
|
||||
### Database Connection Fails
|
||||
|
||||
1. Verify MySQL is running
|
||||
2. Check credentials in `.env`
|
||||
3. Test connection: `npm run test:db`
|
||||
4. Ensure database exists
|
||||
|
||||
### JWT Errors
|
||||
|
||||
1. Verify JWT_SECRET is set
|
||||
2. Ensure it's at least 32 characters
|
||||
3. Regenerate if needed: `npm run generate:jwt`
|
||||
|
||||
---
|
||||
|
||||
## Configuration Module
|
||||
|
||||
Access configuration in code:
|
||||
|
||||
```javascript
|
||||
const config = require('./config/config');
|
||||
|
||||
// Server config
|
||||
console.log(config.server.port);
|
||||
console.log(config.server.nodeEnv);
|
||||
|
||||
// Database config
|
||||
console.log(config.database.host);
|
||||
console.log(config.database.name);
|
||||
|
||||
// JWT config
|
||||
console.log(config.jwt.secret);
|
||||
console.log(config.jwt.expire);
|
||||
|
||||
// Guest config
|
||||
console.log(config.guest.maxQuizzes);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Database Setup](./DATABASE_REFERENCE.md)
|
||||
- [Backend README](./README.md)
|
||||
- [Task List](../BACKEND_TASKS.md)
|
||||
|
||||
---
|
||||
|
||||
**Remember:** Never commit `.env` files to version control! Only commit `.env.example` with placeholder values.
|
||||
Reference in New Issue
Block a user