Powershell Files

For local server environments, Ledger uses PowerShell (ps1) files to complete various actions, these include, install.ps1, start_server.ps1, kill.ps1, diag.ps1 and update-schema.ps1

---

install.ps1

This PowerShell script manages the initialization and orchestration of the portable development stack. It automates the configuration of the local environment, starts the backend services, and seeds the database.

---

1. Initial Launch & Domain Setup

The script uses ledger.test as the local development domain.

• Privilege Elevation: On the first run, the script will request Administrator privileges to modify your Windows hosts file (C:\Windows\System32\drivers\etc\hosts).
• DNS Resolution: It maps 127.0.0.1 to ledger.test. Once this entry exists, subsequent launches do not require Admin rights.
• Cleanup: The script automatically flushes the DNS cache (ipconfig /flushdns) to ensure the new domain mapping is active immediately.

---

2. Service Orchestration

The script starts three core components in the background:

• MariaDB (Port 3307): Initializes the data directory using mariadb-install-db.exe if it doesn't exist. It uses a custom my.ini generated from your template.
• PHP FastCGI (Port 9000): Starts the PHP-CGI engine bound to the local interface, utilizing the portable php.ini configuration.
• Caddy Web Server: Loads the Caddyfile and routes traffic to the PHP engine. It passes the current directory as LEDGER_ROOT to the environment.

---

3. Automated Database Setup

Once the services are running, the script performs a "Surgical Seed":

1. Connectivity Check: It polls Port 3307 until MariaDB is ready to accept connections.
2. Database & User Creation:
   • Creates the database ledger_db.
   • Configures a local user ledger_user with password ledger123.
3. Schema Import: Sources the install/schema.sql file to build the table structure.
4. Data Seeding: * Admin User: Creates the default administrator account (admin@ledger-demo.local).
   • Site Settings: Injects default metadata (Site Name, Description, Asset Paths) into the site_settings table.

---

4. Troubleshooting & Logs

If the stack fails to start, refer to the following:

• Start Log: Found at \logs\start_stack.log. This contains the timestamped output of every step.
• Import Log: Found at \install\import_log.txt. Specifically tracks SQL execution results and errors.
• Common Failures: * Port 3307 or 9000 already in use by another application.
  • Missing binaries in the \bin or \php directories.
  • Antivirus blocking the hosts file modification.

---

start_server.ps1

This script serves as the primary "ignition" for the Ledger stack. It orchestrates the startup of MariaDB, PHP-CGI, and Caddy to provide a zero-dependency local environment.

---

1. Initialization Logic

The script automatically determines the project root and sets up a logs/ directory. All startup events are recorded in logs/start_stack.log for audit trailing.

---

2. Service Orchestration

The stack is brought online in a specific sequence to ensure dependency availability:

Phase	Service	Technical Action
I	MariaDB	Starts the database engine using the specific instance config (data/my.ini) on port 3307. It uses a hidden window style to keep the desktop clean.
II	PHP FastCGI	Launches php-cgi.exe bound to 127.0.0.1:9000. It explicitly loads the local conf/php.ini to ensure portability.
III	Caddy	Sets the LEDGER_ROOT environment variable and runs the Caddyfile configuration. This serves as the reverse proxy and SSL terminator.

---

3. Connection & Access

Once the "SERVER READY" notification appears:

• Primary URL: https://ledger.test:8443/
• Auto-Launch: The script will automatically open your default browser to this address.

---

4. Critical Checks for Users

• Ports: Ensure ports 8443 (HTTPS), 3307 (DB), and 9000 (PHP) are not blocked or used by other software (like a local XAMPP or IIS instance).
• Binary Health: If the script reports "Binary not found," ensure the bin/ and php/ folders haven't been moved or deleted.
• Logs: If the terminal shows a red "STARTUP FAILED" message, check logs/start_stack.log immediately for the specific exception string.

---

kill.ps1

Cleanly stops all three Ledger server services: Caddy web server, PHP-CGI, and MariaDB database.

What It Does

1. Stops Caddy - Kills all caddy.exe processes
2. Stops PHP-CGI - Kills all php-cgi.exe and php.exe processes
3. Stops MariaDB - Kills all mysqld.exe and mariadbd.exe processes
4. Verifies Shutdown - Checks that all processes actually terminated
5. Logs Activity - Saves all actions to logs\stop_stack.log

Usage

Double-click kill.ps1 or run from PowerShell:

Output

• Shows which processes were stopped with their PIDs
• Confirms successful shutdown with green checkmarks
• Warns if any processes are still running with yellow warnings
• Reports summary of stopped/failed processes

When to Use

• Before making configuration changes
• When services need a clean restart
• Before running fix scripts
• At end of development session
• When processes are misbehaving or stuck

Notes

• Uses Stop-Process -Force to ensure processes terminate
• Waits 2 seconds after stopping to verify clean-up
• Does not error if services aren't running
• May require Administrator privileges if processes won't stop

---

diag.ps1

Comprehensive diagnostic and fix script that checks and repairs both MariaDB permission issues AND PHP configuration problems in one go.

What It Does

Step 1: Stop All Services

• Stops Caddy, PHP-CGI, and MariaDB processes
• Ensures clean state before making fixes

Step 2: Check MariaDB Permissions

• Scans all critical database files (ibdata1, undo files, aria logs)
• Removes read-only attributes from database files
• Sets full control permissions on data directory
• Fixes the "ibdata1 must be writable" error

Step 3: Check PHP Configuration

• Verifies php.ini exists (creates from template if missing)
• Checks if required extensions are enabled:
  • mysqli (database connection)
  • mbstring (multi-byte string handling)
  • openssl (secure connections)
  • pdo_mysql (alternative database driver)
  • curl (HTTP requests)
• Automatically enables disabled extensions
• Verifies extension DLL files exist in ext directory

Step 4: Check Port Availability

• Tests if ports are available:
  • 3307 (MariaDB)
  • 9000 (PHP-CGI)
  • 8443 (Caddy HTTPS)
  • 8080 (Caddy HTTP)
• Warns about port conflicts

Step 5: Summary Report

• Lists all fixes applied
• Reports remaining issues
• Provides specific recommendations
• Logs everything to logs\fix_all.log

---

Managing the Processes

Since the processes run in Hidden mode, they will continue to run in the background after you close the PowerShell window. To stop the server, you will need to terminate the processes using kill.ps1

---

Compatibility & Troubleshooting

Why it might not work on older computers

This stack uses modern binaries and PowerShell automation that require specific Windows features. If the installer window closes immediately on your machine, check the following:

1. PowerShell Version (Requires 5.1+)

Older versions of Windows (Windows 7/8) often ship with PowerShell 2.0 or 3.0. This script uses commands like Test-NetConnection and modern redirection syntax that do not exist in older versions.

• Fix: Install Windows Management Framework 5.1.

2. Unblock in Properties

Right click install.ps1 select properties and Security and tick/select "unblock"

---

Support

Issues or questions visit the Troubleshooting forum.

---

Is this document high quality? Or does it need improvement? High ranking articles display in the footer, admin notified if improvements required.