mirror of
https://github.com/DRYTRIX/TimeTracker.git
synced 2026-05-19 12:50:11 -05:00
Dries Peeters
0a4b29c50d
- Add run_seed() in app/utils/seed_dev_data.py: users, clients, projects, tasks, time entries, expenses, comments, warehouses, stock items, warehouse stock, stock movements, currencies, tax rules, invoices, invoice items, and payments. Only runs when FLASK_ENV=development. - Register 'flask seed' CLI command with options (users, clients, projects-per-client, tasks-per-project, days-back). - Add scripts/seed-dev-data.py and docker/seed-dev-data.sh for local and Docker runs. Include seed scripts in image via Dockerfile chmod. - Document in docs/development/SEED_DEV_DATA.md; update DATABASE_RECOVERY.md, DOCKER_COMPOSE_SETUP.md, and development README.
84 lines
3.4 KiB
Markdown
84 lines
3.4 KiB
Markdown
# Development Data Seeding
|
||
|
||
The application can be seeded with rich test data for local development. Seeding **only runs when `FLASK_ENV=development`** and is disabled in production and testing.
|
||
|
||
## What Gets Seeded
|
||
|
||
| Category | Data | Default counts |
|
||
|----------|------|----------------|
|
||
| **Users** | Admin (if missing), dev users `devuser1`–`devuser4` (password: `dev`) | 4 extra users |
|
||
| **Clients** | Named clients with contact details and hourly rates | 20 |
|
||
| **Projects** | Projects per client (e.g. Website, Mobile App, API) | 4 per client |
|
||
| **Tasks** | Tasks per project (todo / in progress / review / done) | 12 per project |
|
||
| **Time entries** | Closed entries over the last 120 days, linked to tasks | Up to 1500 |
|
||
| **Expenses** | Expense categories (Travel, Meals, etc.), expenses on projects | 7 categories, 50 expenses |
|
||
| **Comments** | Internal comments on tasks | 80 |
|
||
| **Inventory** | Warehouses, stock items, warehouse stock levels, stock movements | 3 warehouses, 15 items, ~40 movements |
|
||
| **Finance** | Currencies (EUR, USD), tax rules (VAT), invoices with line items, payments | 2 currencies, 2 tax rules, 25 invoices, payments on up to 20 invoices |
|
||
|
||
## How to Run
|
||
|
||
### Local (no Docker)
|
||
|
||
Set the environment to development, then run the seed:
|
||
|
||
```bash
|
||
# Required: development only
|
||
export FLASK_ENV=development # Linux/macOS
|
||
# or: set FLASK_ENV=development (Windows CMD)
|
||
# or: $env:FLASK_ENV="development" (PowerShell)
|
||
|
||
# Option A: Flask CLI
|
||
flask seed
|
||
|
||
# Option B: Standalone script (sets FLASK_ENV=development by default when unset)
|
||
python scripts/seed-dev-data.py
|
||
```
|
||
|
||
### Docker
|
||
|
||
From the host, run the seed inside the app container. The image defaults to `FLASK_ENV=production`, so use the wrapper script or pass the env explicitly:
|
||
|
||
```bash
|
||
# Option A: Wrapper script (recommended)
|
||
docker compose exec app /app/docker/seed-dev-data.sh
|
||
|
||
# Option B: Flask CLI with env
|
||
docker compose exec -e FLASK_ENV=development app flask seed
|
||
```
|
||
|
||
### Flask seed options
|
||
|
||
You can tune some counts via CLI options:
|
||
|
||
```bash
|
||
flask seed --users 2 --clients 10 --projects-per-client 3 --tasks-per-project 8 --days-back 60
|
||
```
|
||
|
||
Inventory and finance counts use defaults; to change them, call `run_seed()` from code or extend the CLI (see `app/utils/seed_dev_data.py` and `app/utils/cli.py`).
|
||
|
||
## When to Use
|
||
|
||
- After a **database reset** (e.g. `scripts/reset-dev-db.py` or `docker compose exec app python3 /app/scripts/reset-dev-db.py`) to get a full dataset.
|
||
- On a **fresh database** (after migrations) to avoid entering data by hand.
|
||
- To test **reports, dashboards, and filters** with realistic volume.
|
||
|
||
## Safety
|
||
|
||
- The seed **refuses to run** unless `FLASK_ENV=development`. In production it raises an error.
|
||
- Running the seed multiple times is **additive**: it skips entities that already exist (e.g. clients by name, invoices by number) and adds new ones where applicable (e.g. more time entries, tasks).
|
||
|
||
## Files
|
||
|
||
| File | Purpose |
|
||
|------|--------|
|
||
| `app/utils/seed_dev_data.py` | Core logic: `run_seed()` and data constants |
|
||
| `app/utils/cli.py` | `flask seed` command registration |
|
||
| `scripts/seed-dev-data.py` | Standalone script for local or CI |
|
||
| `docker/seed-dev-data.sh` | Docker wrapper that sets `FLASK_ENV=development` and runs the Python script |
|
||
|
||
## Related
|
||
|
||
- [Database Recovery](../DATABASE_RECOVERY.md) – reset and seed from Docker
|
||
- [Docker Compose Setup](../admin/configuration/DOCKER_COMPOSE_SETUP.md) – development seed step in troubleshooting
|