Humblee

A humble PHP framework & CMS

Installation

Prerequisites

Before you begin, make sure your server meets the following requirements:

  • PHP 8.3 or higher with the sodium extension (bundled with PHP 8.3 — no separate install needed)
  • Apache with mod_rewrite enabled and .htaccess support (NGINX and IIS are supported but require additional rewrite configuration)
  • MySQL or PostgreSQL database
  • Composer — PHP package manager
  • Node.js and npm — required for the frontend build tooling and CSS dependencies

Steps

1. Clone the repository

git clone https://github.com/micah1701/humblee

2. Configure your environment

Open humblee/configuration/env_dev.php and fill in your database credentials and any other environment-specific values.

You can create additional copies of this file for different environments — for example env_qa.php or env_production.php. To switch between them, update the reference in humblee/configuration/config.php.

3. Install PHP dependencies

Run Composer from inside the humblee/ directory:

cd humblee
composer install

This installs the following libraries into humblee/vendor/:

Library Required Purpose
j4mie/idiorm Yes Lightweight ORM for all database access
twilio/sdk No SMS delivery for two-factor authentication
tinify/tinify No Image compression via the TinyPNG API
erusev/parsedown No Converts Markdown content blocks to HTML

Optional libraries are gated in code — if you do not add credentials for Twilio or Tinify in your environment config, those features are simply disabled.

4. Install frontend dependencies

Run the setup script from the project root:

npm run setup

This installs two separate sets of dependencies:

  • public/node_modules/ — Bulma CSS, Bulma Tooltip, and nestedSortable. These are served directly by the admin UI and must live in this location.
  • frontend/node_modules/ — Vite, Svelte, and TypeScript. These are build tools only and are never served to the browser.

The two sets are intentionally kept separate. The root workspace does not hoist them into a shared node_modules/ because that would break the PHP templates that reference Bulma directly by path.

Built frontend assets (the compiled JS and CSS for tools like the media manager) are committed to the repository, so npm run build is only needed when actively developing a frontend tool — not for a standard deployment.

5. Run the installer

In your browser, navigate to:

https://your-site.tld/humblee/install

The installer will:

  1. Create the required database tables
  2. Insert default content
  3. Generate a 32-byte encryption key and write it to humblee/configuration/crypto/key.php
  4. Prompt you to create the master admin user account

Once installation is complete, the install page will no longer be accessible.

Important: Do not lose humblee/configuration/crypto/key.php. It is excluded from version control and is the only key that can decrypt your media files. Back it up alongside your database.

Server configuration notes

PHP in CGI or FastCGI mode

Humblee is configured out of the box for Apache's mod_php. If you see No input file specified after installation, you are likely running PHP in CGI or FastCGI mode. Two changes are required:

1. Update public/.htaccess:

# Comment out or remove this line:
# RewriteRule ^(.*)$ index.php/$1 [L]

# Replace with these two lines:
RewriteRule . /index.php [L]
RewriteRule ^index.php/(.*)$ [L]

2. Update the getURI() method in humblee/src/Foundation/Core.php — replace the final $uri assignment with:

$_path_info = preg_split("/\?|\&/", $_path_info);
$uri = (!isset($_path_info[0]) || $_path_info[0] === "" || $_path_info[0] === "public") ? "" : ltrim($_path_info[0], "/");
return $uri;

PHP runtime settings (upload size, memory)

The preferred place to set upload_max_filesize, post_max_size, and similar limits is your server's main php.ini. If you need per-project overrides:

  • CGI / FastCGI (php-fpm): Create a public/.user.ini file:

    upload_max_filesize = 50M
post_max_size = 52M

    PHP-FPM caches .user.ini for 5 minutes, so changes may take a moment to take effect. Do not use php_value directives in .htaccess under FastCGI — Apache cannot pass them to the FPM process, which causes a 403 error on the site root.

  • mod_php: php_value directives in .htaccess work as expected:

    php_value upload_max_filesize 50M
php_value post_max_size 52M

Folder permissions

Two directories need to be writable by the web server:

humblee/configuration/ — the installer writes the encryption key here. If it fails, temporarily relax permissions to 777, let the installer run, then tighten back to 755.

storage/ — all uploaded media is saved here. On Ubuntu/Debian with Apache running as www-data:

sudo chown -R www-data:www-data /path/to/storage
sudo chmod -R 755 /path/to/storage

If you also need your own user account to manage files in this directory via CLI, use shared group ownership with the setgid bit so new files inherit the group automatically:

sudo chown -R youruser:www-data /path/to/storage
sudo chmod -R 775 /path/to/storage
sudo chmod g+s /path/to/storage

To confirm which user Apache is running as: ps aux | grep apache2 | grep -v root