feat: local SQLite test env, UI fixes, and DB migrations

- UI/UX: Refine layouts and responsive styles; fix task and timer views; update
  shared components and dashboard templates
  - Updates across `app/templates/**`, `templates/**`, `app/static/base.css`,
    and `app/static/mobile.css`
- Backend: Route cleanups and minor fixes for admin, auth, invoices, and timer
  - Touches `app/routes/admin.py`, `app/routes/auth.py`, `app/routes/api.py`,
    `app/routes/invoices.py`, `app/routes/timer.py`
- DevOps: Improve Docker setup and add local testing workflow
  - Update `Dockerfile`, `docker/start-fixed.py`
  - Add `docker-compose.local-test.yml`, `.env.local-test`, start scripts
- Docs: Update `README.md` and add `docs/LOCAL_TESTING_WITH_SQLITE.md`
- Utilities: Adjust CLI and PDF generator behavior

Database (Alembic) migrations:
- 005_add_missing_columns.py
- 006_add_logo_and_task_timestamps.py
- 007_add_invoice_and_more_settings_columns.py
- 008_align_invoices_and_settings_more.py
- 009_add_invoice_created_by.py
- 010_enforce_single_active_timer.py

BREAKING CHANGE: Only one active timer per user is now enforced.

Note: Apply database migrations after deploy (e.g., `alembic upgrade head`).
This commit is contained in:
Dries Peeters
2025-09-10 11:49:49 +02:00
parent dee5e8d4d8
commit 7486037307
48 changed files with 2312 additions and 1151 deletions

View File

@@ -0,0 +1,224 @@
# Local Testing with SQLite
This document explains how to run TimeTracker locally for testing using SQLite instead of PostgreSQL.
## Overview
The local test environment uses:
- **SQLite database** instead of PostgreSQL (no separate database container needed)
- **Development mode** with debug logging enabled
- **Local data persistence** through Docker volumes
- **Simplified setup** for quick testing and development
## Quick Start
### Option 1: Using Scripts (Recommended)
**Windows:**
```cmd
scripts\start-local-test.bat
```
**Linux/macOS:**
```bash
./scripts/start-local-test.sh
```
**PowerShell:**
```powershell
.\scripts\start-local-test.ps1
```
### Option 2: Manual Docker Compose
```bash
docker-compose -f docker-compose.local-test.yml up --build
```
## Configuration
The local test environment uses these key settings:
- **Database**: SQLite at `/data/timetracker.db` (persisted in Docker volume)
- **Port**: 8080 (same as production)
- **Environment**: Development mode with debug enabled
- **Security**: Secure cookies disabled for local testing
- **Logs**: Available in `./logs/` directory
## Environment Variables
You can override default settings using environment variables:
```bash
# Timezone
export TZ=Europe/Brussels
# Currency
export CURRENCY=EUR
# Admin users (comma-separated)
export ADMIN_USERNAMES=admin,testuser
# Secret key (change for security)
export SECRET_KEY=your-local-test-secret-key
# Start with custom settings
docker-compose -f docker-compose.local-test.yml up --build
```
## Data Persistence
- **SQLite database**: Stored in Docker volume `app_data_local_test`
- **Uploads**: Stored in `/data/uploads` (persisted in Docker volume)
- **Logs**: Stored in `./logs/` directory (mounted from host)
## Stopping the Environment
```bash
# Stop containers
docker-compose -f docker-compose.local-test.yml down
# Stop and remove volumes (WARNING: This will delete all data)
docker-compose -f docker-compose.local-test.yml down -v
```
## Accessing the Application
Once started, the application will be available at:
- **URL**: http://localhost:8080
- **Health Check**: http://localhost:8080/_health
## Database Management
### Viewing SQLite Database
You can access the SQLite database directly:
```bash
# Copy database from container to host
docker cp timetracker-app-local-test:/data/timetracker.db ./local-db.sqlite
# Use sqlite3 command line tool
sqlite3 local-db.sqlite
# Or use any SQLite browser tool
```
### Resetting Database
To start with a fresh database:
```bash
# Stop and remove volumes
docker-compose -f docker-compose.local-test.yml down -v
# Start again
docker-compose -f docker-compose.local-test.yml up --build
```
## Troubleshooting
### Container Won't Start
1. **Check Docker is running**:
```bash
docker info
```
2. **Check port 8080 is available**:
```bash
netstat -an | grep 8080
```
3. **View container logs**:
```bash
docker-compose -f docker-compose.local-test.yml logs app
```
### Database Issues
1. **Check database file exists**:
```bash
docker exec timetracker-app-local-test ls -la /data/
```
2. **Reset database**:
```bash
docker-compose -f docker-compose.local-test.yml down -v
docker-compose -f docker-compose.local-test.yml up --build
```
### Permission Issues
The local test setup includes a custom entrypoint that automatically handles permissions. If you still encounter issues:
```bash
# Check container logs for permission errors
docker-compose -f docker-compose.local-test.yml logs app
# If needed, fix permissions manually
docker exec timetracker-app-local-test chown -R timetracker:timetracker /data
```
### Entrypoint Issues
If you encounter issues with the entrypoint script (like `su-exec: not found`), you can use the simplified entrypoint:
1. **Edit docker-compose.local-test.yml** and change the entrypoint line:
```yaml
# Change this line:
entrypoint: ["/app/docker/entrypoint-local-test.sh"]
# To this:
entrypoint: ["/app/docker/entrypoint-local-test-simple.sh"]
```
2. **Restart the container**:
```bash
docker-compose -f docker-compose.local-test.yml down
docker-compose -f docker-compose.local-test.yml up --build
```
The simplified entrypoint runs everything as root, which avoids user switching issues but is less secure (fine for local testing).
### License Server Errors
If you see license server 404 errors, they should be automatically disabled in the local test environment. If you still see them:
1. **Verify environment variable is set**:
```bash
docker exec timetracker-app-local-test env | grep LICENSE_SERVER_ENABLED
```
2. **Should show**: `LICENSE_SERVER_ENABLED=false`
3. **If not set correctly, restart the container**:
```bash
docker-compose -f docker-compose.local-test.yml restart
```
## Differences from Production
| Feature | Local Test | Production |
|---------|------------|------------|
| Database | SQLite | PostgreSQL |
| Debug Mode | Enabled | Disabled |
| Secure Cookies | Disabled | Enabled |
| Data Volume | `app_data_local_test` | `app_data` |
| Container Name | `timetracker-app-local-test` | `timetracker-app` |
## Development Tips
1. **Hot Reload**: The development environment supports hot reloading for Python changes
2. **Logs**: Check `./logs/timetracker.log` for detailed application logs
3. **Database**: Use SQLite browser tools for easier database inspection
4. **Testing**: This environment is perfect for testing new features before production deployment
## Security Note
⚠️ **Important**: This local test environment is configured for development only:
- Secure cookies are disabled
- Debug mode is enabled
- Uses a default secret key
**Never use these settings in production!**