1c9c092dfa
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.
215 lines
3.4 KiB
Markdown
215 lines
3.4 KiB
Markdown
# 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
|
|
```
|