docs: Add troubleshooting for PostgreSQL init and ADMIN_USERNAMES behavior

Addresses user deployment issues: 1. PostgreSQL database tables not being created automatically 2. Authentication issues when using multiple admin usernames Documentation improvements: - Added comprehensive troubleshooting sections for PostgreSQL database initialization - Clarified that only the first username in ADMIN_USERNAMES is auto-created during initialization - Documented that additional admin usernames must self-register or be created manually - Added step-by-step solutions for both issues Code improvements: - Fixed whitespace handling in ADMIN_USERNAMES parsing (strip whitespace from all usernames) - Fixed whitespace handling in all database initialization scripts to properly strip the first admin username - Ensured consistent behavior across all initialization paths Files updated: - All Docker setup documentation files - Configuration documentation - README and env.example - Database initialization scripts - Config parsing logic
2026-05-06 20:40:38 -05:00 · 2025-12-29 08:00:26 +01:00
parent df9b06c228
commit d3f7fb8998
11 changed files with 230 additions and 10 deletions
@@ -78,7 +78,10 @@ All environment variables can be provided via `.env` and are consumed by the `ap
 - SINGLE_ACTIVE_TIMER: Allow only one active timer per user. Default: `true`.
 - IDLE_TIMEOUT_MINUTES: Auto-pause after idle. Default: `30`.
 - ALLOW_SELF_REGISTER: Allow new users to self-register. Default: `true`.
- ADMIN_USERNAMES: Comma-separated admin usernames. Default: `admin`.
+- ADMIN_USERNAMES: Comma-separated admin usernames. Default: `admin`. **Important**: Only the first username in the list is automatically created during database initialization. Additional admin usernames must either:
+  - Self-register by logging in (if `ALLOW_SELF_REGISTER=true`), or
+  - Be created manually by an existing admin user.
+  Example: `ADMIN_USERNAMES=admin,manager` - only "admin" is created automatically; "manager" must self-register or be created manually.

 ### Authentication

@@ -171,4 +174,70 @@ For CSRF and cookie issues behind proxies, see `docs/CSRF_CONFIGURATION.md`.
 - Database connection: Confirm `db` service is healthy and `DATABASE_URL` points to it.
 - Timezone issues: Set `TZ` to your local timezone [[memory:7499916]].

+### Database Tables Not Created (PostgreSQL)
+
+**Symptoms**: Services start successfully, but database tables are missing when using PostgreSQL (works fine with SQLite).
+
+**Solution**:
+1. Ensure the database container is healthy and the `app` service waits for it:
+   ```bash
+   docker-compose ps
+   docker-compose logs app | grep -i "database\|migration\|initialization"
+   ```
+
+2. Check that Flask-Migrate runs properly during startup. The entrypoint script should automatically:
+   - Initialize Flask-Migrate if needed
+   - Create and apply migrations
+   - Verify tables exist
+
+3. If tables are still missing, manually trigger database initialization:
+   ```bash
+   docker-compose exec app flask db upgrade
+   ```
+
+4. For a fresh start with clean volumes:
+   ```bash
+   docker-compose down -v
+   docker-compose up -d
+   ```
+
+5. Verify tables were created:
+   ```bash
+   docker-compose exec db psql -U timetracker -d timetracker -c "\dt"
+   ```
+
+### Admin User Authentication Issues
+
+**Symptoms**: Cannot login with usernames from `ADMIN_USERNAMES` (e.g., `ADMIN_USERNAMES=admin,manager`).
+
+**Important Notes**:
+- Only the **first** username in `ADMIN_USERNAMES` is automatically created during database initialization
+- Additional admin usernames in the list must be created separately before they can login
+
+**Solutions**:
+
+1. **If using multiple admin usernames**, create them using one of these methods:
+
+   **Option A: Self-Registration** (if `ALLOW_SELF_REGISTER=true`):
+   - Go to the login page
+   - Enter the username (e.g., "manager")
+   - Set a password and login
+   - The user will automatically get admin role if their username is in `ADMIN_USERNAMES`
+
+   **Option B: Manual Creation** (recommended for production):
+   - Login with the first admin user (e.g., "admin")
+   - Go to **Admin → Users → Create User**
+   - Create the additional admin users manually
+   - They will automatically get admin role when they login (if their username is in `ADMIN_USERNAMES`)
+
+2. **If you cannot login with the first admin user**:
+   - Verify the user was created: `docker-compose exec db psql -U timetracker -d timetracker -c "SELECT username, role FROM users;"`
+   - If the user doesn't exist, check container logs for initialization errors
+   - The default admin username is "admin" (or the first value in `ADMIN_USERNAMES`)
+
+3. **For fresh installations**, ensure:
+   - `ADMIN_USERNAMES` is set in your `.env` file before starting containers
+   - Database initialization completed successfully (check logs)
+   - If using `AUTH_METHOD=local`, you'll need to set a password after first login
+

@@ -82,6 +82,10 @@ IDLE_TIMEOUT_MINUTES=30
 DATABASE_URL=postgresql+psycopg2://timetracker:timetracker@db:5432/timetracker
 ```

+> **Important**: When using multiple admin usernames (e.g., `ADMIN_USERNAMES=admin,manager`), only the first username ("admin") is automatically created during database initialization. Additional admin usernames ("manager") must either:
+> - Self-register by logging in (if `ALLOW_SELF_REGISTER=true`), or
+> - Be created manually by the first admin user.
+
 ### Docker Compose Configuration

 Use `docker-compose.remote.yml` (production) or `docker-compose.remote-dev.yml` (testing):
@@ -160,6 +164,39 @@ docker-compose -f docker-compose.remote.yml up -d
 - The image supports multiple architectures automatically
 - If you're on ARM64, the correct image will be pulled automatically

+#### 4. Database Tables Not Created (PostgreSQL)
+
+**Symptoms**: Services start successfully, but database tables are missing when using PostgreSQL.
+
+**Solution:**
+1. Check container logs for initialization errors:
+   ```bash
+   docker-compose -f docker-compose.remote.yml logs app | grep -i "database\|migration\|initialization"
+   ```
+
+2. Manually trigger database initialization:
+   ```bash
+   docker-compose -f docker-compose.remote.yml exec app flask db upgrade
+   ```
+
+3. For a fresh start with clean volumes:
+   ```bash
+   docker-compose -f docker-compose.remote.yml down -v
+   docker-compose -f docker-compose.remote.yml up -d
+   ```
+
+#### 5. Cannot Login with Admin Username
+
+**Symptoms**: Cannot login with usernames from `ADMIN_USERNAMES` (e.g., `ADMIN_USERNAMES=admin,manager`).
+
+**Important**: Only the **first** username in `ADMIN_USERNAMES` is automatically created. Additional admin usernames must be created separately.
+
+**Solution:**
+- **First admin user**: Should be created automatically. If not, check database initialization logs.
+- **Additional admin users**: Either:
+  - Self-register by logging in (if `ALLOW_SELF_REGISTER=true`), or
+  - Login as the first admin and create them manually via **Admin → Users → Create User**
+
 ### Debugging

 #### Check Image Details
@@ -118,3 +118,111 @@ If the issue persists, check:
 - Windows line ending settings
 - Antivirus software blocking Docker
 - Docker daemon logs
+
+---
+
+## Additional Troubleshooting
+
+### Database Tables Not Created (PostgreSQL)
+
+**Symptoms**: Services start successfully, but database tables are missing when using PostgreSQL. Works fine with SQLite.
+
+**Causes**:
+- Flask-Migrate initialization didn't run properly
+- Database container wasn't ready when app started
+- Migration scripts failed silently
+
+**Solutions**:
+
+1. **Check database initialization logs**:
+   ```bash
+   docker-compose logs app | grep -i "database\|migration\|initialization\|flask db"
+   ```
+
+2. **Verify database container is healthy**:
+   ```bash
+   docker-compose ps db
+   docker-compose logs db
+   ```
+
+3. **Manually trigger database initialization**:
+   ```bash
+   docker-compose exec app flask db upgrade
+   ```
+
+4. **For a complete fresh start** (⚠️ **WARNING**: This will delete all data):
+   ```bash
+   docker-compose down -v
+   docker-compose up -d
+   ```
+
+5. **Verify tables exist**:
+   ```bash
+   # PostgreSQL
+   docker-compose exec db psql -U timetracker -d timetracker -c "\dt"
+   
+   # Or check from app container
+   docker-compose exec app python -c "from app import create_app, db; app = create_app(); app.app_context().push(); print(db.engine.table_names())"
+   ```
+
+**Prevention**: The entrypoint script should automatically handle this. If issues persist, check that:
+- The entrypoint script runs properly (check container logs)
+- Database container has `healthcheck` configured
+- App service has `depends_on` with `condition: service_healthy` for the db service
+
+### Admin User Authentication Issues
+
+**Symptoms**: Cannot login with usernames from `ADMIN_USERNAMES` environment variable (e.g., `ADMIN_USERNAMES=admin,manager`).
+
+**Important Understanding**:
+- Only the **first** username in `ADMIN_USERNAMES` is automatically created during database initialization
+- Additional admin usernames in the comma-separated list must be created separately before they can login
+- If `ADMIN_USERNAMES=admin,manager`, only "admin" is created automatically
+
+**Solutions**:
+
+1. **Login with the first admin user**:
+   - Use the first username from `ADMIN_USERNAMES` (default: "admin")
+   - If using `AUTH_METHOD=local`, you may need to set a password on first login
+   - If using `AUTH_METHOD=none`, you can login immediately (no password required)
+
+2. **Create additional admin users**:
+
+   **Option A: Self-Registration** (if `ALLOW_SELF_REGISTER=true`):
+   - Go to login page
+   - Enter the additional admin username (e.g., "manager")
+   - Set a password and login
+   - The user will automatically get admin role because their username is in `ADMIN_USERNAMES`
+
+   **Option B: Manual Creation** (recommended for production):
+   - Login with the first admin user
+   - Navigate to **Admin → Users → Create User**
+   - Create the additional admin users
+   - They will automatically get admin role when they login (if their username is in `ADMIN_USERNAMES`)
+
+3. **Verify admin user exists**:
+   ```bash
+   # PostgreSQL
+   docker-compose exec db psql -U timetracker -d timetracker -c "SELECT username, role, is_active FROM users;"
+   ```
+
+4. **Check environment variable is set correctly**:
+   ```bash
+   docker-compose exec app env | grep ADMIN_USERNAMES
+   ```
+
+5. **If the first admin user doesn't exist**, check:
+   - Database initialization completed successfully (check logs)
+   - `ADMIN_USERNAMES` is set in `.env` file before starting containers
+   - Container logs show admin user creation
+
+**Example Configuration**:
+```bash
+# .env file
+ADMIN_USERNAMES=admin,manager
+ALLOW_SELF_REGISTER=true  # Allows "manager" to self-register
+```
+
+In this example:
+- "admin" is created automatically during initialization
+- "manager" must self-register by logging in (or be created manually)