mirror of
https://github.com/DRYTRIX/TimeTracker.git
synced 2026-05-17 01:49:35 -05:00
chore: move documentation and assets to docs/
- Move API, ARCHITECTURE, BUILD, DEVELOPMENT, and fix docs to docs/ - Move README variants and WINDOWS_BUILD to docs/ - Move assets and screenshots to docs/assets/ - Update GETTING_STARTED, README, CONTRIBUTOR_GUIDE, PROJECT_STRUCTURE, LOCAL_TESTING_WITH_SQLITE, VERSION_MANAGEMENT
This commit is contained in:
Dries Peeters
@@ -1,118 +0,0 @@
|
||||
# Building TimeTracker Mobile and Desktop Apps
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Build Everything (All Platforms)
|
||||
|
||||
**Linux/macOS:**
|
||||
```bash
|
||||
chmod +x scripts/build-all.sh
|
||||
./scripts/build-all.sh
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```batch
|
||||
scripts\build-all.bat
|
||||
```
|
||||
|
||||
## Available Build Scripts
|
||||
|
||||
### Main Build Scripts
|
||||
|
||||
1. **build-all.sh / build-all.bat** - Build both mobile and desktop apps
|
||||
- Automatically detects platform
|
||||
- Supports flags: `--mobile-only`, `--desktop-only`, `--android-only`, `--ios-only`, `--windows-only`, `--linux-only`, `--macos-only`
|
||||
|
||||
2. **build-mobile.sh / build-mobile.bat** - Build mobile app only
|
||||
- Supports: `android`, `ios`, `all`
|
||||
|
||||
3. **build-desktop.sh / build-desktop.bat** - Build desktop app only
|
||||
- Supports: `win`, `mac`, `linux`, `all`, `current`
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Build Everything
|
||||
```bash
|
||||
# Linux/macOS
|
||||
./scripts/build-all.sh
|
||||
|
||||
# Windows
|
||||
scripts\build-all.bat
|
||||
```
|
||||
|
||||
### Build Mobile Only
|
||||
```bash
|
||||
# Linux/macOS
|
||||
./scripts/build-all.sh --mobile-only
|
||||
# Or
|
||||
./scripts/build-mobile.sh android
|
||||
|
||||
# Windows
|
||||
scripts\build-all.bat --mobile-only
|
||||
# Or
|
||||
scripts\build-mobile.bat android
|
||||
```
|
||||
|
||||
### Build Desktop Only
|
||||
```bash
|
||||
# Linux/macOS
|
||||
./scripts/build-all.sh --desktop-only
|
||||
# Or
|
||||
./scripts/build-desktop.sh current
|
||||
|
||||
# Windows
|
||||
scripts\build-all.bat --desktop-only
|
||||
# Or
|
||||
scripts\build-desktop.bat win
|
||||
```
|
||||
|
||||
### Build Specific Platform
|
||||
```bash
|
||||
# Android only
|
||||
./scripts/build-all.sh --android-only
|
||||
|
||||
# iOS only (macOS)
|
||||
./scripts/build-all.sh --ios-only
|
||||
|
||||
# Windows desktop only
|
||||
scripts\build-all.bat --windows-only
|
||||
|
||||
# Linux desktop only
|
||||
./scripts/build-all.sh --linux-only
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Mobile App
|
||||
- Flutter SDK 3.0+
|
||||
- Android SDK (for Android)
|
||||
- Xcode (for iOS, macOS only)
|
||||
- **App icon:** Launcher icons are generated at the start of each mobile build from `mobile/assets/icon/app_icon.png`. That PNG can be exported once from `app/static/images/timetracker-logo-icon.svg` (1024×1024), or created by running `scripts/generate-mobile-icon.bat` / `scripts/generate-mobile-icon.sh` (requires ImageMagick, Inkscape, or Python with Pillow).
|
||||
|
||||
### Desktop App
|
||||
- Node.js 18+
|
||||
- npm
|
||||
- Platform build tools
|
||||
|
||||
## Build Outputs
|
||||
|
||||
### Mobile App
|
||||
- **Android APK**: `mobile/build/app/outputs/flutter-apk/app-release.apk`
|
||||
- **Android AAB**: `mobile/build/app/outputs/bundle/release/app-release.aab`
|
||||
- **iOS**: `mobile/build/ios/iphoneos/Runner.app`
|
||||
|
||||
### Desktop App
|
||||
- **Windows**: `desktop/dist/*.exe`
|
||||
- **macOS**: `desktop/dist/*.dmg`
|
||||
- **Linux**: `desktop/dist/*.AppImage` and `desktop/dist/*.deb`
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **Mobile launcher icon shows Android default:** Run icon generation and do a full clean build: from `mobile/` run `flutter clean`, `flutter pub get`, `dart run flutter_launcher_icons`, then build again. The build scripts run icon generation automatically; if you built without them, run the above once.
|
||||
- **Icon should match the web app:** Export `app/static/images/timetracker-logo-icon.svg` to 1024×1024 PNG at `mobile/assets/icon/app_icon.png` (see `mobile/assets/icon/README.md`), then run `dart run flutter_launcher_icons` and rebuild.
|
||||
|
||||
See `scripts/README-BUILD.md` for detailed troubleshooting guide.
|
||||
|
||||
## CI/CD
|
||||
|
||||
These scripts are designed to work in CI/CD environments (GitHub Actions workflows are also available in `.github/workflows/`).
|
||||
@@ -1,66 +0,0 @@
|
||||
# Quick Fix for Windows Build Issues
|
||||
|
||||
## Try the Simplified Build Script
|
||||
|
||||
If `build-desktop.bat` stops working, use the simplified version:
|
||||
|
||||
```cmd
|
||||
scripts\build-desktop-simple.bat
|
||||
```
|
||||
|
||||
This version:
|
||||
- Uses simpler logic (no delayed expansion issues)
|
||||
- Has better debug output
|
||||
- More reliable on Windows
|
||||
|
||||
## If That Doesn't Work
|
||||
|
||||
### Step 1: Manual Build
|
||||
|
||||
```cmd
|
||||
cd desktop
|
||||
npm install
|
||||
npx electron-builder --win
|
||||
```
|
||||
|
||||
### Step 2: Check What's Missing
|
||||
|
||||
Run the test script:
|
||||
```cmd
|
||||
scripts\test-build-desktop.bat
|
||||
```
|
||||
|
||||
This will show exactly what's wrong.
|
||||
|
||||
### Step 3: Common Fixes
|
||||
|
||||
1. **Exclude node_modules from OneDrive**
|
||||
- Right-click `desktop\node_modules`
|
||||
- Choose "Always keep on this device"
|
||||
|
||||
2. **Reinstall Dependencies**
|
||||
```cmd
|
||||
cd desktop
|
||||
rmdir /s /q node_modules
|
||||
del package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
3. **Fix Script Issues**
|
||||
```cmd
|
||||
scripts\fix-windows-build.bat
|
||||
```
|
||||
|
||||
## Debugging
|
||||
|
||||
If the script stops after "npm version", check:
|
||||
- Is node_modules missing or corrupted?
|
||||
- Are there OneDrive file locks?
|
||||
- Does `npx` work? Try: `npx --version`
|
||||
|
||||
---
|
||||
|
||||
**Last Resort:** Use the PowerShell script:
|
||||
```powershell
|
||||
.\scripts\build-desktop-windows.ps1
|
||||
```
|
||||
@@ -1,52 +0,0 @@
|
||||
# Building on Windows - Quick Guide
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
**Use the Windows-native build script:**
|
||||
|
||||
```cmd
|
||||
scripts\build-desktop-windows.bat
|
||||
```
|
||||
|
||||
Or in PowerShell:
|
||||
```powershell
|
||||
.\scripts\build-desktop-windows.ps1
|
||||
```
|
||||
|
||||
## ⚠️ Important: OneDrive Issues
|
||||
|
||||
If your project is in OneDrive, you **MUST** exclude `node_modules` from sync:
|
||||
|
||||
1. Right-click `desktop\node_modules` folder
|
||||
2. Choose **"Always keep on this device"**
|
||||
3. Or exclude it from OneDrive sync entirely
|
||||
|
||||
This prevents 90% of Windows build issues!
|
||||
|
||||
## 🔧 If Build Fails
|
||||
|
||||
### Step 1: Fix npm Issues
|
||||
```cmd
|
||||
scripts\fix-windows-build.bat
|
||||
```
|
||||
|
||||
### Step 2: Generate Icons (if missing)
|
||||
```cmd
|
||||
cd desktop
|
||||
npm install sharp
|
||||
cd ..
|
||||
node scripts\generate-icons.js
|
||||
```
|
||||
|
||||
### Step 3: Build Again
|
||||
```cmd
|
||||
scripts\build-desktop-windows.bat
|
||||
```
|
||||
|
||||
## 📋 Full Documentation
|
||||
|
||||
See [README_WINDOWS_BUILD.md](README_WINDOWS_BUILD.md) for complete troubleshooting guide.
|
||||
|
||||
---
|
||||
|
||||
**TL;DR:** Use `scripts\build-desktop-windows.bat` and exclude `node_modules` from OneDrive!
|
||||
@@ -47,7 +47,7 @@ curl -H "X-API-Key: YOUR_API_TOKEN" \
|
||||
| **Search** | `/api/v1/search` | Global search across projects, tasks, clients |
|
||||
| **Time approvals** | `/api/v1/time-entry-approvals` | Approve, reject, request approval for time entries |
|
||||
|
||||
Access is controlled by **scopes** (e.g. `read:projects`, `write:time_entries`). Create a token with the scopes you need; see [API Token Scopes](docs/api/API_TOKEN_SCOPES.md).
|
||||
Access is controlled by **scopes** (e.g. `read:projects`, `write:time_entries`). Create a token with the scopes you need; see [API Token Scopes](api/API_TOKEN_SCOPES.md).
|
||||
|
||||
## Quick Examples
|
||||
|
||||
@@ -71,7 +71,7 @@ Replace `your-domain.com` with your TimeTracker host and `YOUR_API_TOKEN` with y
|
||||
|
||||
## Full Documentation
|
||||
|
||||
- **[REST API reference](docs/api/REST_API.md)** — All endpoints, request/response formats, pagination, errors
|
||||
- **[API Consistency Audit](docs/api/API_CONSISTENCY_AUDIT.md)** — Response contracts, error format, pagination
|
||||
- **[API Token Scopes](docs/api/API_TOKEN_SCOPES.md)** — Scopes and permissions
|
||||
- **[API Versioning](docs/api/API_VERSIONING.md)** — Versioning policy and usage
|
||||
- **[REST API reference](api/REST_API.md)** — All endpoints, request/response formats, pagination, errors
|
||||
- **[API Consistency Audit](api/API_CONSISTENCY_AUDIT.md)** — Response contracts, error format, pagination
|
||||
- **[API Token Scopes](api/API_TOKEN_SCOPES.md)** — Scopes and permissions
|
||||
- **[API Versioning](api/API_VERSIONING.md)** — Versioning policy and usage
|
||||
@@ -74,27 +74,27 @@ API endpoints are versioned under `/api/v1/`. Authentication is session-based fo
|
||||
- **Base URL:** `/api/v1/`
|
||||
- **Auth:** API token in header `Authorization: Bearer <token>` or `X-API-Key: <token>`. Tokens are created in Admin → Api-tokens and have scopes (e.g. `read:projects`, `write:time_entries`).
|
||||
- **Sub-blueprints (all under `/api/v1/`):** `api_v1` (info, health, auth/login), `api_v1_time_entries`, `api_v1_projects`, `api_v1_tasks`, `api_v1_clients`, `api_v1_invoices`, `api_v1_expenses`, `api_v1_payments`, `api_v1_mileage`, `api_v1_deals`, `api_v1_leads`, `api_v1_contacts`, plus remaining routes in `api_v1` (time-entry-approvals, per-diems, budget-alerts, calendar, kanban, saved-filters, etc.).
|
||||
- **Full reference:** [REST API](docs/api/REST_API.md).
|
||||
- **Full reference:** [REST API](api/REST_API.md).
|
||||
|
||||
## Backend vs Frontend
|
||||
|
||||
- **Backend:** Flask (Python), Jinja2, SQLAlchemy, Flask-Migrate, Flask-Login, Authlib (OIDC), Flask-SocketIO, APScheduler. Configuration via environment variables (see `env.example`).
|
||||
- **Frontend:** Server-rendered HTML from Jinja2, styled with **Tailwind CSS**. JavaScript is used for interactivity (e.g. Chart.js, command palette, forms). The app can be used as a **PWA** (offline and installable). There is no separate SPA; the main UI is server-rendered with JS enhancements.
|
||||
- **UI layer:** The base layout is `app/templates/base.html` (sidebar, header, main content area). Styling uses **Tailwind** and design tokens in `app/static/src/input.css`. Reusable UI is built from **component macros** in `app/templates/components/ui.html` and `app/templates/components/cards.html` (page headers, stat cards, empty states, modals, buttons). Layout uses a max-width content container and consistent grid and spacing. See [UI Guidelines](docs/UI_GUIDELINES.md) and [Project Structure](docs/development/PROJECT_STRUCTURE.md) for templates and static assets.
|
||||
- **UI layer:** The base layout is `app/templates/base.html` (sidebar, header, main content area). Styling uses **Tailwind** and design tokens in `app/static/src/input.css`. Reusable UI is built from **component macros** in `app/templates/components/ui.html` and `app/templates/components/cards.html` (page headers, stat cards, empty states, modals, buttons). Layout uses a max-width content container and consistent grid and spacing. See [UI Guidelines](UI_GUIDELINES.md) and [Project Structure](development/PROJECT_STRUCTURE.md) for templates and static assets.
|
||||
- **Native clients:** The **desktop** (Electron) and **mobile** (Flutter) apps are separate codebases that consume the REST API.
|
||||
|
||||
## Design Decisions
|
||||
|
||||
- **Service layer:** Business logic lives in `app/services/` so routes stay thin and logic is reusable and testable. See [Service Layer and Base CRUD](docs/development/SERVICE_LAYER_AND_BASE_CRUD.md) and the [Architecture Migration Guide](docs/implementation-notes/ARCHITECTURE_MIGRATION_GUIDE.md).
|
||||
- **Service layer:** Business logic lives in `app/services/` so routes stay thin and logic is reusable and testable. See [Service Layer and Base CRUD](development/SERVICE_LAYER_AND_BASE_CRUD.md) and the [Architecture Migration Guide](implementation-notes/ARCHITECTURE_MIGRATION_GUIDE.md).
|
||||
- **API v1 split:** Core resources (projects, tasks, clients, invoices, expenses, payments, mileage, deals, leads, contacts) are in separate sub-blueprints (`api_v1_*.py`) under `/api/v1/` for maintainability; the main `api_v1` module keeps info, health, auth, and remaining endpoints.
|
||||
- **Bootstrap:** Logging is configured in `app/utils/setup_logging.py`; legacy migration helpers (task management, issues tables) are in `app/utils/legacy_migrations.py`. `app/__init__.py` creates the app and wires extensions.
|
||||
- **Blueprint registry:** All blueprints are registered from `app/blueprint_registry.py` to keep registration in one place and simplify adding new modules.
|
||||
- **Database:** **PostgreSQL** is recommended for production; **SQLite** is supported for development and testing (e.g. `docker-compose.local-test.yml`).
|
||||
- **Database:** **PostgreSQL** is recommended for production; **SQLite** is supported for development and testing (e.g. `docker/docker-compose.local-test.yml`).
|
||||
- **API auth:** The REST API uses API tokens (created in Admin → Api-tokens) with scopes; no session cookies for API access.
|
||||
- **Single codebase for web UI:** No separate frontend repo; templates and static assets live in the main repo under `app/templates/` and `app/static/`.
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [Project Structure](docs/development/PROJECT_STRUCTURE.md) — Folder layout and file roles
|
||||
- [Architecture Migration Guide](docs/implementation-notes/ARCHITECTURE_MIGRATION_GUIDE.md) — Moving routes to the service layer
|
||||
- [REST API](docs/api/REST_API.md) — API reference and authentication
|
||||
- [Project Structure](development/PROJECT_STRUCTURE.md) — Folder layout and file roles
|
||||
- [Architecture Migration Guide](implementation-notes/ARCHITECTURE_MIGRATION_GUIDE.md) — Moving routes to the service layer
|
||||
- [REST API](api/REST_API.md) — API reference and authentication
|
||||
@@ -51,7 +51,7 @@ Quick reference for running the project locally, running tests, and contributing
|
||||
For a quick run without installing Python locally:
|
||||
|
||||
```bash
|
||||
docker-compose -f docker-compose.local-test.yml up --build
|
||||
docker-compose -f docker/docker-compose.local-test.yml up --build
|
||||
```
|
||||
|
||||
Then open http://localhost:8080. See [Local Testing with SQLite](docs/development/LOCAL_TESTING_WITH_SQLITE.md) for details.
|
||||
@@ -83,7 +83,7 @@ TimeTracker/
|
||||
└── requirements.txt # Python dependencies
|
||||
```
|
||||
|
||||
For more detail, see [ARCHITECTURE.md](ARCHITECTURE.md) and [Project Structure](docs/development/PROJECT_STRUCTURE.md).
|
||||
For more detail, see [ARCHITECTURE.md](ARCHITECTURE.md) and [Project Structure](development/PROJECT_STRUCTURE.md).
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
@@ -119,7 +119,7 @@ See [Contributing – Testing](docs/development/CONTRIBUTING.md#testing) for mor
|
||||
|
||||
- **Web app:** No separate frontend build required; Tailwind and static assets are served as-is (or built via your pipeline if you use one). Run the app with `flask run` or `python app.py`.
|
||||
- **Docker image:** `docker build -t timetracker .` from repo root. See [Docker Compose Setup](docs/admin/configuration/DOCKER_COMPOSE_SETUP.md).
|
||||
- **Mobile/Desktop:** See [BUILD.md](BUILD.md) and [docs/mobile-desktop-apps/README.md](docs/mobile-desktop-apps/README.md) for Flutter and Electron build steps.
|
||||
- **Mobile/Desktop:** See [BUILD.md](build/BUILD.md) and [mobile-desktop-apps/README.md](mobile-desktop-apps/README.md) for Flutter and Electron build steps.
|
||||
|
||||
## Contributing
|
||||
|
||||
@@ -62,7 +62,7 @@ Want to try it without setting up a database?
|
||||
|
||||
```bash
|
||||
# Start with SQLite (no database setup needed)
|
||||
docker-compose -f docker-compose.local-test.yml up --build
|
||||
docker-compose -f docker/docker-compose.local-test.yml up --build
|
||||
|
||||
# Access at: http://localhost:8080
|
||||
```
|
||||
|
||||
+6
-6
@@ -9,9 +9,9 @@ Welcome to the comprehensive TimeTracker documentation. Everything you need to i
|
||||
- **[🚀 Getting Started Guide](GETTING_STARTED.md)** — Complete beginner tutorial (⭐ Start here!)
|
||||
- **[Main README](../README.md)** — Product overview and quick start
|
||||
- **[Installation Guide](../INSTALLATION.md)** — Step-by-step installation (Docker, SQLite)
|
||||
- **[Architecture](../ARCHITECTURE.md)** — System overview and design
|
||||
- **[Development Guide](../DEVELOPMENT.md)** — Run locally, tests, releases
|
||||
- **[API Quick Reference](../API.md)** — REST API overview and examples
|
||||
- **[Architecture](ARCHITECTURE.md)** — System overview and design
|
||||
- **[Development Guide](DEVELOPMENT.md)** — Run locally, tests, releases
|
||||
- **[API Quick Reference](API.md)** — REST API overview and examples
|
||||
- **[Installation & Deployment](#-installation--deployment)** — Get TimeTracker running
|
||||
- **[Feature Guides](#-feature-documentation)** — Learn what TimeTracker can do
|
||||
- **[Troubleshooting](#-troubleshooting)** — Solve common issues
|
||||
@@ -123,8 +123,8 @@ Use consistent terms in code, API, and user-facing copy: **time entry** / **time
|
||||
- **[Contributor Guide](development/CONTRIBUTOR_GUIDE.md)** — Architecture, local dev, testing, adding routes/services/templates, versioning
|
||||
- **[Contributing](../CONTRIBUTING.md)** — How to contribute (root; quick overview)
|
||||
- **[Contributing Guidelines (full)](development/CONTRIBUTING.md)** — Setup, standards, PR process
|
||||
- **[Development Guide](../DEVELOPMENT.md)** — Run locally, tests, releases (root)
|
||||
- **[Architecture](../ARCHITECTURE.md)** — System overview and design (root)
|
||||
- **[Development Guide](DEVELOPMENT.md)** — Run locally, tests, releases
|
||||
- **[Architecture](ARCHITECTURE.md)** — System overview and design
|
||||
- **[Code of Conduct](development/CODE_OF_CONDUCT.md)** — Community standards
|
||||
- **[Project Structure](development/PROJECT_STRUCTURE.md)** — Codebase organization and architecture
|
||||
|
||||
@@ -159,7 +159,7 @@ Use consistent terms in code, API, and user-facing copy: **time entry** / **time
|
||||
|
||||
## 📚 API Documentation
|
||||
|
||||
- **[API Quick Reference](../API.md)** — Overview and quick examples (root)
|
||||
- **[API Quick Reference](API.md)** — Overview and quick examples
|
||||
- **[REST API](api/REST_API.md)** — Complete API reference with all endpoints (⭐ Full reference!)
|
||||
- **[API Token Scopes](api/API_TOKEN_SCOPES.md)** — Understanding token permissions and scopes
|
||||
- **[API Versioning](api/API_VERSIONING.md)** — API versioning strategy
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
This document describes the comprehensive version management system for TimeTracker that provides flexible versioning for both GitHub releases and build numbers.
|
||||
|
||||
**For contributors:** Application version is defined only in **setup.py**. Do not duplicate it in README or other docs. Desktop and mobile builds may use their own version numbers; see [BUILD.md](../../../BUILD.md) and repo scripts.
|
||||
**For contributors:** Application version is defined only in **setup.py**. Do not duplicate it in README or other docs. Desktop and mobile builds may use their own version numbers; see [BUILD.md](../../build/BUILD.md) and repo scripts.
|
||||
|
||||
## Overview
|
||||
|
||||
|
||||
|
Before Width: | Height: | Size: 111 KiB After Width: | Height: | Size: 111 KiB |
|
Before Width: | Height: | Size: 60 KiB After Width: | Height: | Size: 60 KiB |
|
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 58 KiB |
|
Before Width: | Height: | Size: 80 KiB After Width: | Height: | Size: 80 KiB |
|
Before Width: | Height: | Size: 99 KiB After Width: | Height: | Size: 99 KiB |
|
Before Width: | Height: | Size: 102 KiB After Width: | Height: | Size: 102 KiB |
|
Before Width: | Height: | Size: 63 KiB After Width: | Height: | Size: 63 KiB |
|
Before Width: | Height: | Size: 91 KiB After Width: | Height: | Size: 91 KiB |
|
Before Width: | Height: | Size: 57 KiB After Width: | Height: | Size: 57 KiB |
|
Before Width: | Height: | Size: 69 KiB After Width: | Height: | Size: 69 KiB |
|
Before Width: | Height: | Size: 63 KiB After Width: | Height: | Size: 63 KiB |
|
Before Width: | Height: | Size: 37 KiB After Width: | Height: | Size: 37 KiB |
|
Before Width: | Height: | Size: 100 KiB After Width: | Height: | Size: 100 KiB |
|
Before Width: | Height: | Size: 58 KiB After Width: | Height: | Size: 58 KiB |
|
Before Width: | Height: | Size: 143 KiB After Width: | Height: | Size: 143 KiB |
|
Before Width: | Height: | Size: 64 KiB After Width: | Height: | Size: 64 KiB |
|
Before Width: | Height: | Size: 154 KiB After Width: | Height: | Size: 154 KiB |
|
Before Width: | Height: | Size: 57 KiB After Width: | Height: | Size: 57 KiB |
|
Before Width: | Height: | Size: 114 KiB After Width: | Height: | Size: 114 KiB |
@@ -18,7 +18,7 @@ flowchart LR
|
||||
Models --> DB[(DB)]
|
||||
```
|
||||
|
||||
**More**: [ARCHITECTURE.md](../../ARCHITECTURE.md) · [Project Structure](PROJECT_STRUCTURE.md)
|
||||
**More**: [ARCHITECTURE.md](../ARCHITECTURE.md) · [Project Structure](PROJECT_STRUCTURE.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -32,11 +32,11 @@ flowchart LR
|
||||
6. **Run**: `flask run` → http://127.0.0.1:5000.
|
||||
|
||||
**Docker (no local Python)**:
|
||||
- **SQLite (quick test)**: `docker-compose -f docker-compose.local-test.yml up --build` → http://localhost:8080.
|
||||
- **SQLite (quick test)**: `docker-compose -f docker/docker-compose.local-test.yml up --build` → http://localhost:8080.
|
||||
- **Default (HTTPS)**: `docker-compose up -d` → https://localhost (self-signed cert).
|
||||
- **HTTP 8080**: `docker-compose -f docker-compose.example.yml up -d` → http://localhost:8080.
|
||||
|
||||
**More**: [Local Testing with SQLite](LOCAL_TESTING_WITH_SQLITE.md) · [DEVELOPMENT.md](../../DEVELOPMENT.md)
|
||||
**More**: [Local Testing with SQLite](LOCAL_TESTING_WITH_SQLITE.md) · [DEVELOPMENT.md](../DEVELOPMENT.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -71,7 +71,7 @@ Run the full test suite before opening a PR. Add tests for new behavior (e.g. in
|
||||
3. Follow existing patterns (see [Service Layer and Base CRUD](SERVICE_LAYER_AND_BASE_CRUD.md)); use `BaseCRUDService` only when the domain is simple CRUD with an existing repository.
|
||||
4. Call the service from routes; add tests in `tests/test_services/` or `tests/test_repositories/`.
|
||||
|
||||
**More**: [SERVICE_LAYER_AND_BASE_CRUD.md](SERVICE_LAYER_AND_BASE_CRUD.md) · [ARCHITECTURE.md](../../ARCHITECTURE.md)
|
||||
**More**: [SERVICE_LAYER_AND_BASE_CRUD.md](SERVICE_LAYER_AND_BASE_CRUD.md) · [ARCHITECTURE.md](../ARCHITECTURE.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -87,7 +87,7 @@ Run the full test suite before opening a PR. Add tests for new behavior (e.g. in
|
||||
## Versioning
|
||||
|
||||
- **Application version**: Defined **only** in `setup.py`. Do not duplicate it in README or other docs.
|
||||
- **Desktop / mobile**: Desktop and mobile builds may use their own version numbers; see [BUILD.md](../../BUILD.md) and repo scripts. Align with app version when releasing together.
|
||||
- **Desktop / mobile**: Desktop and mobile builds may use their own version numbers; see [BUILD.md](../build/BUILD.md) and repo scripts. Align with app version when releasing together.
|
||||
- **Releases and Docker images**: Tagging, GitHub releases, and image publishing are in [VERSION_MANAGEMENT.md](../admin/deployment/VERSION_MANAGEMENT.md) and [RELEASE_PROCESS.md](../admin/deployment/RELEASE_PROCESS.md).
|
||||
|
||||
**For contributors**: When updating the app version, change only `setup.py`. Do not add the version number to README, FEATURES_COMPLETE, or PROJECT_STRUCTURE.
|
||||
|
||||
@@ -32,7 +32,7 @@ scripts\start-local-test.bat
|
||||
### Option 2: Manual Docker Compose
|
||||
|
||||
```bash
|
||||
docker-compose -f docker-compose.local-test.yml up --build
|
||||
docker-compose -f docker/docker-compose.local-test.yml up --build
|
||||
```
|
||||
|
||||
## Configuration
|
||||
@@ -63,7 +63,7 @@ export ADMIN_USERNAMES=admin,testuser
|
||||
export SECRET_KEY=your-local-test-secret-key
|
||||
|
||||
# Start with custom settings
|
||||
docker-compose -f docker-compose.local-test.yml up --build
|
||||
docker-compose -f docker/docker-compose.local-test.yml up --build
|
||||
```
|
||||
|
||||
## Data Persistence
|
||||
@@ -76,10 +76,10 @@ docker-compose -f docker-compose.local-test.yml up --build
|
||||
|
||||
```bash
|
||||
# Stop containers
|
||||
docker-compose -f docker-compose.local-test.yml down
|
||||
docker-compose -f docker/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
|
||||
docker-compose -f docker/docker-compose.local-test.yml down -v
|
||||
```
|
||||
|
||||
## Accessing the Application
|
||||
@@ -110,10 +110,10 @@ To start with a fresh database:
|
||||
|
||||
```bash
|
||||
# Stop and remove volumes
|
||||
docker-compose -f docker-compose.local-test.yml down -v
|
||||
docker-compose -f docker/docker-compose.local-test.yml down -v
|
||||
|
||||
# Start again
|
||||
docker-compose -f docker-compose.local-test.yml up --build
|
||||
docker-compose -f docker/docker-compose.local-test.yml up --build
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
@@ -132,7 +132,7 @@ docker-compose -f docker-compose.local-test.yml up --build
|
||||
|
||||
3. **View container logs**:
|
||||
```bash
|
||||
docker-compose -f docker-compose.local-test.yml logs app
|
||||
docker-compose -f docker/docker-compose.local-test.yml logs app
|
||||
```
|
||||
|
||||
### Database Issues
|
||||
@@ -144,8 +144,8 @@ docker-compose -f docker-compose.local-test.yml up --build
|
||||
|
||||
2. **Reset database**:
|
||||
```bash
|
||||
docker-compose -f docker-compose.local-test.yml down -v
|
||||
docker-compose -f docker-compose.local-test.yml up --build
|
||||
docker-compose -f docker/docker-compose.local-test.yml down -v
|
||||
docker-compose -f docker/docker-compose.local-test.yml up --build
|
||||
```
|
||||
|
||||
### Permission Issues
|
||||
@@ -154,7 +154,7 @@ The local test setup includes a custom entrypoint that automatically handles per
|
||||
|
||||
```bash
|
||||
# Check container logs for permission errors
|
||||
docker-compose -f docker-compose.local-test.yml logs app
|
||||
docker-compose -f docker/docker-compose.local-test.yml logs app
|
||||
|
||||
# If needed, fix permissions manually
|
||||
docker exec timetracker-app-local-test chown -R timetracker:timetracker /data
|
||||
@@ -164,7 +164,7 @@ docker exec timetracker-app-local-test chown -R timetracker:timetracker /data
|
||||
|
||||
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:
|
||||
1. **Edit docker/docker-compose.local-test.yml** and change the entrypoint line:
|
||||
```yaml
|
||||
# Change this line:
|
||||
entrypoint: ["/app/docker/entrypoint-local-test.sh"]
|
||||
@@ -175,8 +175,8 @@ If you encounter issues with the entrypoint script (like `su-exec: not found`),
|
||||
|
||||
2. **Restart the container**:
|
||||
```bash
|
||||
docker-compose -f docker-compose.local-test.yml down
|
||||
docker-compose -f docker-compose.local-test.yml up --build
|
||||
docker-compose -f docker/docker-compose.local-test.yml down
|
||||
docker-compose -f docker/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).
|
||||
|
||||
@@ -23,9 +23,9 @@ TimeTracker/
|
||||
├── 🐳 Dockerfile # Main Dockerfile
|
||||
├── 📄 docker-compose.yml # Default stack (HTTPS via nginx)
|
||||
├── 📄 docker-compose.example.yml # HTTP on port 8080 (no nginx)
|
||||
├── 📄 docker-compose.local-test.yml # SQLite, HTTP 8080 (quick test)
|
||||
├── 📄 docker-compose.remote.yml # Remote/production compose (ghcr.io)
|
||||
├── 📄 docker-compose.remote-dev.yml # Remote dev/testing compose (ghcr.io)
|
||||
├── 📄 docker/docker-compose.local-test.yml # SQLite, HTTP 8080 (quick test)
|
||||
├── 📄 docker/docker-compose.remote.yml # Remote/production compose (ghcr.io)
|
||||
├── 📄 docker/docker-compose.remote-dev.yml # Remote dev/testing compose (ghcr.io)
|
||||
├── 📄 requirements.txt # Python dependencies
|
||||
├── 📄 app.py # Application entry point
|
||||
├── 📄 env.example # Environment variables template
|
||||
@@ -57,7 +57,7 @@ TimeTracker/
|
||||
|
||||
### Files Consolidated
|
||||
- **Dockerfiles**: Primary `Dockerfile` at repo root; additional Dockerfiles in `docker/` as needed
|
||||
- **Docker Compose**: `docker-compose.yml` (local), `docker-compose.remote.yml`, `docker-compose.remote-dev.yml`
|
||||
- **Docker Compose**: `docker-compose.yml` (local), `docker/docker-compose.remote.yml`, `docker/docker-compose.remote-dev.yml`
|
||||
- **Deployment**: `deploy-public.bat`, `deploy-public.sh`
|
||||
|
||||
## 🏗️ Core Components
|
||||
@@ -91,15 +91,15 @@ TimeTracker/
|
||||
|
||||
### 2. HTTP (no HTTPS)
|
||||
- **File**: `docker-compose.example.yml` — app on **http://localhost:8080** (published image or build).
|
||||
- **File**: `docker-compose.local-test.yml` — SQLite, **http://localhost:8080** (no PostgreSQL).
|
||||
- **File**: `docker/docker-compose.local-test.yml` — SQLite, **http://localhost:8080** (no PostgreSQL).
|
||||
|
||||
### 3. Remote/Production
|
||||
- **File**: `docker-compose.remote.yml`
|
||||
- **File**: `docker/docker-compose.remote.yml`
|
||||
- **Image**: `ghcr.io/drytrix/timetracker:latest` (or versioned tag)
|
||||
- **Use case**: Production deployment
|
||||
|
||||
### 4. Remote Dev/Testing
|
||||
- **File**: `docker-compose.remote-dev.yml`
|
||||
- **File**: `docker/docker-compose.remote-dev.yml`
|
||||
- **Image**: `ghcr.io/drytrix/timetracker:development`
|
||||
- **Use case**: Pre-release testing
|
||||
|
||||
@@ -108,10 +108,10 @@ TimeTracker/
|
||||
- **README.md** (root): Main project documentation and quick start guide
|
||||
- **CONTRIBUTING.md** (root): [Contributing](../../CONTRIBUTING.md) — quick overview; full guidelines in [CONTRIBUTING.md](CONTRIBUTING.md) (this folder)
|
||||
- **CODE_OF_CONDUCT.md** (this folder): [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — community guidelines
|
||||
- **ARCHITECTURE.md** (root): [Architecture overview](../../ARCHITECTURE.md)
|
||||
- **ARCHITECTURE.md**: [Architecture overview](../ARCHITECTURE.md)
|
||||
- **INSTALLATION.md** (root): [Installation guide](../../INSTALLATION.md)
|
||||
- **DEVELOPMENT.md** (root): [Development guide](../../DEVELOPMENT.md)
|
||||
- **API.md** (root): [API quick reference](../../API.md)
|
||||
- **DEVELOPMENT.md**: [Development guide](../DEVELOPMENT.md)
|
||||
- **API.md**: [API quick reference](../API.md)
|
||||
- **PROJECT_STRUCTURE.md** (this folder): Project structure overview
|
||||
- **TASK_MANAGEMENT_README.md** (docs/): Detailed Task Management feature documentation
|
||||
|
||||
@@ -163,7 +163,7 @@ The Task Management feature is fully integrated into the application with automa
|
||||
|
||||
1. **Choose deployment type**: Local dev, remote, or remote-dev
|
||||
2. **Follow README.md**: Complete setup instructions
|
||||
3. **Use appropriate compose file**: `docker-compose.yml`, `docker-compose.remote.yml`, or `docker-compose.remote-dev.yml`
|
||||
3. **Use appropriate compose file**: `docker-compose.yml`, `docker/docker-compose.remote.yml`, or `docker/docker-compose.remote-dev.yml`
|
||||
4. **Configure timezone**: Access admin settings to set your local timezone
|
||||
|
||||
## Versioning
|
||||
|
||||
Reference in New Issue
Block a user