normogen/thoughts/QUICKSTART.md

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

# 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)

docker run -d \
  --name normogen-mongo \
  -p 27017:27017 \
  -e MONGO_INITDB_DATABASE=normogen \
  mongo:latest

Option B: Using System MongoDB

# Start MongoDB service
sudo systemctl start mongod  # Linux
brew services start mongodb  # macOS

Step 3: Configure Environment

Edit backend/.env:

# 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

# 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

curl http://localhost:8000/health

Expected response:

{
  "status": "ok",
  "database": "connected"
}

Register a User

curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "SecurePassword123!"
  }'

Expected response:

{
  "message": "User registered successfully",
  "user_id": "...",
  "email": "test@example.com"
}

Login

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "SecurePassword123!"
  }'

Expected response:

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 900
}

Access Protected Endpoint

# Replace YOUR_ACCESS_TOKEN with the token from login
curl http://localhost:8000/api/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Expected response:

{
  "user_id": "...",
  "email": "test@example.com",
  "family_id": null,
  "token_version": 0
}

Docker Quick Start

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 for detailed configuration
• Read STATUS.md for development progress
• Run ./thoughts/test_auth.sh for comprehensive API testing
• Check API documentation in verification-report-phase-2.3.md

Troubleshooting

Port 8000 already in use

# Find and kill the process
lsof -ti:8000 | xargs kill -9

MongoDB connection failed

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

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

Compilation errors

# 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

# 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