349 lines
6.8 KiB
Markdown
349 lines
6.8 KiB
Markdown
# 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.
|