initial commit

docs/user-guide/admin-panel/user-management.md

@@ -0,0 +1,213 @@
+# User Management
+
+Learn how to manage admin users in your FastAPI boilerplate's admin panel. The boilerplate automatically creates admin users from environment variables and provides a separate authentication system (powered by [CRUDAdmin](https://github.com/benavlabs/crudadmin)) from your application users.
+
+> **CRUDAdmin Authentication**: For advanced authentication features and session management, see the [CRUDAdmin documentation](https://benavlabs.github.io/crudadmin/).
+
+## Initial Admin Setup
+
+### Configure Admin Credentials
+
+Set your admin credentials in your `.env` file:
+
+```bash
+# Required admin credentials
+ADMIN_USERNAME="admin"
+ADMIN_PASSWORD="SecurePassword123!"
+
+# Optional details
+ADMIN_NAME="Administrator"
+ADMIN_EMAIL="admin@yourcompany.com"
+```
+
+### Access the Admin Panel
+
+Start your application and access the admin panel:
+
+```bash
+# Start application
+uv run fastapi dev
+
+# Visit: http://localhost:8000/admin
+# Login with your ADMIN_USERNAME and ADMIN_PASSWORD
+```
+
+The boilerplate automatically creates the initial admin user from your environment variables when the application starts.
+
+## Managing Admin Users
+
+### Creating Additional Admin Users
+
+Once logged in, you can create more admin users through the admin interface:
+
+1. Navigate to the admin users section in the admin panel
+2. Click "Create" or "Add New"
+3. Fill in the required fields:
+   - Username (must be unique)
+   - Password (will be hashed automatically)
+   - Email (optional)
+
+### Admin User Requirements
+
+- **Username**: 3-50 characters, letters/numbers/underscores/hyphens
+- **Password**: Minimum 8 characters with mixed case, numbers, and symbols
+- **Email**: Valid email format (optional)
+
+### Updating and Removing Users
+
+- **Update**: Find the user in the admin panel and click "Edit"
+- **Remove**: Click "Delete" (ensure you have alternative admin access first)
+
+## Security Configuration
+
+### Environment-Specific Settings
+
+Configure different security levels for each environment:
+
+```bash
+# Development
+ADMIN_USERNAME="dev-admin"
+ADMIN_PASSWORD="DevPass123!"
+ENVIRONMENT="local"
+
+# Production
+ADMIN_USERNAME="prod-admin"
+ADMIN_PASSWORD="VerySecurePassword123!"
+ENVIRONMENT="production"
+CRUD_ADMIN_TRACK_EVENTS=true
+CRUD_ADMIN_TRACK_SESSIONS=true
+SESSION_SECURE_COOKIES=true
+```
+
+### Session Management
+
+Control admin sessions with these settings:
+
+```bash
+# Session limits and timeouts
+CRUD_ADMIN_MAX_SESSIONS=10          # Max concurrent sessions per user
+CRUD_ADMIN_SESSION_TIMEOUT=1440     # Timeout in minutes (24 hours)
+SESSION_SECURE_COOKIES=true         # HTTPS-only cookies
+```
+
+### Enable Tracking
+
+Monitor admin activity by enabling event tracking:
+
+```bash
+# Track admin actions and sessions
+CRUD_ADMIN_TRACK_EVENTS=true        # Log all admin actions  
+CRUD_ADMIN_TRACK_SESSIONS=true      # Track session lifecycle
+```
+
+## Production Deployment
+
+### Secure Credential Management
+
+For production, use Docker secrets or Kubernetes secrets instead of plain text:
+
+```yaml
+# docker-compose.yml
+services:
+  web:
+    secrets:
+      - admin_username
+      - admin_password
+    environment:
+      - ADMIN_USERNAME_FILE=/run/secrets/admin_username
+      - ADMIN_PASSWORD_FILE=/run/secrets/admin_password
+
+secrets:
+  admin_username:
+    file: ./secrets/admin_username.txt
+  admin_password:
+    file: ./secrets/admin_password.txt
+```
+
+### Production Security Settings
+
+```bash
+# Production .env
+ENVIRONMENT="production"
+ADMIN_USERNAME="prod-admin"
+ADMIN_PASSWORD="UltraSecurePassword123!"
+
+# Enhanced security
+CRUD_ADMIN_REDIS_ENABLED=true
+CRUD_ADMIN_REDIS_HOST="redis.internal.company.com"
+CRUD_ADMIN_REDIS_PASSWORD="secure-redis-password"
+CRUD_ADMIN_REDIS_SSL=true
+
+# Monitoring
+CRUD_ADMIN_TRACK_EVENTS=true
+CRUD_ADMIN_TRACK_SESSIONS=true
+SESSION_SECURE_COOKIES=true
+CRUD_ADMIN_MAX_SESSIONS=5
+CRUD_ADMIN_SESSION_TIMEOUT=480      # 8 hours
+```
+
+## Application User Management
+
+### Admin vs Application Users
+
+Your boilerplate maintains two separate user systems:
+
+- **Admin Users**: Access the admin panel (stored by CRUDAdmin)
+- **Application Users**: Use your application (stored in your User model)
+
+### Managing Application Users
+
+Through the admin panel, you can manage your application's users:
+
+1. Navigate to "Users" section (your application users)
+2. View, create, update user profiles
+3. Manage user tiers and subscriptions
+4. View user-generated content (posts)
+
+The User model is already registered with password hashing and proper permissions.
+
+## Emergency Recovery
+
+### Lost Admin Password
+
+If you lose admin access, update your environment variables:
+
+```bash
+# Update .env file
+ADMIN_USERNAME="emergency-admin"
+ADMIN_PASSWORD="EmergencyPassword123!"
+
+# Restart application
+uv run fastapi dev
+```
+
+### Database Recovery (Advanced)
+
+For direct database password reset:
+
+```python
+# Generate bcrypt hash
+import bcrypt
+password = "NewPassword123!"
+hashed = bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt())
+print(hashed.decode('utf-8'))
+```
+
+```sql
+-- Update in database
+UPDATE admin_users 
+SET password_hash = '<bcrypt-hash>' 
+WHERE username = 'admin';
+```
+
+## What's Next
+
+Your admin user management is now configured with:
+
+- Automatic admin user creation from environment variables
+- Secure authentication separate from application users
+- Environment-specific security settings
+- Production-ready credential management
+- Emergency recovery procedures
+
+You can now securely manage both admin users and your application users through the admin panel.