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

./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:

# 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

./check-solaria-logs.sh

What it shows:

• Container status
• Backend logs (last 50 lines)
• MongoDB logs

3. Test API Endpoints

./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:6500

Public Endpoints (No Auth)

Health Check

curl http://solaria:6500/health

Register

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

Login

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

Set Recovery Phrase

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

Recover Password

curl -X POST http://solaria:6500/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

curl http://solaria:6500/api/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Update Profile

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

Get Settings

curl http://solaria:6500/api/users/me/settings \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Update Settings

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

Change Password

curl -X POST http://solaria:6500/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

curl -X DELETE http://solaria:6500/api/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "confirmation": "DELETE_ACCOUNT"
  }'

Create Share

curl -X POST http://solaria:6500/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

curl http://solaria:6500/api/shares \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Update Share

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

Delete Share

curl -X DELETE http://solaria:6500/api/shares/SHARE_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Check Permission

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

Get Sessions (NEW)

curl http://solaria:6500/api/sessions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Revoke Session (NEW)

curl -X DELETE http://solaria:6500/api/sessions/SESSION_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Revoke All Sessions (NEW)

curl -X DELETE http://solaria:6500/api/sessions/all \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Troubleshooting

Container Won't Start

# 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

# 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

# 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

# Test SSH connection
ssh alvaro@solaria

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

Environment Variables

Create a .env file in backend/ directory:

JWT_SECRET=your-super-secret-jwt-key-min-32-chars
MONGODB_URI=mongodb://mongodb:27017
MONGODB_DATABASE=normogen
RUST_LOG=info
NORMOGEN_PORT=6500
NORMOGEN_HOST=0.0.0.0
APP_ENVIRONMENT=production

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

# 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