# Configuration Guide

This document explains all configuration files and environment variables for the Normogen project.

## Backend Configuration

### Environment Files

#### 1. backend/.env.example (Primary Configuration Template)

This is the main environment configuration template for the backend service.

```bash
# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017
DATABASE_NAME=normogen

# JWT Configuration
JWT_SECRET=your-secret-key-here-change-in-production
JWT_ACCESS_TOKEN_EXPIRY_MINUTES=15
JWT_REFRESH_TOKEN_EXPIRY_DAYS=30

# Server Configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
```

**How to use:**
```bash
cd backend
cp .env.example .env
# Edit .env with your values
```

#### 2. backend/defaults.env

This file contains default values for development. It's sourced by docker-compose files.

```bash
MONGODB_URI=mongodb://localhost:27017
DATABASE_NAME=normogen
JWT_SECRET=change-this-secret-in-production
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
```

#### 3. thoughts/env.example

This is a reference copy in the thoughts directory for documentation purposes.

## Environment Variables

### Required Variables

| Variable | Description | Example | Default |
|----------|-------------|---------|---------|
| `MONGODB_URI` | MongoDB connection string | `mongodb://localhost:27017` | - |
| `DATABASE_NAME` | MongoDB database name | `normogen` | - |
| `JWT_SECRET` | Secret key for JWT signing | Minimum 32 characters | - |

### Optional Variables

| Variable | Description | Example | Default |
|----------|-------------|---------|---------|
| `SERVER_HOST` | Server bind address | `0.0.0.0` | `127.0.0.1` |
| `SERVER_PORT` | Server port | `8000` | `8000` |
| `JWT_ACCESS_TOKEN_EXPIRY_MINUTES` | Access token lifetime | `15` | `15` |
| `JWT_REFRESH_TOKEN_EXPIRY_DAYS` | Refresh token lifetime | `30` | `30` |

## Docker Configuration

### docker-compose.yml (Production)

Standard production deployment with MongoDB.

```bash
cd backend
docker compose up -d
```

**Services:**
- `backend` - Axum server on port 6000 (host)
- `mongodb` - MongoDB on port 27017

**Resource Limits:**
- CPU: 1000m (1 core)
- Memory: 1000Mi (1GB)

### docker-compose.dev.yml (Development)

Development mode with hot reload and volume mounts.

```bash
cd backend
docker compose -f docker-compose.dev.yml up -d
```

**Features:**
- Hot reload on code changes
- Source code mounted as volume
- Exposes server on port 8000

## Local Development

### Quick Start

```bash
# Clone repository
git clone <forgejo-url> normogen
cd normogen/backend

# Setup environment
cp .env.example .env
# Edit .env with your configuration

# Install dependencies
cargo build

# Run server
cargo run

# Test
curl http://localhost:8000/health
```

### Testing

```bash
# Unit tests
cargo test

# Integration tests
cargo test --test auth_tests

# Manual testing script
cd ..
./thoughts/test_auth.sh
```

## Configuration Best Practices

### JWT Secret

```bash
# Generate a secure JWT secret (minimum 32 characters)
openssl rand -base64 32

# Or use a passphrase-based secret
echo "your-secure-passphrase-32-chars-minimum" | base64
```

**Security Requirements:**
- Minimum 32 characters
- Use random, high-entropy values
- Never commit to git
- Rotate periodically in production
- Use different secrets for dev/staging/production

### MongoDB Connection

```bash
# Local development
MONGODB_URI=mongodb://localhost:27017

# With authentication
MONGODB_URI=mongodb://username:password@localhost:27017

# Replica set
MONGODB_URI=mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myReplicaSet

# MongoDB Atlas (cloud)
MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/mydb
```

### Server Configuration

```bash
# Local development (localhost only)
SERVER_HOST=127.0.0.1
SERVER_PORT=8000

# Docker/Docker Compose (all interfaces)
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

# Production (behind reverse proxy)
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
```

## Deployment Environments

### Development

```bash
MONGODB_URI=mongodb://localhost:27017
DATABASE_NAME=normogen_dev
JWT_SECRET=dev-secret-key-32-chars-minimum
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
```

### Staging

```bash
MONGODB_URI=mongodb://staging-mongo.internal:27017
DATABASE_NAME=normogen_staging
JWT_SECRET=<use-vault-or-secret-manager>
SERVER_HOST=0.0.0.0
SERVER_PORT=8000
```

### Production

```bash
MONGODB_URI=mongodb+srv://<username>:<password>@prod-cluster.mongodb.net/normogen
DATABASE_NAME=normogen
JWT_SECRET=<use-vault-or-secret-manager>
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
```

## Troubleshooting

### MongoDB Connection Issues

```bash
# Check if MongoDB is running
docker ps | grep mongo
# or
systemctl status mongod

# Test connection
mongosh "mongodb://localhost:27017"
```

### JWT Errors

```bash
# Verify JWT_SECRET is set
echo $JWT_SECRET | wc -c  # Should be >= 32

# Check for special characters
# Some shells may require quotes
export JWT_SECRET="your-secret-with-special-chars-!@#$%"
```

### Port Already in Use

```bash
# Check what's using port 8000
lsof -i :8000
# or
netstat -tulpn | grep 8000

# Kill the process
kill -9 <PID>
```

## Security Checklist

Before deploying to production:

- [ ] Change `JWT_SECRET` to a strong, randomly generated value
- [ ] Enable MongoDB authentication
- [ ] Use TLS/SSL for MongoDB connections
- [ ] Set up firewall rules
- [ ] Configure reverse proxy (nginx/caddy)
- [ ] Enable HTTPS
- [ ] Set up log aggregation
- [ ] Configure monitoring and alerts
- [ ] Implement rate limiting
- [ ] Regular security updates

## Additional Resources

- [README.md](../README.md) - Project overview
- [STATUS.md](./STATUS.md) - Development progress
- [encryption.md](../encryption.md) - Encryption implementation guide
- [introduction.md](../introduction.md) - Project vision