# WES Project Tool — PHP 8.2 / cPanel deployment

## What is included

The existing React interface is compiled into static JavaScript and CSS. A new PHP 8.2 backend provides login, database records, permissions, invitations, uploads, and downloads. The VPS does **not** need Node.js or Composer to run this package.

The installer imports **43,767 saved records in 56 collections**, including **6,217 cables**, and verifies **456 attachments**. This is a snapshot of the data imported from your supplied exports, plus changes saved in your local application before packaging. It is not a continuing connection to the original live application. Later changes require another migration.

Your exported user profiles and groups are included. Existing account passwords are not in the exports. You choose a new administrator login during installation, then invite other users and assign their groups.

## 1. Prepare the hosting account

Use a dedicated domain or subdomain for this application. Set up HTTPS/AutoSSL before installation. A subfolder URL such as `example.com/wes` is not supported by this package.

In **cPanel → MultiPHP Manager**, select **PHP 8.2** for this domain and apply it. Enable PHP-FPM if available. Ask the hosting administrator to confirm these PHP extensions: **PDO, pdo_mysql, fileinfo, json, filter**. `curl` is only needed for optional AI integration. MySQL/MariaDB must support InnoDB.

In **MultiPHP INI Editor**, use:

| Setting | Value |
| --- | --- |
| memory_limit | 512M |
| upload_max_filesize | 50M |
| post_max_size | 64M |
| max_execution_time | 180 |
| display_errors | Off |
| log_errors | On |

The package also includes `.user.ini` with these settings. The server administrator may need to adjust Apache/PHP-FPM request limits for long imports.

## 2. Upload and extract the ZIP

In cPanel File Manager, enable **Show Hidden Files**. Upload the ZIP into your account's home directory, **outside the public web directory**, and extract it. The ZIP contains a `wes-php-cpanel` folder. Use this layout, replacing `CPANELUSER` with your actual account name:

```text
/home/CPANELUSER/wes-php-cpanel/
  public_html/       ← domain document root
    .htaccess
    .user.ini
    index.php
    install.php
    assets/
  wes-private/       ← keep outside every public document root
    config.example.php
    seed/
    uploads/
  frontend-source/   ← development source, not needed for hosting
  DEPLOYMENT.md
  VALIDATION.md
```

Set your domain's document root to `/home/CPANELUSER/wes-php-cpanel/public_html`.

If cPanel restricts document roots to the account's original `public_html` directory, have the WHM administrator configure the document root shown above. Do not work around that restriction by putting `wes-private` inside another site's public directory. The PHP entry points expect `wes-private` immediately beside the application's `public_html` folder.

## 3. Create a database

Use **cPanel → MySQL Databases / Database Wizard** to create a new, empty database and a database user. Add that user to this database with all privileges. Note the complete database and user names, including cPanel's account prefix.

## 4. Configure the application

Copy `wes-private/config.example.php` to `wes-private/config.php`, then edit:

- `app_url`: the exact HTTPS domain, for example `https://projects.example.com`, with no subfolder.
- `install_key`: a new random secret of at least 32 characters. Save it for the next step.
- `db.name`, `db.user`, `db.password`: your new database details.
- `db.host`: normally `localhost`; use the host supplied by your provider.

Keep `db.driver` as `mysql`. Do not put database credentials in the frontend files. The ZIP contains no working administrator password or production database credentials.

PHP must be able to create/write `wes-private/storage` and write `wes-private/uploads`. With cPanel PHP-FPM running as your account, owner-writable directories and owner-readable files are sufficient; do not use permission `777`. Keep the private configuration readable only by the account/PHP process. Preserve the supplied `.htaccess` files.

## 5. Run the installer once

Open `https://YOUR-DOMAIN/install.php`. Enter your setup key, administrator email, and a new password of **12–72 bytes**, then confirm the password and install.

The installer checks data and attachment checksums, imports the records into MySQL, changes saved local attachment links to your domain, and creates your administrator account. Wait for the success page. It locks itself after installation; you may then remove the public `install.php` file.

Do not import these seed files repeatedly into a working database. The database becomes the active data store after setup; the JSON seed files remain an initial snapshot.

## 6. Verify on the VPS before switching users over

1. Open `/api/health`: it should return `ok: true` and `app: wes-php`.
2. Log in with the administrator you just created.
3. Confirm the dashboard shows **6,217 cables**, **1,782 EX records**, **1,376 MDI documents**, and **3,113 IO signals**.
4. Open a saved attachment, upload a small test file, and verify a reversible record edit.
5. Invite one user through User Management, assign a group, and check that the intended pages and actions are available. Existing imported profiles are reused when their email matches.
6. Log out and confirm private downloads require login.

The package has been tested locally on PHP 8.2.33 using SQLite/PDO. **The MySQL driver, Apache rewrite rules, and your AlmaLinux/cPanel configuration still need the server-side checks above.** This package has not been deployed to your VPS.

## Optional services and limitations

- **Email:** disabled initially. Invitations return an activation link an administrator can copy and send. Automatic invitation and password-reset emails need working PHP `mail()` delivery; configure `mail_from` and test delivery before setting `mail_enabled` to `true`.
- **Registration:** invitation-only by default. The registration page explains this if used. Enable self-registration only after email delivery works.
- **AI:** disabled until an API key/provider/model is configured in the private configuration. This PHP adapter supports text prompts; AI processing of attached documents requires additional integration. Google sign-in is not included.
- **Performance:** collection filters currently load that collection into PHP memory. The supplied data passes local checks, but concurrent-user capacity has not been load-tested.
- **SQLite alternative:** if your provider supports `pdo_sqlite`, `db.driver` may be `sqlite` and the private `sqlite_path` can retain its example value. Choose the database before first installation.

## Backups and maintenance

Back up the database, `wes-private/uploads`, `wes-private/config.php`, and `wes-private/storage` together. Use a consistent database backup through cPanel/phpMyAdmin or your provider's backup system. A seed-file copy alone does not back up edits made after installation. Keep backups outside public web folders.

If installing fails, check cPanel's PHP error log for missing extensions, incorrect database credentials, or unwritable private storage. A 404 on routes usually indicates a wrong document root or missing `.htaccess`/mod_rewrite. A 413 upload error means a PHP or web-server request limit is too small. A timeout during setup may require the host to raise its request limit or run the included `wes-private/install-cli.php` with `WES_INSTALL_KEY`, `WES_ADMIN_EMAIL`, and `WES_ADMIN_PASSWORD` environment variables. Use PHP 8.2 for that command and keep credentials out of shell history.

For future frontend development, `frontend-source` includes the editable React project. On a development computer, run `npm ci` and `npm run build`; copy the resulting `dist` contents into `public_html`, preserving the PHP files and `.htaccess`. Node.js is needed only for that build step.

Official cPanel references: [MultiPHP Manager](https://docs.cpanel.net/cpanel/software/multiphp-manager-for-cpanel/) and [MultiPHP INI Editor](https://docs.cpanel.net/cpanel/software/multiphp-ini-editor-for-cpanel/).