WFM - Windows + FrankenPHP + MariaDB Stack

✅ 1. Automated Installation

To get started, clone the repository to your desired location and run the master setup script. This script will download and extract FrankenPHP 1.12.3, MariaDB 11.4.12, and phpMyAdmin 5.2.3 automatically.

FrankenPHP include: PHP 8.5.6 and Caddy v2.11.3.

Step 1: Clone the repository

git clone https://github.com/adorade/wfm.git
cd wfm

Step 2: Run the setup script From the root directory:

PowerShell:
powershell -NoProfile -ExecutionPolicy Bypass -File setup\main.ps1

Git Bash:
./setup/main.sh

The setup script initializes the following components within your project root ($WFM):

• FrankenPHP ($WFM\frankenphp\): The core application server and PHP execution engine.
• MariaDB ($WFM\mariadb\): A portable, self-contained instance of the database engine.
• phpMyAdmin ($WFM\tools\phpmyadmin\): A web-based interface for managing your databases.

After installation, verify:

frankenphp --version
php --version

---

✅ 2. Setup FrankenPHP

FrankenPHP configuration is centralized in the config/ directory. This stack uses symbolic links to ensure the binaries use these shared settings regardless of their location.

Caddyfile (Web Server)

The main configuration file is $WFM\config\Caddyfile. Use this to:

• Define site blocks and domains (e.g., localhost, pma.local).
• Configure TLS settings and routing.
• Enable Worker Mode for high performance.

php.ini (PHP Settings)

The main PHP configuration is $WFM\frankenphp\php.ini ($WFM\config\php.ini is a symlink). Use this to:

• Enable or disable PHP extensions.
• Adjust memory_limit, upload_max_filesize, and max_execution_time.

---

✅ 3. Setup MariaDB

3.1 Initialize Data Directory

MariaDB requires a data/ directory to store your databases. Run the following command from the project root to initialize it and optionally create a Windows service:

cd $WFM\mariadb\bin
.\mariadb-install-db.exe --datadir=$WFM\data --service=MariaDB

Note: Omit the --service=MariaDB flag if you prefer to run the database engine manually.

3.2 Start the Database

If running as a service:

net start MariaDB

If running manually:

cd $WFM\mariadb\bin
.\mariadbd.exe --datadir=$WFM\data --console

3.3 Secure the Installation

Run the security script to set a root password and remove insecure default settings:

cd $WFM\mariadb\bin
.\mariadb-secure-installation

3.4 Database Settings (my.ini)

The main MariaDB configuration is $WFM\mariadb\my.ini ($WFM\config\my.ini is a symlink). Use this to:

• Change the default port (3306).
• Adjust memory limits and cache sizes.
• Configure logging and performance tuning.

---

✅ 4. Stack Management

You can manage the full WFM stack using the centralized management script or the system tray utility.

CLI Management

Use the scripts\manage-wfm.ps1 script to control services from the terminal:

# Start all services (MariaDB & FrankenPHP)
.\scripts\manage-wfm.ps1 -action start    # PowerShell
./scripts/manage-wfm.sh -action start     # Git Bash

# Stop all services
.\scripts\manage-wfm.ps1 -action stop     # PowerShell
./scripts/manage-wfm.sh -action stop      # Git Bash

# Restart all services
.\scripts\manage-wfm.ps1 -action restart  # PowerShell
./scripts/manage-wfm.sh -action restart   # Git Bash

# Check the status of processes and network ports
.\scripts\manage-wfm.ps1 -action status   # PowerShell
./scripts/manage-wfm.sh -action status    # Git Bash

System Tray Utility (GUI)

For a visual interface, run the tray launcher. It provides a right-click menu in your Windows Taskbar to start/stop services, view logs, and toggle auto-start with Windows.

PowerShell:
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\tray_launcher.ps1

Git Bash:
./scripts/tray_launcher.sh

Portability & Maintenance (Symlinks)

The WFM stack is designed to be portable. To keep management simple, we centralize all settings in the config/ directory and use symbolic links to point components (like PHP and MariaDB) to those files.

If you move the WFM folder to a different path or drive, these links will break and components may fail to load your settings.

Run this script if you move the project or if configurations aren't being picked up:
(Requires Administrator privileges) PowerShell:
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\create_symlinks.ps1

Git Bash:
./scripts/create_symlinks.sh

---

✅ 5. Portable Folder Structure

Here is the clean, portable, Windows‑friendly layout of your stack:

D:\WFM\
 ├─ frankenphp\
 │   ├─ frankenphp.exe      ← App Server (Caddy)
 │   ├─ php.exe             ← CLI Binary
 │   └─ php.ini             ← Active PHP config (Real file)
 │
 ├─ data\                   ← MariaDB databases (created during initialization)
 │
 ├─ mariadb\
 │   ├─ bin\                ← mariadbd.exe, mysql.exe, etc.
 │   └─ my.ini              ← Active DB config (Real file)
 │
 ├─ config\
 │   ├─ Caddyfile           ← Active Web config (Real file)
 │   ├─ assets\             ← Static assets (icons, etc.)
 │   ├─ sites\              ← Custom .caddyfile site blocks
 │   ├─ config.inc.php      ← symlink to tools\phpmyadmin\config.inc.php
 │   ├─ my.ini              ← symlink to mariadb\my.ini
 │   ├─ php.ini             ← symlink to frankenphp\php.ini
 │   └─ README.md           ← Configuration documentation
 │
 ├─ logs\                   ← Server and application logs
 │
 ├─ scripts\                ← Stack management and maintenance scripts
 │   └─ README.md           ← Scripts documentation
 │
 ├─ setup\                  ← Main setup script and GitHub integration
 │   └─ README.md           ← Setup documentation
 │
 ├─ tmp\                    ← Temporary session and cache files
 │
 ├─ tools\                  ← Third-party tools (phpMyAdmin)
 │   └─ phpmyadmin\
 │      └─ config.inc.php   ← Active PMA config (Real file)
 │
 ├─ www\                    ← Web application root
 │  └─ dashboard\           ← Minimalistic dashboard
 │
 └─ README.md               ← Main documentation

Why this structure?

• Portable → can be zipped and moved to another PC
• Separation of concerns
• Logs isolated
• Config isolated
• MariaDB ZIP stays self‑contained
• FrankenPHP stays self‑contained

Observations:

• Portability: The addition of $WFM reinforces the idea that this stack can run from any directory as long as the symlinks are refreshed.
• Data Folder: Specifically noting that data\ is created during initialization helps users who might worry why it's missing immediately after the main.ps1 script finishes but before they run the MariaDB install command.

---

🧩 Accessing phpMyAdmin

phpMyAdmin is automatically installed into tools/phpmyadmin and a secure config.inc.php is generated for you during setup.

1. Update your Hosts file

For the local domain to resolve, add this line to C:\Windows\System32\drivers\etc\hosts (requires Administrator privileges):

127.0.0.1 pma.local

2. Verify Caddy Configuration

Ensure the following block exists in your config/Caddyfile (it is included by default):

pma.local {
    root ../tools/phpmyadmin

    encode gzip zstd

    php_server

    file_server

    log {
        output file ../logs/pma-access.log
        format console {
            time_local
        }
    }
}

3. Automatic Configuration Check

The setup script has already generated $WFM\tools\phpmyadmin\config.inc.php ($WFM\config\config.inc.php is a symlink). It should look like this:

<?php
declare(strict_types=1);

/* Best practice: Use a secret for cookie encryption */
$cfg['blowfish_secret'] = '32_character_unique_guid';

/* Authentication type */
$cfg['Servers'][1]['auth_type'] = 'config';
$cfg['Servers'][1]['user'] = 'root';
$cfg['Servers'][1]['password'] = '';

/* Server parameters */
$cfg['Servers'][1]['host'] = '127.0.0.1';
$cfg['Servers'][1]['AllowNoPassword'] = true;
$cfg['Servers'][1]['port'] = '';
$cfg['Servers'][1]['socket'] = '';

$cfg['Servers'][1]['verbose'] = 'Franken PHP';
?>

4. Visit in Browser

Ensure that the stack is running, then visit: https://pma.local/
Note: You may see a certificate warning. This is expected as Caddy generates a local self-signed certificate for .local domains.

---

🎯 Final Result: Fully Native Windows WFM Stack

You now have:

• FrankenPHP (native Windows binary)
• MariaDB 11.4 ZIP (portable)
• phpMyAdmin (portable)
• No Docker
• No WSL
• No virtualization
• Full PHP + DB devstack on Windows

⚠️ Important Notes

✔ Works perfectly:

• PHP scripts
• PDO MySQL / mysqli
• Caddy routing
• Static files
• Environment variables

⚠ Limited or missing on Windows:

• Some PHP extensions (e.g., pcntl)
• Some FrankenPHP workers features
• No systemd integration (obviously)

---

📚 Further Reading

For more detailed information about specific components of this stack, please refer to the documentation in their respective directories:

• Setup Documentation - Details on installation scripts and GitHub integration.
• Configuration Documentation - Deep dive into centralized settings and symlinks.
• Management Scripts Documentation - Deep dive into CLI commands, symlink repair, and the system tray utility.

Official configuration and documentation:

• Caddyfile - Comprehensive guide for Caddy server configuration.
• FrankenPHP - Detailed documentation for FrankenPHP-specific directives and performance tuning.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.