initial

README.md

@@ -0,0 +1,52 @@
+# Timekeeper (Synology NAS Docker)
+
+A lightweight timekeeping utility for importing Excel time clock reports, auto-generating employee timesheets, printing, and viewing monthly/yearly stats. Runs on port **5070** with a **Postgres** backend.
+
+## Features
+- Upload your “Final Time Clock Report” Excel and import entries.
+- Per-employee timesheet in a layout similar to your template screenshot with weekly summaries and totals (Regular, PTO, Holiday, Bereavement, OT, Paid Total).
+- Print-ready timesheet (browser print / Save as PDF).
+- Yearly overview with monthly breakdown and averages.
+- Default login: **Admin / 1Senior!** (please change).
+
+## Run on Synology
+1. Copy this folder to your NAS, e.g. `/volume1/docker/timekeeper`.
+2. Open Container Manager (Docker) → Projects → Create.
+3. Select this folder, confirm docker-compose.yml, and start.
+4. Visit `http://<NAS-IP>:5070`.
+5. Login with Admin / 1Senior! → Import Excel → View Employees → Timesheet/Overview.
+
+## Configuration
+- Port: 5070 (mapped in compose).
+- Environment:
+  - `SECRET_KEY` – set to a strong random string.
+  - `PAY_PERIOD_TYPE` – `BIWEEKLY` (default), `WEEKLY`, or `SEMI_MONTHLY`.
+  - `PAY_PERIOD_START_WEEKDAY` – start of week (0=Mon ... 6=Sun) for weekly/biweekly grouping.
+
+## Excel Import
+The importer detects a sheet whose name contains “Final Time Clock Report” (or first sheet otherwise). Expected columns by name (case-sensitive):
+
+- Employee Name
+- Date
+- Clock In Time
+- Clock Out Time
+- Hours Worked Minus Break Hours
+- Break Hours
+- Paid Hours
+- (Optional) PTO Type, PTO Hours, Holiday Hours, Bereavement Hours, Schedule Group
+
+If your column names differ, update `COLUMN_ALIASES` in `app/process_excel.py`.
+
+## Security
+- Immediately change the Admin password after first login.
+- Restrict port exposure to your LAN/VPN.
+- Consider enabling HTTPS behind Synology’s reverse proxy.
+
+## Backups
+- Postgres data persists in `db_data` volume.
+- Uploaded Excel files are stored in the `uploads` volume.
+
+## Roadmap ideas
+- PDF export via WeasyPrint/wkhtmltopdf.
+- Role-based accounts and user management.
+- Overtime rules customization; per-employee schedules; PTO imports.