Docs: Update README with current status and add config/quickstart guides
Changes: - Updated README.md with current Phase 2.3 completion status - Added detailed development progress section - Added backend API endpoints documentation - Added environment configuration guide - Added local development and Docker quick start - Added deployment instructions New Documentation: - thoughts/CONFIG.md - Comprehensive configuration guide - thoughts/QUICKSTART.md - 5-minute quick start guide All configuration files are now documented and up-to-date.
This commit is contained in:
goose
parent
4e58fb832e
commit
1c9c092dfa
3 changed files with 737 additions and 102 deletions
280
thoughts/CONFIG.md
Normal file
280
thoughts/CONFIG.md
Normal file
|
|
@ -0,0 +1,280 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue