mirror of
https://github.com/DRYTRIX/TimeTracker.git
synced 2026-01-06 11:40:52 -06:00
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:
224
docs/LOCAL_TESTING_WITH_SQLITE.md
Normal file
224
docs/LOCAL_TESTING_WITH_SQLITE.md
Normal 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!**
|
||||
Reference in New Issue
Block a user