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:

   cp .env.example .env
   

2. Edit .env and set a secure password:

   DEFAULT_SUPERADMIN_USERNAME=superadmin
   DEFAULT_SUPERADMIN_PASSWORD=your_secure_password_here
   

3. Run the initialization (happens automatically on container startup):

   docker-compose up -d
   

Production

1. Set environment variables in your deployment configuration:

   export DEFAULT_SUPERADMIN_USERNAME=superadmin
   export DEFAULT_SUPERADMIN_PASSWORD=your_very_secure_password
   

2. Deploy with docker-compose:

   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:

# 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.