# cPanel Deployment Guide

## 1. Choose final HTTPS addresses

Decide the final URL of the portal and all three applications before installing. Do not install under a temporary hostname and later move folders without updating central application URLs and cookie scope.

### Preferred: folders on one hostname

Example:

- `/public_html/user-portal`
- `/public_html/staff-compliance`
- `/public_html/store-audit`
- `/public_html/price-labels`

Leave the shared cookie domain blank. The portal uses a host-only `__Host-unified_access` cookie, which provides the strongest browser scope.

### Supported: subdomains of one parent

Example: `users.example.com`, `staff.example.com`, `audit.example.com`, `labels.example.com`.

Use `.example.com` as the shared cookie domain and valid TLS for every subdomain. The portal uses a `__Secure-unified_access` cookie. Do not use this mode when another untrusted application can set cookies on the parent domain.

Different registrable domains cannot share one browser login session.

## 2. Take backups and use staging

For existing applications, first create a staging copy and a coordinated backup of:

- Staff Compliance code, `data/`, policy/training/library document folders and uploads;
- Price Label `storage/app.sqlite` and all `uploads/` folders;
- Store Audit database, `config.php`, `storage/` and `storage/install.lock`;
- the original application code.

After the central portal is installed, include its database and `/home/CPANEL_USER/unified-auth-config.php` in coordinated backups.

## 3. Configure PHP

Use PHP 8.1 or newer. Enable:

- Central portal: PDO MySQL, OpenSSL
- Staff Compliance: JSON, Fileinfo, OpenSSL
- Store Audit: PDO MySQL, GD, Fileinfo, JSON, OpenSSL
- Price Label Maker: PDO SQLite, Fileinfo, OpenSSL

`mbstring` is useful but is not required by the unified login code. Use production error display settings and log errors outside the public web directory.

Recommended Store Audit upload settings are `memory_limit=256M`, `upload_max_filesize=16M`, `post_max_size=24M` and `max_execution_time=120` or greater.

## 4. Upload all four folders

Upload each application folder to its final location. Ensure cPanel extracts hidden files such as `.htaccess`. Do not copy the `.git` directory or any private configuration file into `public_html`.

For upgrades, overlay code without replacing mutable data described in step 2.

## 5. Create the central database

Using cPanel MySQL Databases:

1. Create a dedicated central database.
2. Create a dedicated database user with a strong random password.
3. Grant the user all privileges on only that central database.
4. Record cPanel-prefixed names exactly.

Use a separate Store Audit database/user for the Store Audit business database.

## 6. Install the Unified User Portal

Open the portal `install.php` over HTTPS and enter:

- exact portal HTTPS URL;
- optional shared cookie domain;
- central database host, port, name, user and password;
- exact final HTTPS URL for each application;
- initial Super Administrator identity and password.

The password must contain at least 14 characters and must not be a predictable phrase or include account details.

The installer creates the schema and attempts to write:

`/home/CPANEL_USER/unified-auth-config.php`

The file should normally be mode 0600 and must be outside `public_html`. When automatic home detection is unavailable, define `UNIFIED_AUTH_CONFIG` to an absolute private path or manually place the generated configuration there. Never place it in a publicly served folder.

Sign in immediately and complete authenticator setup. Save the one-time recovery codes offline.

## 7. Review central security and URLs

As Super Administrator:

1. Confirm all four registered URLs are exact and HTTPS.
2. Keep Administrator two-factor authentication required.
3. Review the default 30-minute idle and 12-hour absolute session limits.
4. Keep user-agent session binding enabled unless a tested business requirement conflicts.
5. Create a second tested Super Administrator and securely store its recovery method before production launch.

Changing cookie scope or application URLs revokes sessions. Test sign-in again after such a change.

## 8. Initialise or upgrade each application

### Staff Compliance

- Grant the installer `staff.manage_settings` and Staff Compliance app access.
- Make `data`, assets and all policy/training/library folders writable by PHP.
- Open `setup.php` only to initialise missing business data.

### Store Audit

- Grant `audit.manage_settings` and Store Audit app access.
- For a new install, make `storage/` writable and open `install.php`.
- For an upgrade, preserve `config.php`, database, `storage/` and lock file, then open `upgrade.php`.

### Price Label Maker

- Grant `labels.manage_settings` and Price Label app access.
- Make `storage`, `uploads/backgrounds`, `uploads/data` and `uploads/logo` writable.
- Open `setup.php` for a new business database. Existing SQLite databases are upgraded non-destructively when opened.

Prefer 0750 or 0770 for writable directories. Use 0775 only when the host requires group/other write. Do not use 777.

## 9. Migrate existing identities

Follow `MIGRATION_GUIDE.md`. Run the CLI importer in cPanel Terminal without `--apply`, resolve every conflict, take another coordinated backup, then apply. Keep any sensitive report outside `public_html` and delete it after temporary credentials are delivered or reset.

## 10. Configure users and functions

For every user:

1. Select one fixed account level.
2. Enable only the applications required.
3. Leave function controls at Inherit where the level default is correct.
4. Use explicit Deny for exceptions that must remain blocked after future level-default changes.
5. Use explicit Allow sparingly and only for a complete business function.
6. Configure local manager/branch/workflow assignments inside each application.

An app-level deny wins over all function allows.

## 11. Validate and launch

Complete `ACCEPTANCE_CHECKLIST.md`, including direct-URL denial tests and cross-application logout. Keep the applications restricted until migration and role testing pass.

After launch:

- remove all release ZIPs and private reports from `public_html`;
- preserve `.htaccess` files during future uploads;
- schedule coordinated backups;
- monitor central and application audit logs;
- promptly disable departed users centrally;
- test restoration periodically.

## Official cPanel references

- Database Wizard: https://docs.cpanel.net/cpanel/databases/database-wizard/
- MultiPHP Manager: https://docs.cpanel.net/cpanel/software/multiphp-manager-for-cpanel/
- SSL/TLS Status: https://docs.cpanel.net/cpanel/security/ssl-tls-status/
- File Manager: https://docs.cpanel.net/cpanel/files/file-manager/
- Script and code permission guidance: https://docs.cpanel.net/knowledge-base/general-systems-administration/best-practices-for-code-and-script-permissions/

Your hosting provider can hide or restrict individual cPanel interfaces. In that case, use the equivalent host-provided database, PHP, TLS and file-management controls.