65 lines
3.2 KiB
Markdown
65 lines
3.2 KiB
Markdown
# JOBcard & Client Management System
|
|
|
|
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
|
|
|
|
- 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
|
|
|
|
## Installation on a standard host
|
|
|
|
1. Create a MariaDB/MySQL database and database user.
|
|
2. Upload the repository outside the public web root.
|
|
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
|
|
php bin/install.php
|
|
```
|
|
|
|
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` and permit `AllowOverride FileInfo` (or configure equivalent virtual-host rewrite rules); 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.
|
|
- The `public/` directory is mandatory as the virtual server document root. Never configure the repository root as the document root; `public/.htaccess` cannot protect files located in parent directories.
|
|
- 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
|
|
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
|
|
|
|
- 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.
|