infoscreen/SUPERADMIN_SETUP.md

# Superadmin User Setup

This document describes the superadmin user initialization system implemented in the infoscreen_2025 project.

## Overview

The system automatically creates a default superadmin user during database initialization if one doesn't already exist. This ensures there's always an initial administrator account available for system setup and configuration.

## Implementation Details

### Files Modified

1. **`server/init_defaults.py`**
   - Updated to create a superadmin user with role `superadmin` (from `UserRole` enum)
   - Password is securely hashed using bcrypt
   - Only creates user if not already present in the database
   - Provides clear feedback about creation status

2. **`.env.example`**
   - Updated with new environment variables
   - Includes documentation for required variables

3. **`docker-compose.yml`** and **`docker-compose.prod.yml`**
   - Added environment variable passthrough for superadmin credentials

4. **`userrole-management.md`**
   - Marked stage 1, step 2 as completed

## Environment Variables

### Required

- **`DEFAULT_SUPERADMIN_PASSWORD`**: The password for the superadmin user
  - **IMPORTANT**: This must be set for the superadmin user to be created
  - Should be a strong, secure password
  - If not set, the script will skip superadmin creation with a warning

### Optional

- **`DEFAULT_SUPERADMIN_USERNAME`**: The username for the superadmin user
  - Default: `superadmin`
  - Can be customized if needed

## Setup Instructions

### Development

1. Copy `.env.example` to `.env`:
   ```bash
   cp .env.example .env
   ```

2. Edit `.env` and set a secure password:
   ```bash
   DEFAULT_SUPERADMIN_USERNAME=superadmin
   DEFAULT_SUPERADMIN_PASSWORD=your_secure_password_here
   ```

3. Run the initialization (happens automatically on container startup):
   ```bash
   docker-compose up -d
   ```

### Production

1. Set environment variables in your deployment configuration:
   ```bash
   export DEFAULT_SUPERADMIN_USERNAME=superadmin
   export DEFAULT_SUPERADMIN_PASSWORD=your_very_secure_password
   ```

2. Deploy with docker-compose:
   ```bash
   docker-compose -f docker-compose.prod.yml up -d
   ```

## Behavior

The `init_defaults.py` script runs automatically during container initialization and:

1. Checks if the username already exists in the database
2. If it exists: Prints an info message and skips creation
3. If it doesn't exist and `DEFAULT_SUPERADMIN_PASSWORD` is set:
   - Hashes the password with bcrypt
   - Creates the user with role `superadmin`
   - Prints a success message
4. If `DEFAULT_SUPERADMIN_PASSWORD` is not set:
   - Prints a warning and skips creation

## Security Considerations

1. **Never commit the `.env` file** to version control
2. Use a strong password (minimum 12 characters, mixed case, numbers, special characters)
3. Change the default password after first login
4. In production, consider using secrets management (Docker secrets, Kubernetes secrets, etc.)
5. Rotate passwords regularly
6. The password is hashed with bcrypt (industry standard) before storage

## Testing

To verify the superadmin user was created:

```bash
# Connect to the database container
docker exec -it infoscreen-db mysql -u root -p

# Check the users table
USE infoscreen_by_taa;
SELECT username, role, is_active FROM users WHERE role = 'superadmin';
```

Expected output:
```
+------------+------------+-----------+
| username   | role       | is_active |
+------------+------------+-----------+
| superadmin | superadmin |         1 |
+------------+------------+-----------+
```

## Troubleshooting

### Superadmin not created

**Symptoms**: No superadmin user in database

**Solutions**:
1. Check if `DEFAULT_SUPERADMIN_PASSWORD` is set in environment
2. Check container logs: `docker logs infoscreen-api`
3. Look for warning message: "⚠️ DEFAULT_SUPERADMIN_PASSWORD nicht gesetzt"

### User already exists message

**Symptoms**: Script says user already exists but you can't log in

**Solutions**:
1. Verify the username is correct
2. Reset the password manually in the database
3. Or delete the user and restart containers to recreate

### Permission denied errors

**Symptoms**: Database connection errors during initialization

**Solutions**:
1. Verify `DB_USER`, `DB_PASSWORD`, and `DB_NAME` environment variables
2. Check database container is healthy: `docker ps`
3. Verify database connectivity: `docker exec infoscreen-api ping -c 1 db`

## Next Steps

After setting up the superadmin user:

1. Implement the `/api/me` endpoint (Stage 1, Step 3)
2. Add authentication/session management
3. Create permission decorators (Stage 1, Step 4)
4. Build user management UI (Stage 2)

See `userrole-management.md` for the complete roadmap.