refactor: support portable PHP hosting without Docker

README.md

@@ -1,36 +1,64 @@
 # JOBcard & Client Management System
 
-Greenfield PHP/MariaDB implementation of the approved JOBcard scope.
-
-## Current increment
-
-Verified foundation and early domain slices: Docker runtime, MariaDB schema, secure session authentication, environment-based Administrator bootstrap, role-aware navigation/dashboard, CSRF protection, password hashing, audit events, client/contact validation, client search/detail views, jobcard creation/listing, jobcard references and status rules, time-entry validation/aggregation, SLA calculations/classification, and safe internal versus client-facing reporting contracts.
+Portable PHP/MariaDB implementation of the JOBcard & Client Management System. The application does not require Docker and is designed to run on shared hosting, Virtualmin, cPanel, or a conventional PHP-FPM/Apache/Nginx server.
 
 ## Requirements
 
-- Docker Engine with Compose v2
-- A `.env` file copied from `.env.example` with unique values filled in
+- PHP 8.2+ (PHP 8.4 is recommended)
+- MariaDB 10.6+ or MySQL 8+
+- PHP extensions: `pdo_mysql`, `mbstring`, `openssl`, `json`, `fileinfo`
+- Apache with `mod_rewrite`, or Nginx with an equivalent front-controller rule
+- CLI PHP access for the initial database installation
 
-## Run locally
+## Installation on a standard host
+
+1. Create a MariaDB/MySQL database and database user.
+2. Upload the repository outside the public web root where possible.
+3. Set the virtual host/document root to the `public/` directory.
+4. Copy `.env.example` to `.env` and replace every placeholder with production values.
+5. Restrict `.env` permissions, for example `chmod 600 .env`.
+6. Install the schema and initial Administrator account:
 
 ```bash
-cp .env.example .env
-# Replace every placeholder in .env with unique local values.
-docker compose up --build
+php bin/install.php
 ```
 
-Open http://localhost:8082. The first application boot creates the Administrator user from `ADMIN_EMAIL` and `ADMIN_PASSWORD`; the password is hashed with PHP's password API and is never stored in configuration or SQL.
+The installer must be run once against a new database. It creates the schema and bootstraps the Administrator using `ADMIN_EMAIL` and `ADMIN_PASSWORD`; the password is hashed with PHP's password API.
+
+7. Visit the domain over HTTPS and sign in.
+
+## Virtualmin setup
+
+- Create a Virtualmin virtual server and MariaDB database/user.
+- Set the virtual server PHP version to PHP 8.2+ and use PHP-FPM.
+- Set the document root to `jobcard-system/public`.
+- Enable Apache `mod_rewrite`; the included `public/.htaccess` routes requests to `public/index.php`.
+- Enable HTTPS with Virtualmin/Let's Encrypt.
+- Run `php bin/install.php` from the application directory using the same PHP version configured for the domain.
+- Keep `.env`, `config/`, `database/`, `bin/` and `tests/` outside the public document root when the Virtualmin layout allows it. If the repository root must be inside the domain, the included rules deny common sensitive file types and the public root remains `public/`.
+- Schedule database and upload backups using the hosting provider's backup system or cron.
+
+## Nginx alternative
+
+Use `public/` as the root and route all non-file requests to `public/index.php`. PHP requests should be passed to the selected PHP-FPM socket. Do not expose the repository root as the web root.
 
 ## Verification
 
 ```bash
-docker compose config
-find app config database public -type f -name '*.php' -print0 | xargs -0 -n1 php -l
+php -v
+php -m | grep -E 'pdo_mysql|mbstring|openssl|json|fileinfo'
+php bin/install.php
+for f in tests/*Test.php tests/smoke.php; do php -d assert.exception=1 "$f"; done
+for f in $(find app config public bin -type f -name '*.php'); do php -l "$f"; done
 ```
 
+## Current increment
+
+The repository currently includes the secure foundation, role/permission schema, client and contact domain validation, client detail/search views, jobcard creation/listing, time/SLA calculations, and safe report data contracts. Remaining scope modules are being implemented incrementally, including complete credential management, technician workflows, exports, attachments, notifications and production UAT.
+
 ## Security notes
 
-- Do not commit `.env` or production credentials.
-- Set `APP_KEY` to a long random value and keep it in a secrets manager in production.
-- Credential vault encryption and the remaining domain modules are scheduled in later phases.
-- The initial schema is delivered as a Docker bootstrap SQL file. Apply it once to a new database; later releases should use versioned migrations.
+- Never commit `.env` or production credentials.
+- Use a long random `APP_KEY` stored outside source control.
+- Use HTTPS in production.
+- The initial bootstrap schema is intended for a new database and should be replaced by versioned migrations in later releases.