mirror of https://github.com/DRYTRIX/TimeTracker.git synced 2026-01-16 01:00:16 -06:00

Files

Dries Peeters 29f7186ee8 docs: Reorganize documentation structure for better navigation

Complete reorganization of project documentation to improve discoverability,
navigation, and maintainability. All documentation has been restructured into
a clear, role-based hierarchy.

## Major Changes

### New Directory Structure
- Created `docs/api/` for API documentation
- Created `docs/admin/` with subdirectories:
  - `admin/configuration/` - Configuration guides
  - `admin/deployment/` - Deployment guides
  - `admin/security/` - Security documentation
  - `admin/monitoring/` - Monitoring and analytics
- Created `docs/development/` for developer documentation
- Created `docs/guides/` for user-facing guides
- Created `docs/reports/` for analysis reports and summaries
- Created `docs/changelog/` for detailed changelog entries (ready for future use)

### File Organization

#### Moved from Root Directory (40+ files)
- Implementation notes → `docs/implementation-notes/`
- Test reports → `docs/testing/`
- Analysis reports → `docs/reports/`
- User guides → `docs/guides/`

#### Reorganized within docs/
- API documentation → `docs/api/`
- Administrator documentation → `docs/admin/` (with subdirectories)
- Developer documentation → `docs/development/`
- Security documentation → `docs/admin/security/`
- Telemetry documentation → `docs/admin/monitoring/`

### Documentation Updates

#### docs/README.md
- Complete rewrite with improved navigation
- Added visual documentation map
- Organized by role (Users, Administrators, Developers)
- Better categorization and quick links
- Updated all internal links to new structure

#### README.md (root)
- Updated all documentation links to reflect new structure
- Fixed 8 broken links

#### app/templates/main/help.html
- Enhanced "Where can I get additional help?" section
- Added links to new documentation structure
- Added documentation index link
- Added admin documentation link for administrators
- Improved footer with organized documentation links
- Added "Complete Documentation" section with role-based links

### New Index Files
- Created README.md files for all new directories:
  - `docs/api/README.md`
  - `docs/guides/README.md`
  - `docs/reports/README.md`
  - `docs/development/README.md`
  - `docs/admin/README.md`

### Cleanup
- Removed empty `docs/security/` directory (moved to `admin/security/`)
- Removed empty `docs/telemetry/` directory (moved to `admin/monitoring/`)
- Root directory now only contains: README.md, CHANGELOG.md, LICENSE

## Results

**Before:**
- 45+ markdown files cluttering root directory
- Documentation scattered across root and docs/
- Difficult to find relevant documentation
- No clear organization structure

**After:**
- 3 files in root directory (README, CHANGELOG, LICENSE)
- Clear directory structure organized by purpose and audience
- Easy navigation with role-based organization
- All documentation properly categorized
- Improved discoverability

## Benefits

1. Better Organization - Documentation grouped by purpose and audience
2. Easier Navigation - Role-based sections (Users, Admins, Developers)
3. Improved Discoverability - Clear structure with README files in each directory
4. Cleaner Root - Only essential files at project root
5. Maintainability - Easier to add and organize new documentation

## Files Changed

- 40+ files moved from root to appropriate docs/ subdirectories
- 15+ files reorganized within docs/
- 3 major documentation files updated (docs/README.md, README.md, help.html)
- 5 new README index files created
- 2 empty directories removed

All internal links have been updated to reflect the new structure.

2025-12-14 07:56:07 +01:00

4.2 KiB

Raw Blame History

🔒 HTTPS Setup for TimeTracker

Quick Start with mkcert

1. Install mkcert

Windows:

choco install mkcert

macOS:

brew install mkcert

Linux:

# See HTTPS_MKCERT_GUIDE.md for detailed instructions

2. Run Setup Script

Windows:

setup-https-mkcert.bat

Linux/Mac:

bash setup-https-mkcert.sh

3. Start with HTTPS

docker-compose -f docker-compose.yml -f docker-compose.https.yml up -d

4. Access Your App

https://localhost
https://192.168.1.100  (your actual IP)

✅ No certificate warnings! ✅ Works with IP addresses! ✅ Secure HTTPS!

What the Script Does

✅ Installs local Certificate Authority (trusted by your browser)
✅ Generates SSL certificates for localhost + your IP
✅ Creates nginx reverse proxy configuration
✅ Creates docker-compose.https.yml
✅ Updates .env with secure HTTPS settings:
- WTF_CSRF_SSL_STRICT=true
- SESSION_COOKIE_SECURE=true
- CSRF_COOKIE_SECURE=true

Benefits

✅ CSRF cookies work correctly with IP addresses
✅ Strict security settings enabled
✅ No more "CSRF token missing or invalid" errors

Secure Communication

✅ All traffic encrypted
✅ Trusted certificates (no warnings)
✅ Modern TLS 1.2/1.3

Easy Management

✅ One command setup
✅ Valid for 10 years
✅ No renewal needed

Access from Other Devices

To access from your phone, tablet, or other computers without warnings:

Find CA location:
```
mkcert -CAROOT
```
Copy rootCA.pem to device
Install certificate on device:
- iOS: Settings → Profile → Install
- Android: Settings → Security → Install certificate
- See HTTPS_MKCERT_GUIDE.md for details
Access from device:
```
https://192.168.1.100
```

File Structure

After running the setup:

TimeTracker/
├── nginx/
│   ├── conf.d/
│   │   └── https.conf          # nginx HTTPS config
│   └── ssl/
│       ├── cert.pem            # SSL certificate (gitignored)
│       └── key.pem             # Private key (gitignored)
├── docker-compose.yml          # Base configuration
├── docker-compose.https.yml    # HTTPS override (auto-generated)
├── setup-https-mkcert.sh      # Linux/Mac setup script
├── setup-https-mkcert.bat     # Windows setup script
└── .env                        # Updated with HTTPS settings

Verification

Check Certificate

Navigate to https://localhost
Click padlock icon in browser
View certificate → Should show "mkcert" with no warnings

Check Cookies

Open DevTools (F12) → Application → Cookies
Verify session and XSRF-TOKEN cookies have Secure flag

Test Application

Login
Create a project
Log time
Should work without any CSRF errors ✅

Stopping HTTPS

To return to HTTP:

# Stop HTTPS setup
docker-compose -f docker-compose.yml -f docker-compose.https.yml down

# Start normally
docker-compose up -d

Troubleshooting

Certificate Warning Appears

# Reinstall CA
mkcert -install

# Restart browser completely

nginx Won't Start

# Check if port is in use
netstat -ano | findstr :443     # Windows
lsof -i :443                    # Linux/Mac

# Check logs
docker-compose logs nginx

IP Address Not Working

# Regenerate with correct IP
mkcert -key-file nginx/ssl/key.pem -cert-file nginx/ssl/cert.pem \
  localhost 127.0.0.1 ::1 YOUR_ACTUAL_IP *.local

# Restart
docker-compose restart nginx

Complete Documentation

For detailed instructions, see:

HTTPS_MKCERT_GUIDE.md - Complete mkcert guide
CSRF_IP_ACCESS_FIX.md - CSRF troubleshooting

Summary

One command to HTTPS:

bash setup-https-mkcert.sh
docker-compose -f docker-compose.yml -f docker-compose.https.yml up -d

Result: ✅ Secure HTTPS
✅ No certificate warnings
✅ Works with IP addresses
✅ CSRF cookies work perfectly
✅ Production-grade security settings

Enjoy secure TimeTracker! 🔒

4.2 KiB Raw Blame History