Clockora Quickstart, as shipped in the download

CLOCKORA — QUICKSTART
=====================

Self-hosted staff timesheet & time tracker — PHP + MySQL/SQLite. Records hours
worked only (no invoicing, no billing rates, no payments, no payroll).


REQUIREMENTS
------------
  - PHP 8.0+ with extensions: pdo, pdo_sqlite (or pdo_mysql)
  - MySQL 5.7+ / MariaDB 10+ OR SQLite 3 (SQLite requires no extra setup)
  - A web server (Apache with mod_rewrite, or Nginx with try_files)
  - No Composer packages, no API keys, no external services.


SHARED HOSTING / CPANEL (RECOMMENDED FOR MOST BUYERS)
------------------------------------------------------
1. Upload the contents of the `app/` folder to your web root (e.g. public_html/)
   or a subdirectory (e.g. public_html/clockora/).

2. Make sure this directory is writable by PHP:
     data/

   Via cPanel File Manager: right-click -> Permissions -> set to 755 or 775.

3. Visit https://yourdomain.com/install/ in your browser.

4. Fill in the installer:
     - Database: choose MySQL (fill in host/name/user/pass) or SQLite (no setup)
     - Business name, timezone
     - Your admin name, email + password

5. The installer writes config.php, adds a couple of starter projects, and
   redirects you to the login page.

6. Log in, then:
     - Under Settings, set which weekday the timesheet week starts on and the
       default weekly overtime threshold (whole hours, e.g. 40, or H:MM).
     - Add your employees (Employees > New), each with a role and (optionally)
       their own weekly-hours target.
     - Add projects under Setup > Projects (optional — time can be logged with
       no project).
     - Log time from "Log time"; submit and approve from Time entries or the
       Timesheet page.


TRY IT WITH DEMO DATA FIRST
---------------------------
  - On the dashboard, click "Load demo data" for a sample studio team, projects,
    and a full week of time entries (a mix of clock and manual entries, a
    cross-midnight night shift, and one employee flagged over the weekly
    threshold). Then "Reset all data" when done.
  - Or from the command line:  php bin/demo.php
      (login: admin@clockora.app / admin123)


VPS / SELF-HOSTED (APACHE)
--------------------------
  <VirtualHost *:80>
    DocumentRoot /var/www/clockora/app
    <Directory /var/www/clockora/app>
      AllowOverride All
      Require all granted
    </Directory>
  </VirtualHost>


NGINX
-----
  location / { try_files $uri /index.php?$query_string; }
  location ~ /\.(demo-mode) { deny all; }
  location ~* \.(sqlite)$   { deny all; }
  location ~ ^/(src|data|bin|tests|controllers)/ { deny all; }
  location = /config.php    { deny all; }


DOCKER (QUICK TEST)
-------------------
  docker run --rm -p 8080:8080 \
    -v "$(pwd)/app:/var/www/html" \
    -w /var/www/html \
    php:8.3-cli \
    php -S 0.0.0.0:8080 router.php

  Then visit http://localhost:8080/install/


LOGGING TIME
------------
  - Clock times: enter a Start and End time as HH:MM (24-hour). If the End time
    is earlier than the Start, the entry crosses midnight (ends the next day),
    e.g. 22:00 -> 06:00 = 8 hours.
  - Manual duration: enter H:MM (e.g. 7:30) or whole minutes (e.g. 450). Stored
    as exact integer minutes.
  - One employee cannot have two clock entries that overlap in time on a day;
    back-to-back entries (one ends where the next starts) are fine.


TIMESHEET, APPROVALS & OVERTIME
-------------------------------
  - The Timesheet page shows a week (with prev/next) or a custom date range,
    with totals per employee and per project — exact to the minute.
  - Each entry moves draft -> submitted -> approved / rejected, recording the
    approver and the time. Submit/approve one entry, or a whole employee's
    period in bulk from the Timesheet.
  - Overtime is a FLAG: when an employee's weekly hours exceed their threshold
    (their own target or the business default), the week is flagged. It is never
    a pay or money figure.


REPORTS & EXPORTS
-----------------
  - Time entries > Export CSV: safe to open in Excel / Google Sheets
    (formula-injection hardened). Includes an exact Minutes column and an H:MM
    Duration.
  - Employee page > Timesheet PDF: a genuine, dependency-free PDF with the
    employee's entries for the period, totals by project, the period total, and
    the overtime flag.


POST-INSTALL SECURITY CHECKLIST
--------------------------------
  [ ] config.php is protected (the .htaccess does this automatically)
  [ ] data/ is not web-accessible (.htaccess blocks it automatically)
  [ ] Use HTTPS in production
  [ ] Keep PHP updated


NOTES
-----
  * Worked time is stored as integer minutes (never a float); period totals
    reconcile exactly.
  * Date math is UTC-anchored, so week bucketing and cross-midnight overlap
    detection stay correct across daylight-saving changes.
  * Clockora records hours only. It is not invoicing and not payroll: it computes
    no money, applies no billing rates, and processes no payments.