mirror/TimeTracker
1
0
Fork 0
mirror of https://github.com/DRYTRIX/TimeTracker.git synced 2026-05-19 12:50:11 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
2f838adeee3fe45f64d4efd62ef35cc753cc16af
TimeTracker/docs/README.md
T
Dries Peeters e34a668ddc feat(auth): add LDAP directory authentication 
Introduce AUTH_METHOD values ldap and all, with LDAP_* environment settings, ldap3-based LDAPService (search, optional groupOfNames checks, user bind, DB sync), and users.auth_provider (local|oidc|ldap) via migration 153_add_user_auth_provider.

Login supports LDAP-only and combined all (local then LDAP where appropriate); OIDC callback sets auth_provider. Forgot/reset/change password flows skip LDAP-managed accounts. Admin System Settings gains a read-only LDAP summary and POST /admin/ldap/test. Production env validation requires core LDAP variables when LDAP is enabled; OIDC registration and docs recognize all.

Documentation: new docs/admin/configuration/LDAP_SETUP.md; updates to OIDC_SETUP, GETTING_STARTED, Docker guides, Render deploy notes, docs README, and CHANGELOG. Tests: tests/test_ldap_auth.py; test_oidc_logout allows auth_method all.
2026-04-27 19:08:08 +02:00

376 lines
16 KiB
Markdown
Raw Blame History

# TimeTracker Documentation
Welcome to the comprehensive TimeTracker documentation. Everything you need to install, configure, use, and contribute to TimeTracker.
---
## 📖 Quick Links
- **[🚀 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
- **[Installation & Deployment](#-installation--deployment)** — Get TimeTracker running
- **[Feature Guides](#-feature-documentation)** — Learn what TimeTracker can do
- **[Troubleshooting](#-troubleshooting)** — Solve common issues
---
## 🗺️ Documentation Map
```
docs/
├── 👤 User Documentation
│ ├── Getting Started
│ ├── Feature Guides
│ └── User Guides
│
├── 🔧 Administrator Documentation
│ ├── Configuration
│ ├── Deployment
│ ├── Security
│ └── Monitoring
│
├── 👨‍💻 Developer Documentation
│ ├── Contributing
│ ├── Architecture
│ ├── Development Setup
│ └── Testing
│
└── 📚 Reference
├── API Documentation
├── Implementation Notes
└── Reports
```
---
## 👤 User Documentation
### Getting Started
- **[🚀 Getting Started Guide](GETTING_STARTED.md)** — Complete beginner tutorial (⭐ Start here!)
- **[Installation Guide](../INSTALLATION.md)** — Step-by-step installation (root)
- **[Requirements](REQUIREMENTS.md)** — System requirements and dependencies
### User Guides
- **How to deploy**: [Docker Compose Setup](admin/configuration/DOCKER_COMPOSE_SETUP.md) · [Docker Public Setup](admin/configuration/DOCKER_PUBLIC_SETUP.md)
- **[Quick Wins Implementation (Deployment Checklist)](guides/DEPLOYMENT_GUIDE.md)** — Feature implementation status (not deployment steps)
- **[Quick Start Guide](guides/QUICK_START_GUIDE.md)** — Get started quickly
- **[Quick Start Local Development](guides/QUICK_START_LOCAL_DEVELOPMENT.md)** — Local development setup
### Feature Documentation
- **[📋 Complete Features Overview](FEATURES_COMPLETE.md)** — Comprehensive documentation of all 130+ features (⭐ Complete reference!)
- **[Task Management](TASK_MANAGEMENT_README.md)** — Complete task tracking system
- **[Client Management](CLIENT_MANAGEMENT_README.md)** — Manage clients and relationships
- **[Invoice System](INVOICE_FEATURE_README.md)** — Generate and track invoices
- **[Calendar Features](CALENDAR_FEATURES_README.md)** — Calendar view and bulk entry
- **[Expense Tracking](EXPENSE_TRACKING.md)** — Track business expenses
- **[Payment Tracking](PAYMENT_TRACKING.md)** — Track invoice payments
- **[Budget Alerts & Forecasting](BUDGET_ALERTS_AND_FORECASTING.md)** — Monitor project budgets
- **[Command Palette](COMMAND_PALETTE_USAGE.md)** — Keyboard shortcuts and quick actions
- **[Bulk Time Entry](BULK_TIME_ENTRY_README.md)** — Create multiple time entries at once
- **[Time Entry Templates](TIME_ENTRY_TEMPLATES.md)** — Reusable time entry templates
- **[Weekly Time Goals](WEEKLY_TIME_GOALS.md)** — Set and track weekly hour targets
- **[Break Time for timers and manual entries](BREAK_TIME_FEATURE.md)** — Pause timers (break time) and optional break field on manual entries (Issue #561)
- **[Time Rounding](TIME_ROUNDING_PREFERENCES.md)** — Configurable time rounding
- **[Role-Based Permissions](ADVANCED_PERMISSIONS.md)** — Granular access control
- **[Subcontractor role and assigned clients](SUBCONTRACTOR_ROLE.md)** — Restrict users to specific clients and projects
See [features/](features/) for additional feature documentation.
---
## 🔧 Administrator Documentation
### Configuration
- **[Docker Compose Setup](admin/configuration/DOCKER_COMPOSE_SETUP.md)** — Docker deployment guide
- **[Docker Public Setup](admin/configuration/DOCKER_PUBLIC_SETUP.md)** — Production deployment
- **[Docker Startup Troubleshooting](admin/configuration/DOCKER_STARTUP_TROUBLESHOOTING.md)** — Fix startup issues
- **[Email Configuration](admin/configuration/EMAIL_CONFIGURATION.md)** — Email setup
- **[OIDC Setup](admin/configuration/OIDC_SETUP.md)** — OIDC/SSO authentication setup
- **[LDAP Setup](admin/configuration/LDAP_SETUP.md)** — LDAP directory authentication (`AUTH_METHOD=ldap` or `all`)
- **[Support visibility](admin/configuration/SUPPORT_VISIBILITY.md)** — Hide donate/support UI with a purchased key; [purchase key](https://timetracker.drytrix.com/support.html)
### Deployment
- **[Version Management](admin/deployment/VERSION_MANAGEMENT.md)** — Managing versions
- **[Release Process](admin/deployment/RELEASE_PROCESS.md)** — Release workflow
- **[Official Builds](admin/deployment/OFFICIAL_BUILDS.md)** — Official build information
### Security
- **[Security Documentation](admin/security/)** — Security guides and configuration
- **[CSRF Configuration](admin/security/CSRF_CONFIGURATION.md)** — CSRF token setup
- **[CSRF Troubleshooting](admin/security/CSRF_TROUBLESHOOTING.md)** — Fix CSRF errors
- **[HTTPS Setup (Auto)](admin/security/README_HTTPS_AUTO.md)** — Automatic HTTPS
- **[HTTPS Setup (mkcert)](admin/security/README_HTTPS.md)** — Manual HTTPS with mkcert
- See [admin/security/](admin/security/) for all security-related documentation
### Monitoring
- **[Monitoring Documentation](admin/monitoring/)** — Monitoring and analytics setup
- See [admin/monitoring/](admin/monitoring/) for telemetry and analytics guides
**📖 See [admin/README.md](admin/README.md) for complete administrator documentation**
---
## 👨‍💻 Developer Documentation
### Terminology
Use consistent terms in code, API, and user-facing copy: **time entry** / **time entries**, **client**, **project**, **task**, **invoice**. See [Product/UX Audit](PRODUCT_UX_AUDIT.md) for full context and naming recommendations.
### Getting Started
- **[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
- **[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
### Development Setup
- **[Local Testing with SQLite](development/LOCAL_TESTING_WITH_SQLITE.md)** — Quick local testing setup
- **[Local Development with Analytics](development/LOCAL_DEVELOPMENT_WITH_ANALYTICS.md)** — Development setup with analytics
### Testing
- **[Testing Quick Reference](TESTING_QUICK_REFERENCE.md)** — Testing overview
- **[Testing Coverage Guide](TESTING_COVERAGE_GUIDE.md)** — Coverage documentation
- See [testing/](testing/) for additional testing documentation
### CI/CD
- **[CI/CD Documentation](cicd/)** — Continuous integration and deployment
- **[Documentation](cicd/CI_CD_DOCUMENTATION.md)** — CI/CD overview
- **[Quick Start](cicd/CI_CD_QUICK_START.md)** — Get started with CI/CD
- **[Implementation Summary](cicd/CI_CD_IMPLEMENTATION_SUMMARY.md)** — What was implemented
- **[GitHub Actions Setup](cicd/GITHUB_ACTIONS_SETUP.md)** — Configure GitHub Actions
### Technical Documentation
- **[Solution Guide](SOLUTION_GUIDE.md)** — Technical solutions and patterns
- **[Frontend Quality Gates](development/FRONTEND_QUALITY_GATES.md)** — Accessibility, performance, and modernization (web, desktop, mobile)
- **[Database Migrations](../migrations/README.md)** — Database schema management
- **[Implementation Notes](implementation-notes/)** — Development notes and summaries
### Product & Roadmap
- **[Competitive Analysis](competitive-analysis/README.md)** — Feature gap analysis and phase PRDs
**📖 See [development/README.md](development/README.md) for complete developer documentation**
---
## 📚 API Documentation
- **[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
- **[API Enhancements](api/API_ENHANCEMENTS.md)** — Recent API improvements
**📖 See [api/README.md](api/README.md) for complete API documentation**
### Quick API Examples
**Authentication:**
```bash
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
https://your-domain.com/api/v1/projects
```
**Create Time Entry:**
```bash
curl -X POST -H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"project_id": 1, "start_time": "2025-01-27T09:00:00", "end_time": "2025-01-27T17:00:00"}' \
https://your-domain.com/api/v1/time-entries
```
See [REST API Documentation](api/REST_API.md) for complete examples and endpoint details.
---
## 🚀 Installation & Deployment
### Quick Start
1. **[Installation Guide](../INSTALLATION.md)** — Step-by-step installation (root)
2. **[Getting Started Guide](GETTING_STARTED.md)** — Complete beginner tutorial
3. **[Docker Compose Setup](admin/configuration/DOCKER_COMPOSE_SETUP.md)** — Recommended deployment method
4. **[Requirements](REQUIREMENTS.md)** — System requirements
### Database & Migrations
- **[Database Migrations](../migrations/README.md)** — Database schema management with Flask-Migrate
- **[Migration Guide](../migrations/MIGRATION_GUIDE.md)** — Migrate existing databases
- **[Enhanced Database Startup](ENHANCED_DATABASE_STARTUP.md)** — Automatic database initialization
- **[Database Startup Fix](DATABASE_STARTUP_FIX_README.md)** — Database connection troubleshooting
- **[Docker Connection Troubleshooting](../docker/TROUBLESHOOTING_DB_CONNECTION.md)** — Database connection in Docker
---
## 🛠️ Troubleshooting
### Common Issues
- **[Docker Startup Troubleshooting](admin/configuration/DOCKER_STARTUP_TROUBLESHOOTING.md)** — Docker won't start
- **[Database Connection Issues](../docker/TROUBLESHOOTING_DB_CONNECTION.md)** — Can't connect to database
- **[PDF Generation Issues](PDF_GENERATION_TROUBLESHOOTING.md)** — PDFs not generating
- **[Solution Guide](SOLUTION_GUIDE.md)** — General problem solving
- **[Troubleshooting Transaction Error](TROUBLESHOOTING_TRANSACTION_ERROR.md)** — Transaction issues
### Quick Fixes
- **Port conflicts**: Change `PORT=8081` in docker-compose command
- **Database issues**: Run `docker-compose down -v && docker-compose up -d`
- **Permission errors**: Check file ownership with `chown -R $USER:$USER .`
- **Migration failures**: See [Database Migrations](../migrations/README.md)
---
## 📝 Additional Resources
### Implementation Notes
Recent improvements and changes are documented in [implementation-notes/](implementation-notes/):
- Layout & UX improvements
- Feature implementations
- Bug fixes and improvements
- Architecture changes
### Reports & Analysis
Analysis reports and summaries are available in [reports/](reports/):
- Bugfix summaries
- Audit reports
- Translation analysis
### Feature-Specific Documentation
Detailed feature documentation is available in [features/](features/):
- Feature guides
- Quick start guides
- Implementation status
### User Guides
Additional user guides are available in [user-guides/](user-guides/):
- Step-by-step guides
- Tips and tricks
- Best practices
---
## 🔍 Documentation by Role
### For New Users
1. Start with **[Main README](../README.md)** for product overview
2. Follow **[Getting Started Guide](GETTING_STARTED.md)** for installation
3. Review **[Requirements](REQUIREMENTS.md)** to check system compatibility
4. Explore **[Feature Documentation](#-feature-documentation)** to learn features
### For Administrators
1. Follow **[Docker Compose Setup](admin/configuration/DOCKER_COMPOSE_SETUP.md)** for deployment
2. Review **[Version Management](admin/deployment/VERSION_MANAGEMENT.md)** for updates
3. Set up **[Email Configuration](admin/configuration/EMAIL_CONFIGURATION.md)** if needed
4. Configure **[OIDC/SSO](admin/configuration/OIDC_SETUP.md)** for authentication
5. See **[admin/README.md](admin/README.md)** for complete admin documentation
### For Developers
1. Read **[Contributing Guidelines](development/CONTRIBUTING.md)** before making changes
2. Review **[Project Structure](development/PROJECT_STRUCTURE.md)** to understand codebase
3. Check **[Solution Guide](SOLUTION_GUIDE.md)** for technical patterns
4. Use **[Local Testing with SQLite](development/LOCAL_TESTING_WITH_SQLITE.md)** for development
5. See **[development/README.md](development/README.md)** for complete developer documentation
### For Troubleshooting
1. Check **[Docker Startup Troubleshooting](admin/configuration/DOCKER_STARTUP_TROUBLESHOOTING.md)**
2. Review **[Database Connection Issues](../docker/TROUBLESHOOTING_DB_CONNECTION.md)**
3. Consult **[Solution Guide](SOLUTION_GUIDE.md)** for common problems
4. Check specific feature documentation if issue is feature-related
---
## 📁 Documentation Structure
```
docs/
├── README.md # This file - documentation index
├── GETTING_STARTED.md # Beginner tutorial
├── REQUIREMENTS.md # System requirements
├── FEATURES_COMPLETE.md # Complete features list
│
├── guides/ # User-facing guides
│ ├── DEPLOYMENT_GUIDE.md
│ ├── QUICK_START_GUIDE.md
│ └── ...
│
├── admin/ # Administrator documentation
│ ├── configuration/ # Configuration guides
│ ├── deployment/ # Deployment guides
│ ├── security/ # Security documentation
│ └── monitoring/ # Monitoring & analytics
│
├── development/ # Developer documentation
│ ├── CONTRIBUTING.md
│ ├── CODE_OF_CONDUCT.md
│ ├── PROJECT_STRUCTURE.md
│ └── ...
│
├── api/ # API documentation
│ ├── REST_API.md
│ ├── API_TOKEN_SCOPES.md
│ └── ...
│
├── features/ # Feature-specific guides
│ └── ...
│
├── implementation-notes/ # Development notes
│ └── ...
│
├── testing/ # Testing documentation
│ └── ...
│
├── reports/ # Reports & analysis
│ └── ...
│
├── user-guides/ # Additional user guides
│ └── ...
│
└── cicd/ # CI/CD documentation
└── ...
```
---
## 📋 Documentation Audit
A summary of doc accuracy, outdated content, gaps, and contradictions is in [DOCS_AUDIT.md](DOCS_AUDIT.md). Use it when updating or reorganizing docs.
---
## 🤝 Contributing to Documentation
Found an error? Want to improve the docs?
1. Check the **[Contributing Guidelines](development/CONTRIBUTING.md)**
2. Make your changes to the relevant documentation file
3. Test that all links work correctly
4. Submit a pull request with a clear description
Good documentation helps everyone! 📚
---
## 💡 Tips for Using This Documentation
- **Use the search function** in your browser (Ctrl/Cmd + F) to find specific topics
- **Follow links** to related documentation for deeper understanding
- **Start with Quick Links** at the top if you're in a hurry
- **Browse by role** using the role-based sections above
- **Check Implementation Notes** for recent changes and improvements
---
<div align="center">
**Need help?** [Open an issue](https://github.com/drytrix/TimeTracker/issues) or check the [troubleshooting section](#-troubleshooting)
**Want to contribute?** See our [Contributing Guidelines](development/CONTRIBUTING.md)
---
[⬆ Back to Top](#timetracker-documentation)
</div>
Reference in New Issue View Git Blame Copy Permalink