====== Active Homelab Flat-File CMS Cluster Fleet Manual ======
^ Document Reference | TRACK-HVU24K-2026-V2 |
^ Core Platform | Ubuntu Production VM Node (**hvu24k**) |
^ External Gatekeeper | Bare-Metal Nginx SNI Edge Router Proxy |
^ Runtime Engines | Isolated Dual-Socket PHP 8.3 & PHP 8.1 FPM Pipelines |

This manual serves as a production-grade infrastructure deployment record and a comprehensive operational guide for your homelab cluster setup on **hvu24k**. It documents the exact configuration matrix used to successfully orchestrate your flat-file ecosystem, eliminating any future reliance on multi-VPS platforms.

===== 1. Edge Router Wildcard Routing Blueprint =====

Unlike standard web server blocks, Nginx's Layer 4 ''stream {}'' map feature does not natively understand leading-dot shortcuts (''.ffcms.stream'') or classic asterisks (''*.ffcms.stream'') unless the map is explicitly formatted for hostnames. 

When Nginx encountered a leading dot in the map file, it treated it as a literal string instead of a wildcard evaluation, causing it to fail back to your default 1Panel route. To force Nginx's stream map tool to handle wildcard lookups correctly, you must use a leading asterisk format (*) without a leading dot.

==== Configuration File Path: /etc/nginx/passthrough.map (On Edge Router) ====
<code>
# --- FLAT-FILE CMS FLIGHT TRACKER ---
ffcms.stream                  192.168.0.172:443;
*.ffcms.stream                192.168.0.172:443;
</code>

Apply changes by running:
<code>
sudo nginx -t && sudo systemctl reload nginx
</code>

===== 2. Multi-Socket PHP Processing Architecture =====

To achieve optimal performance and strict platform isolation, the fleet is split dynamically into two standalone FastCGI process pools.

==== 🚀 High-Performance PHP 8.3 FPM Socket Lane ====
These modern frameworks utilize advanced Symfony or Laravel core architectures, operating on your fast PHP 8.3 pipeline:
  * **statamic.ffcms.stream** (Fully active on Statamic v6 with its clean Laravel core layout)
  * **grav.ffcms.stream** (Fully active on Grav 2.0 with its integrated Admin dashboard)
  * **kirby.ffcms.stream** (Fully active on Kirby Starterkit, securely hidden behind your **Apache Basic Auth** license gate)
  * **dokuwiki.ffcms.stream** (Fully active modern text wiki engine)
  * **herbie.ffcms.stream** (Fully active Symfony-based Markdown engine)

==== ⚙️ Standard PHP 8.1 FPM Socket Lane ====
These robust engines operate seamlessly under your primary PHP 8.1 web processing layer:
  * **boidcms.ffcms.stream** (Newly launched minimalist engine - Default Login: admin / password)
  * **flatpress.ffcms.stream** (Newly launched stable blogging portal)
  * **htmly.ffcms.stream** (Newly launched Markdown blogging layout)
  * **mecha.ffcms.stream** (Newly launched hyper-minimalist file engine)
  * **mozilo.ffcms.stream** (Newly launched plain-text page manager)
  * **pulse.ffcms.stream** (Fully active clean reinstallation profile)
  * **bludit.ffcms.stream** (Fully active production profile)
  * **getsimple.ffcms.stream** (Fully active with secure asset routing parameters)
  * **typemill.ffcms.stream**
  * **inline.ffcms.stream**
  * **pluck.ffcms.stream**
  * **pluxml.ffcms.stream**
  * **yellow.ffcms.stream** (Datenstrom Yellow framework)
  * **wonder.ffcms.stream**

//Note: **Baun CMS**, **Flextype**, **Typesetter**, **Monstra**, **Batflat**, and **Parvula** have been cleanly unlinked, deleted, and purged to maintain strict system hygiene.//

===== 3. Production Apache VirtualHost Layout Templates =====

==== Type A: Split-Public Directory Pattern (Statamic / Herbie) ====
Used for heavy frameworks that separate core configuration logic from the public web entry hub. This ensures the master app files sit safely outside public reach, while public traffic is funneled exclusively into the ''public'' or ''web'' subfolder.
<code>
<VirtualHost *:80>
     ServerAdmin clytn50@gmail.com
     DocumentRoot /var/www/html/statamic/public/
     ServerName statamic.ffcms.stream
     ServerAlias www.statamic.ffcms.stream

     # 🚀 FORCE PHP 8.3 SOCKET FOR LARAVEL CORE REQUIREMENTS
     <FilesMatch \.php$>
          SetHandler "proxy:unix:/var/run/php/php8.3-fpm.sock|fcgi://localhost"
     </FilesMatch>

     <Directory /var/www/html/statamic/public/>
          Options FollowSymLinks
          AllowOverride All
          Require all granted
     </Directory>

     ErrorLog ${APACHE_LOG_DIR}/statamic_error.log
     CustomLog ${APACHE_LOG_DIR}/statamic_access.log combined
</VirtualHost>
</code>
==== Type B: Location-Based Security Gate Pattern (Kirby CMS Compliance) ====
Used to enforce strict Apache Basic Authentication at the proxy URL request layer before third-party ''.htaccess'' files load or rewrite rules process. This keeps Kirby invisible to public crawlers and fulfills free evaluation tier guidelines.
<code>
<IfModule mod_ssl.c>
<VirtualHost *:443>
     ServerAdmin clytn50@gmail.com
     DocumentRoot /var/www/html/kirby/
     ServerName kirby.ffcms.stream
     ServerAlias www.kirby.ffcms.stream

     # 🚀 ROUTE TRAFFIC TO THE HIGH-PERFORMANCE PHP 8.3 FPM SOCKET
     <FilesMatch \.php$>
          SetHandler "proxy:unix:/var/run/php/php8.3-fpm.sock|fcgi://localhost"
     </FilesMatch>

     <Directory /var/www/html/kirby/>
          Options +FollowSymLinks
          AllowOverride All
          Require all granted
     </Directory>

     # 🔐 FORCE LOCATION AUTHENTICATION GATES PRIOR TO DIRECTORY PROCESSING
     <Location />
          AuthType Basic
          AuthName "Kirby Private Staging Cluster"
          AuthUserFile /etc/apache2/.kirby.htpasswd
          Require valid-user
     </Location>

     ErrorLog ${APACHE_LOG_DIR}/kirby_error.log
     CustomLog ${APACHE_LOG_DIR}/kirby_access.log combined
</VirtualHost>
</IfModule>
</code>

===== 4. Sysadmin Maintenance & Troubleshooting Diagnostic Playbook =====

==== Triggering Standalone Certbot Redirection Mappings ====
To renew or create certificates for a precise subdomain without altering your cluster's broader mappings:
<code>
sudo certbot --apache -d htmly.ffcms.stream -d www.htmly.ffcms.stream
</code>
Always select option **2** to enforce permanent, automated HTTPS secure redirection mapping passes.

==== Generating Cryptographic Bcrypt Hashes for Flat-File Configs ====
When flat-file engines like Pulse CMS expect safe hashed credentials inside their configuration arrays rather than plain text, compute them natively using the target CLI binary:
<code>
/usr/bin/php8.1 -r 'echo password_hash("YOUR_TARGET_PASSWORD", PASSWORD_BCRYPT) . "\n";'
</code>

==== Breaking Cookie & Failure Throttles ====
If an engine throws infinite rejection loops (such as Pulse CMS displaying "Too many login failures" even after a complete reinstallation pass), the browser cache is passing stale session metrics.
  1. Open Browser DevTools (**F12**).
  2. Navigate to **Application** -> **Storage** / **Session Storage** / **Cookies**.
  3. Clear all tracking keys bound to the subdomain domain string.
  4. Force-purge backend temporary paths: ''sudo rm -rf /var/www/html/pulse/data/cache/*''
  5. Close all windows, open a brand-new **Incognito Tab**, and run a raw curl check: ''curl -I https://ffcms.stream'' to verify the ''HTTP/1.1 200 OK'' clean entry profile.

===== 5. Comprehensive Fleet Deployment Playbook Reference =====
^ Subdomain Hub ^ Architecture ^ Primary Strategy / Script Blueprint ^

| [[https://ffcms.stream|statamic]] | PHP 8.3 FPM | ''sudo -u www-data /usr/bin/php8.3 /usr/bin/composer create-project statamic/statamic statamic --prefer-dist --no-interaction'' <br> Create user via: ''sudo -u www-data /usr/bin/php8.3 artisan statamic:make:user'' |
| [[https://ffcms.stream|grav]] | PHP 8.3 FPM | Extracted official Admin package, linked to PHP 8.3 via FilesMatch. Core asset dependencies fully pre-built. |
| [[https://ffcms.stream|kirby]] | PHP 8.3 FPM | Extracted Starterkit main branch. Panel enabled remotely via ''site/config/config.php'' return array parameter: ''"panel" => ["install" => true]''. Locked behind custom ''.kirby.htpasswd'' file. |
| [[https://ffcms.stream|dokuwiki]] | PHP 8.3 FPM | Unpacked stable tarball. Configured custom permissions using native Access Control List manager. Removed ''install.php'' after onboarding profile build. |
| [[https://ffcms.stream|herbie]] | PHP 8.3 FPM | Created via ''composer create-project getherbie/start-website''. DocumentRoot funneled to secure public ''/web/'' directory. Rebuilt vendor tree via PHP 8.3 binary manually. |
| [[https://ffcms.stream|boidcms]] | PHP 8.1 FPM | Self-contained environment layer. Generic deployment credentials map cleanly to user ''admin'' and password ''password''. |
| [[https://ffcms.stream|flatpress]] | PHP 8.1 FPM | Extracted github master branch array. Fully self-contained engine that relies on native PHP rendering engines without requiring Composer arrays. |
| [[https://ffcms.stream|htmly]] | PHP 8.1 FPM | Extracted stable release zip. Resolved internal template compiler crash (''[views.root] is not set'') by enforcing direct traffic to ''/install.php'' initialization hook script. |
| [[https://ffcms.stream|mecha]] | PHP 8.1 FPM | Extracted release bundle, collapsed inner repository paths. Permissions recursively set to Apache user pool. |
| [[https://ffcms.stream|mozilo]] | PHP 8.1 FPM | Extracted source zip, flattened inner master folders. Preserved baseline entry code by safely renaming ''index.php'' to ''index.php.bak'' for staging operations. |
| [[https://ffcms.stream|pulse]] | PHP 8.1 FPM | Clean reinstallation path. Initialized folder arrays via ''/admin/install.php'' call. Core logins verified as encrypted bcrypt structures rather than obsolete plain text scripts. |

^ Permissions Enforcement Blueprint ^
<code>
sudo chown -R www-data:www-data /var/www/html/
sudo find /var/www/html/ -type d -exec chmod 755 {} \;
sudo find /var/www/html/ -type f -exec chmod 644 {} \;
sudo systemctl restart apache2
</code>