alvaro/normogen
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Docs: Update README with current status and add config/quickstart guides

Browse source 
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 2026-02-15 09:25:03 -03:00
parent 4e58fb832e
commit 1c9c092dfa
3 changed files with 737 additions and 102 deletions
Download patch file Download diff file Expand all files Collapse all files

280
thoughts/CONFIG.md Normal file
View 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

215
thoughts/QUICKSTART.md Normal file
View file

@ -0,0 +1,215 @@
# Quick Start Guide
Get the Normogen backend running locally in 5 minutes.
## Prerequisites
- Rust 1.70 or later
- MongoDB 4.4 or later
- Git
## Step 1: Clone and Setup
```bash
# Clone repository
git clone <forgejo-url> normogen
cd normogen/backend
# Copy environment template
cp .env.example .env
```
## Step 2: Start MongoDB
### Option A: Using Docker (Recommended)
```bash
docker run -d \
--name normogen-mongo \
-p 27017:27017 \
-e MONGO_INITDB_DATABASE=normogen \
mongo:latest
```
### Option B: Using System MongoDB
```bash
# Start MongoDB service
sudo systemctl start mongod # Linux
brew services start mongodb # macOS
```
## Step 3: Configure Environment
Edit `backend/.env`:
```bash
# MongoDB Configuration
MONGODB_URI=mongodb://localhost:27017
DATABASE_NAME=normogen
# JWT Configuration (change this!)
JWT_SECRET=my-super-secret-jwt-key-32-chars
JWT_ACCESS_TOKEN_EXPIRY_MINUTES=15
JWT_REFRESH_TOKEN_EXPIRY_DAYS=30
# Server Configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=8000
```
## Step 4: Build and Run
```bash
# Install dependencies and build
cargo build
# Run the server
cargo run
```
Server will start on `http://127.0.0.1:8000`
## Step 5: Test
### Health Check
```bash
curl http://localhost:8000/health
```
Expected response:
```json
{
"status": "ok",
"database": "connected"
}
```
### Register a User
```bash
curl -X POST http://localhost:8000/api/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "test@example.com",
"password": "SecurePassword123!"
}'
```
Expected response:
```json
{
"message": "User registered successfully",
"user_id": "...",
"email": "test@example.com"
}
```
### Login
```bash
curl -X POST http://localhost:8000/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "test@example.com",
"password": "SecurePassword123!"
}'
```
Expected response:
```json
{
"access_token": "...",
"refresh_token": "...",
"token_type": "Bearer",
"expires_in": 900
}
```
### Access Protected Endpoint
```bash
# Replace YOUR_ACCESS_TOKEN with the token from login
curl http://localhost:8000/api/users/me \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
Expected response:
```json
{
"user_id": "...",
"email": "test@example.com",
"family_id": null,
"token_version": 0
}
```
## Docker Quick Start
```bash
cd backend
# Start MongoDB and backend with Docker Compose
docker compose up -d
# Check logs
docker compose logs -f backend
# Test
curl http://localhost:6000/health
```
## Next Steps
- Read [CONFIG.md](./CONFIG.md) for detailed configuration
- Read [STATUS.md](./STATUS.md) for development progress
- Run `./thoughts/test_auth.sh` for comprehensive API testing
- Check API documentation in [verification-report-phase-2.3.md](./verification-report-phase-2.3.md)
## Troubleshooting
### Port 8000 already in use
```bash
# Find and kill the process
lsof -ti:8000 | xargs kill -9
```
### MongoDB connection failed
```bash
# Check MongoDB is running
docker ps | grep mongo
# or
systemctl status mongod
# Test connection
mongosh "mongodb://localhost:27017"
```
### Compilation errors
```bash
# Clean and rebuild
cargo clean
cargo build
```
### JWT secret too short
Make sure `JWT_SECRET` in `.env` is at least 32 characters.
## Stopping the Server
```bash
# If running with cargo
Ctrl+C
# If running with Docker Compose
docker compose down
# Stop MongoDB (Docker)
docker stop normogen-mongo
docker rm normogen-mongo
```