Bludit: a flat-file PHP CMS

What Bludit is

Bludit is an open-source content management system written in PHP. Its repository describes it as a simple, fast, secure, flat-file CMS. It is a CMS product: an application that gives you an admin area, content, themes and plugins. It is not PHP core, not a framework or framework component, not an async library and not a standalone PHP runtime. Compare Drupal: it is also a CMS product that runs on PHP core, and it is a different project from Bludit. Bludit needs a web server with PHP support to run.

The source packet for this guide is the official repository page only.

Content model

According to the README, Bludit stores content in JSON format. That removes the need to install or configure a database. Pages can be written in Markdown or HTML. This is what flat-file means here: content lives in files that belong to the application directory tree rather than in a database server.

Architecture

The repository root lists these top-level entries:

• bl-content
• bl-kernel
• bl-languages
• bl-plugins
• bl-themes
• index.php
• install.php
• .htaccess

The names suggest the layout. Kernel code, language files, plugins and themes sit in their own directories, and bl-content is the likely home for site data. The packet does not describe these directories in detail, so treat that mapping as an inference to confirm in the official documentation. The same applies to which files hold your site data. It matters for backups.

Index.php is the web entry point and install.php belongs to the installer. The packet does not say what to do with the installer after setup. Check the official documentation and the security policy before going public.

Execution model

In a classic PHP request lifetime, the web server starts PHP work for each request. PHP builds its variables, runs the script and then discards request state. Bludit's documented setup follows this model: a web server with PHP, plus the built-in development server or Docker for quick tests. The packet does not describe running Bludit in a persistent worker.

A persistent worker (for example under Swoole or Open Swoole, which are different projects) keeps the PHP process alive between requests. Process memory then survives. Static properties, globals, caches, open file handles and per-user data can leak from one visitor to the next unless the code resets them. Cleanup means clearing request-scoped state, closing handles and recycling workers. For a flat-file CMS this risk is concrete: cached JSON could go stale, and one visitor's session or login data could carry over to another. Bludit has no documented persistent-worker mode in the packet, so it is unknown whether that works. Do not assume it.

Practical use cases

• A small website or blog where file-based content is enough.
• A local trial of a CMS without running a database server.
• A teaching example of how a PHP application can store structured content as JSON.
• A site that uses community plugins and themes. The README links to plugin and theme resources.

Requirements

The README lists:

• A web server with PHP support.
• PHP 8.0 or higher.
• The mbstring module for full UTF-8 support.
• The gd module for image processing.
• The dom module for DOM manipulation.
• The json module for JSON manipulation.

The packet does not state which PHP versions are tested. Support for PHP 8.4 is unknown, and so is support for PHP 8.5. This track stays on PHP 8.4 with 8.5 planned. Check the project's current documentation and your own tests before relying on either version.

Installation approach

The documented manual route is to download the latest version from bludit.com, extract it into a directory such as bludit, upload it to your server or hosting, visit the URL and follow the installer. For quick tests, the README names the PHP built-in server (php -S localhost:8000) or the Docker image bludit/docker:latest on port 8000.

The example below uses that image through Docker Compose. It binds the port to 127.0.0.1 so only your machine can reach it. The packet does not document a persistent volume path inside the image. The example therefore has no volume, and removing the container may discard content. Treat it as a throwaway trial.

Deployment notes

Bludit reads the client IP from REMOTE_ADDR only. It does not trust X-Forwarded-For or CF-Connecting-IP, because clients can forge them. Behind a reverse proxy, configure the web server to rewrite REMOTE_ADDR before PHP runs. Otherwise the login brute-force blocklist can block the proxy itself, which locks out every visitor. Visitor statistics would also count all traffic as one visitor.

• Apache: the README says to enable mod_remoteip and list upstream ranges with RemoteIPTrustedProxy. For Cloudflare it names the CF-Connecting-IP header.
• nginx: use ngx_http_realip_module with set_real_ip_from and real_ip_header.
• Direct, localhost or intranet deployments need no such configuration.

The README says to upgrade within the same major version like this: make a full backup of all files and directories, note your current version for roll-back, download and extract the new release, replace the existing files, and clear your browser cache. Then log in and check your settings. If a server cache such as Cloudflare sits in front, purge it too. Stale files such as TinyMCE assets can cause UI problems.

Never expose FastCGI publicly. The packet does not cover PHP-FPM setups, so follow your web server's documentation.

Strengths

• No database to install or configure.
• Content stored as JSON, written in Markdown or HTML.
• MIT license, as stated in the README.
• Plugin and theme extension points, a Docker image for trials and a published security policy.
• A short documented install path.

Limitations and unknowns

• Current release version: unknown from this packet.
• Maintenance and support status: unknown, so the lifecycle is marked unknown. The packet shows open issues and pull requests but no support policy.
• PHP 8.4 and 8.5 compatibility: unknown. Only PHP 8.0 or higher is stated.
• Performance: the project calls itself fast, but the packet gives no measurements. This guide makes no speed claim.
• Bludit PRO is mentioned for Patreon supporters. Its terms and any prices are unknown.
• The Docker image's internal PHP version and data paths are unknown.
• Persistent-worker behavior is undocumented.
• Multi-server scaling with file storage is not covered. Concurrent writes and shared storage are unknown.

Next steps

Run the Compose example, finish the installer in a browser, then read the official documentation on themes, plugins, backups and security. The example needs Docker and network access and is not a browser exercise.

services:
  bludit:
    image: bludit/docker:latest
    container_name: bludit
    ports:
      - "127.0.0.1:8000:80"

docker compose up -d
docker compose ps
curl -I http://127.0.0.1:8000
docker compose stop