normogen/docs/deployment/DEPLOYMENT_GUIDE.md

# Normogen Deployment & Testing Guide

## Overview
This guide covers deploying the Normogen backend to Solaria and testing all API endpoints.

## Prerequisites

### Local Setup
- Git repository cloned
- SSH access to Solaria configured
- jq installed for JSON parsing
- Scripts made executable

### Server Requirements (Solaria)
- Docker and Docker Compose installed
- Git access to gitea.solivarez.com.ar
- Ports 8000 available

## Deployment Scripts

### 1. Deploy to Solaria
```bash
./deploy-to-solaria.sh
```

**What it does:**
1. Pushes latest changes to git
2. Connects to Solaria via SSH
3. Clones/updates the repository
4. Stops existing containers
5. Builds and starts new containers
6. Shows container status and logs

**Manual Deployment Steps:**
```bash
# Push to git
git push origin main

# SSH to Solaria
ssh alvaro@solaria

# Navigate to project
cd ~/normogen/backend

# Stop existing containers
docker-compose down

# Build and start
docker-compose up -d --build

# Check status
docker-compose ps

# View logs
docker-compose logs -f backend
```

### 2. Check Server Logs
```bash
./check-solaria-logs.sh
```

**What it shows:**
- Container status
- Backend logs (last 50 lines)
- MongoDB logs

### 3. Test API Endpoints
```bash
./test-api-endpoints.sh
```

**What it tests:**
1. Health Check
2. Authentication (Register, Login)
3. User Management (Get/Update Profile, Settings)
4. Password Recovery (Set phrase, Recover, Change password)
5. Share Management (Create, List shares)
6. Permissions (Check permission)
7. Session Management (Get sessions)

## API Endpoints Reference

### Base URL
```
http://solaria:8000
```

### Public Endpoints (No Auth)

#### Health Check
```bash
curl http://solaria:8000/health
```

#### Register
```bash
curl -X POST http://solaria:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "Password123!",
    "full_name": "Test User"
  }'
```

#### Login
```bash
curl -X POST http://solaria:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "Password123!"
  }'
```

#### Set Recovery Phrase
```bash
curl -X POST http://solaria:8000/api/auth/set-recovery-phrase \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "recovery_phrase": "my-secret-phrase"
  }'
```

#### Recover Password
```bash
curl -X POST http://solaria:8000/api/auth/recover-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "recovery_phrase": "my-secret-phrase",
    "new_password": "NewPassword456!"
  }'
```

### Protected Endpoints (Require Bearer Token)

#### Get Profile
```bash
curl http://solaria:8000/api/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### Update Profile
```bash
curl -X PUT http://solaria:8000/api/users/me \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "full_name": "Updated Name"
  }'
```

#### Get Settings
```bash
curl http://solaria:8000/api/users/me/settings \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### Update Settings
```bash
curl -X PUT http://solaria:8000/api/users/me/settings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "theme": "dark"
  }'
```

#### Change Password
```bash
curl -X POST http://solaria:8000/api/users/me/change-password \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "old_password": "OldPassword123!",
    "new_password": "NewPassword456!"
  }'
```

#### Delete Account
```bash
curl -X DELETE http://solaria:8000/api/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "confirmation": "DELETE_ACCOUNT"
  }'
```

#### Create Share
```bash
curl -X POST http://solaria:8000/api/shares \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "target_email": "other@example.com",
    "resource_type": "profiles",
    "resource_id": "507f1f77bcf86cd799439011",
    "permissions": ["read"]
  }'
```

#### List Shares
```bash
curl http://solaria:8000/api/shares \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### Update Share
```bash
curl -X PUT http://solaria:8000/api/shares/SHARE_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "permissions": ["read", "write"]
  }'
```

#### Delete Share
```bash
curl -X DELETE http://solaria:8000/api/shares/SHARE_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### Check Permission
```bash
curl -X POST http://solaria:8000/api/permissions/check \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "resource_id": "507f1f77bcf86cd799439011",
    "permission": "read"
  }'
```

#### Get Sessions (NEW)
```bash
curl http://solaria:8000/api/sessions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### Revoke Session (NEW)
```bash
curl -X DELETE http://solaria:8000/api/sessions/SESSION_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

#### Revoke All Sessions (NEW)
```bash
curl -X DELETE http://solaria:8000/api/sessions/all \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Troubleshooting

### Container Won't Start
```bash
# Check logs
docker-compose logs backend

# Check container status
docker-compose ps

# Restart containers
docker-compose restart

# Rebuild from scratch
docker-compose down -v
docker-compose up -d --build
```

### Database Connection Issues
```bash
# Check MongoDB is running
docker-compose ps mongodb

# Check MongoDB logs
docker-compose logs mongodb

# Test MongoDB connection
docker-compose exec backend mongosh mongodb://mongodb:27017
```

### Permission Denied
```bash
# Make sure scripts are executable
chmod +x deploy-to-solaria.sh
chmod +x test-api-endpoints.sh
chmod +x check-solaria-logs.sh
```

### SSH Connection Issues
```bash
# Test SSH connection
ssh alvaro@solaria

# Check SSH config
cat ~/.ssh/config | grep solaria
```

## Environment Variables

Create a `.env` file in `backend/` directory:

```env
JWT_SECRET=your-super-secret-jwt-key-min-32-chars
MONGODB_URI=mongodb://mongodb:27017
MONGODB_DATABASE=normogen
RUST_LOG=info
SERVER_PORT=8000
SERVER_HOST=0.0.0.0
```

## Security Features (Phase 2.6)

### Session Management
- Tracks user sessions across devices
- View active sessions
- Revoke specific or all sessions
- Automatic cleanup of expired sessions

### Audit Logging
- Logs all security-relevant events
- Track login attempts, password changes
- Monitor data access and modifications
- Query logs by user or system-wide

### Account Lockout
- Brute-force protection
- Progressive lockout durations
- Configurable attempt limits
- Automatic reset on successful login

### Security Headers
- X-Content-Type-Options: nosniff
- X-Frame-Options: DENY
- X-XSS-Protection: 1; mode=block
- Strict-Transport-Security
- Content-Security-Policy

## Performance Tips

### Production Deployment
1. Use environment-specific JWT_SECRET
2. Set RUST_LOG=warn for production
3. Enable MongoDB authentication
4. Use Docker volumes for data persistence
5. Set up monitoring and alerting
6. Configure reverse proxy (nginx/caddy)

### Monitoring
```bash
# Check container stats
docker stats

# View real-time logs
docker-compose logs -f backend

# Check resource usage
docker-compose top
```

## Next Steps

1. ✅ Complete Phase 2.6 (Security Hardening)
2. ⏳ Integrate session management into auth flow
3. ⏳ Implement proper rate limiting
4. ⏳ Add comprehensive tests
5. ⏳ Begin Phase 2.7 (Health Data Features)

## Support

For issues or questions:
- Check logs: `./check-solaria-logs.sh`
- Review deployment: `./deploy-to-solaria.sh`
- Test API: `./test-api-endpoints.sh`
- Check PHASE_2.6_COMPLETION.md for implementation details