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:
parent
4e58fb832e
commit
1c9c092dfa
3 changed files with 737 additions and 102 deletions
215
thoughts/QUICKSTART.md
Normal file
215
thoughts/QUICKSTART.md
Normal 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
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue