# Deployment Notes

These are basic deployment notes for the delivered operating copy. They are intended to let an appointed developer identify the required components and bring up V1 and V2 in a conventional Linux/PHP environment. They do not constitute a migration/support service or a guarantee for a particular hosting stack.

## 1. Deployment model

Deploy V1 and V2 as **two separate web roots** using one standalone RBE database.

Example layout:

```text
/var/www/rbe-v1/    -> contents of application/v1/
/var/www/rbe-v2/    -> contents of application/v2/
```

Recommended hostname pattern:

```text
V1: https://legacy.example-rbe-domain.tld
V2: https://app.example-rbe-domain.tld
Shared cookie domain: .example-rbe-domain.tld
```

The two hosts must share a parent domain if seamless V1 -> V2 session sharing is required.

## 2. Reference Linux stack

The former/current application style is compatible with a conventional Apache/PHP/MariaDB stack. A practical reference for a fresh Ubuntu 24.04 server is:

- Apache 2.4+
- maintained PHP 8.x, PHP 8.0 minimum; PHP 8.3 is a suitable reference
- MariaDB 10.x / MySQL-compatible server
- Composer where dependencies need to be restored
- Node/npm only if the optional MQTT listener is used

Example package installation on Ubuntu/Debian-type systems:

```bash
sudo apt update
sudo apt install -y apache2 mariadb-server \
  php libapache2-mod-php php-mysql php-curl php-mbstring php-xml php-zip php-intl php-bcmath \
  unzip composer
sudo a2enmod rewrite headers
sudo systemctl restart apache2
```

Install Node/npm only if MQTT is required:

```bash
sudo apt install -y nodejs npm
```

## 3. Copy application files

Create destination roots and copy each application separately:

```bash
sudo mkdir -p /var/www/rbe-v1 /var/www/rbe-v2
```

Copy:

```text
application/v1/* -> /var/www/rbe-v1/
application/v2/* -> /var/www/rbe-v2/
```

Remember hidden files such as `.user.ini` when copying.

A conventional ownership/permission starting point is:

```bash
sudo chown -R www-data:www-data /var/www/rbe-v1 /var/www/rbe-v2
sudo find /var/www/rbe-v1 /var/www/rbe-v2 -type d -exec chmod 755 {} \;
sudo find /var/www/rbe-v1 /var/www/rbe-v2 -type f -exec chmod 644 {} \;
```

Adjust where the destination hosting model requires different ownership.

## 4. Create the standalone database

Example only; choose a new database name, database user and strong password for the destination environment:

```bash
sudo mysql
```

```sql
CREATE DATABASE rbe_power CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'rbe_app'@'localhost' IDENTIFIED BY 'REPLACE_WITH_STRONG_PASSWORD';
GRANT ALL PRIVILEGES ON rbe_power.* TO 'rbe_app'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```

For RC1 validation import:

```bash
mysql -u rbe_app -p rbe_power < database/rbe_handover_RC1_VALIDATION.sql
```

The final delivery will replace the RC1 validation SQL with the final full RBE database export.

### Import note: combined-meter view

The RC1 SQL contains `vw_meters_combined` as `SQL SECURITY INVOKER` and does not carry a former-server `root@localhost` DEFINER. This is intentional for portability.

## 5. Configure V1 and V2

Central files:

```text
V1: application/v1/config/app.php
V2: application/v2/core/config.php
```

Set at minimum:

```text
RBE_DB_HOST
RBE_DB_NAME
RBE_DB_USER
RBE_DB_PASS
RBE_V1_BASE_URL
RBE_V2_BASE_URL
```

Both application versions must point to the same standalone RBE database.

The values may be supplied by environment variables, or the `CHANGE_ME_*` fallback values in the central config files may be replaced in the destination copy.

Do not place production credentials in publicly accessible documentation.

## 6. Configure shared V1/V2 sessions

Both application roots contain `.user.ini` with the intended PHP session settings. Replace:

```text
.CHANGE_ME_SHARED_PARENT_DOMAIN
```

with the shared parent domain, for example:

```text
.example-rbe-domain.tld
```

For HTTPS production operation keep:

```ini
session.name = "RBESESSID"
session.cookie_path = "/"
session.cookie_secure = 1
session.cookie_httponly = 1
session.cookie_samesite = "Lax"
session.use_strict_mode = 1
```

### If `.user.ini` is not honoured

Some Apache/PHP handlers, including common mod_php configurations, may not apply per-directory `.user.ini` settings. In that case configure equivalent PHP directives at server/virtual-host level for **both** V1 and V2.

Example mod_php directives:

```apache
php_value session.name "RBESESSID"
php_value session.cookie_domain ".example-rbe-domain.tld"
php_value session.cookie_path "/"
php_flag session.cookie_secure On
php_flag session.cookie_httponly On
php_value session.cookie_samesite "Lax"
php_flag session.use_strict_mode On
```

Do not use those `php_value/php_flag` directives with PHP-FPM if the Apache build does not support them; use `.user.ini`, PHP-FPM pool settings or an equivalent supported PHP configuration method instead.

## 7. Configure Apache virtual hosts

Example templates are supplied under:

```text
config/apache/
```

At minimum each host needs its own `ServerName` and `DocumentRoot`. Enable the sites and reload Apache after substituting the destination hostnames/paths.

Example:

```bash
sudo a2ensite rbe-v1.conf rbe-v2.conf
sudo apache2ctl configtest
sudo systemctl reload apache2
```

DNS and SSL/certificate setup remain the responsibility of the destination developer/host.

## 8. Restore dependencies if required

Composer manifests/locks are included in both versions. If `vendor/` is not retained or needs to be rebuilt:

```bash
cd /var/www/rbe-v1
composer install --no-dev --optimize-autoloader

cd /var/www/rbe-v2
composer install --no-dev --optimize-autoloader
```

If MQTT is required:

```bash
cd /var/www/rbe-v1
npm ci --omit=dev
```

Enable only one intended MQTT listener/runtime instance unless the destination design intentionally requires more.

## 9. First application checks before integrations

Before enabling meter-sync crons or entering private API credentials, verify:

1. V1 login page loads.
2. A valid standalone RBE user can authenticate.
3. V1 dashboard loads.
4. `RBE_V2_BASE_URL` bridge opens V2.
5. V2 recognises the same authenticated PHP session.
6. V1 and V2 can read properties/meters from the imported standalone database.
7. Admin user/role management pages load.
8. Password reset/set-password code no longer expects an unrelated member database.

If V1 login works but V2 shows its login page after using the bridge, check the shared `RBESESSID` cookie domain/name/path first.

## 10. Configure integrations after core application passes

Configure RBE's destination credentials only after the core application and database have passed the checks above.

See:

```text
docs/API_AND_FLECTO_NOTES.md
docs/CRON_JOBS.md
```

Manually execute each intended sync script successfully before adding its cron entry.

## 11. Production hardening

Before production use, RBE/the appointed developer should configure as appropriate:

- DNS and HTTPS certificates;
- secure PHP settings;
- database backups;
- filesystem/server backups;
- application/server log rotation;
- firewall/security controls;
- cron monitoring;
- new private API/SMTP/database credentials;
- destination-specific access control.

## 12. Acceptance boundary

Successful installation, migration, testing or production operation on RBE's destination server is not a condition of handover delivery. The destination environment and its operation remain RBE's responsibility.