gridpilot.gg/docs/DEMO_ACCOUNTS.md

Demo Accounts

This document serves as the single source of truth for demo accounts in the GridPilot application.

Overview

Demo accounts are predefined user accounts created during application bootstrap for testing and development purposes. They use a fixed password and are automatically seeded into the system.

Available Demo Accounts

All demo accounts use the same fixed password: Demo1234!

Email	Role	Display Name	Notes
demo.driver@example.com	user	John Driver	Standard user account with primary driver ID
demo.sponsor@example.com	user	Jane Sponsor	Standard user account
demo.owner@example.com	owner	Alice Owner	League owner account with admin privileges
demo.steward@example.com	user	Bob Steward	User account with admin privileges
demo.admin@example.com	admin	Charlie Admin	Administrator account
demo.systemowner@example.com	admin	Diana SystemOwner	Administrator account
demo.superadmin@example.com	admin	Edward SuperAdmin	Administrator account

How Demo Users Are Created

Demo users are created automatically during application startup through the bootstrap process:

1. Bootstrap Module: The BootstrapModule runs on API startup
2. SeedDemoUsers: This class creates/updates demo users with fixed specifications
3. Idempotent: If demo users already exist, they are only updated if force reseed is enabled
4. Environment-aware: Demo users are only created in development and test environments (never in production)

Creation Process

• Users are created with deterministic IDs based on their email addresses
• Passwords are hashed using the password hashing service
• Admin users also get corresponding AdminUser entities with appropriate roles
• Users needing primary driver IDs get them generated based on their email

Environment Variables

GRIDPILOT_API_BOOTSTRAP

• Purpose: Controls whether bootstrap seeding runs on startup
• Default: true (enabled by default)
• Values:
  • true, 1, or any truthy value = enabled
  • false, 0 = disabled
• Usage: Set to false to skip all seeding (including demo users)

GRIDPILOT_API_FORCE_RESEED

• Purpose: Forces reseeding of demo users even if they already exist
• Default: false (disabled)
• Values:
  • true, 1, or any truthy value = enabled
  • false, 0 or unset = disabled
• Usage: Set to true to update existing demo users with new data

GRIDPILOT_API_PERSISTENCE

• Purpose: Controls database persistence type
• Values: postgres or inmemory
• Impact: Demo users work with both persistence types

NODE_ENV

• Purpose: Environment mode
• Impact: Demo users are only seeded in development and test environments, never in production

How to Use Demo Accounts

Login

Use the standard login API endpoint with any demo email and the password Demo1234!:

# Example login request
POST /api/auth/login
{
  "email": "demo.driver@example.com",
  "password": "Demo1234!"
}

Access Demo Accounts

1. Start the application in development or test mode
2. Bootstrap will automatically create/update demo users
3. Use any demo email and password Demo1234! to log in
4. Different accounts have different roles and permissions for testing

Forcing Reseed of Demo Users

To force reseeding of demo users (updates existing users):

Option 1: Environment Variable

GRIDPILOT_API_FORCE_RESEED=true npm run dev

Option 2: Docker Compose

Add to your .env file or docker-compose override:

environment:
  - GRIDPILOT_API_FORCE_RESEED=true

Option 3: Test Environment

Demo users are automatically reseeded in test environments when needed.

Demo User Specifications

Each demo user is defined with these properties:

• email: Fixed email address
• password: Always Demo1234!
• needsAdminUser: Whether to create an AdminUser entity
• needsPrimaryDriverId: Whether to generate a primary driver ID
• roles: Array of roles for admin users
• displayName: Human-readable name

Security Considerations

• Demo accounts should only be used in development and testing
• Never enable demo accounts in production
• The fixed password is acceptable for demo purposes but should never be used for real accounts
• Demo users have predictable emails, making them unsuitable for security testing

Troubleshooting

Demo Users Not Created

1. Check NODE_ENV is not production
2. Verify GRIDPILOT_API_BOOTSTRAP is not set to false
3. Check logs for bootstrap errors
4. Ensure database connection is working (for postgres persistence)

Demo Users Not Updating

1. Set GRIDPILOT_API_FORCE_RESEED=true to force updates
2. Check that bootstrap is running on startup
3. Verify the SeedDemoUsers class is being called

Want to Skip Demo Users

Set GRIDPILOT_API_BOOTSTRAP=false to skip all seeding, or modify the bootstrap logic to exclude demo user seeding specifically.