Bludit flat-file CMS: installation, JSON storage, and deployment limits

Bludit's JSON storage removes database setup

Bludit addresses a specific operational problem: running a PHP blog without installing, configuring, or administering a separate database. The README states that content is stored in JSON, while a site needs only a web server with PHP support. This makes the project most relevant to solo publishers, developers, and small organizations that want a conventional PHP content workflow without adding a database service to a simple hosting environment.

The repository layout also separates recognizable parts of the application. `bl-content/` is the obvious content area, while `bl-kernel/`, `bl-plugins/`, and `bl-themes/` contain the core, extension, and presentation areas. `bl-languages/` holds language resources. At the top level, `index.php` is the public entry point and `install.php` provides the installer path. These names support the flat-file model, although the README does not document the complete schema or locking behavior of every JSON file.

Bludit supports both Markdown and HTML for content. That choice is useful for technical blogs, where authors may want Markdown for ordinary posts and direct HTML when a post needs markup that the editor does not otherwise provide. The separate plugin and theme resources indicate an extension model rather than a single fixed interface. The repository includes theme and plugin directories, and the README links to dedicated plugin and theme sites.

The central trade-off is file administration. Removing a database does not remove the need to protect, back up, and replace content files. It moves those duties into the filesystem workflow. That may be simpler for a single-server blog, but it offers less visible transaction handling than a database-backed content system.

Installing Bludit on PHP and trying it through Docker

For a conventional installation, the README directs users to download the latest archive from `bludit.com`, extract it into a directory such as `bludit`, upload that directory to the web server, visit the site URL, and complete the Bludit Installer. The documented runtime requirements are PHP 8.0 or later and the `mbstring`, `gd`, `dom`, and `json` modules. The modules have specific roles: `mbstring` supports full UTF-8 handling, `gd` handles images, `dom` supports DOM manipulation, and `json` supports JSON manipulation.

A first local use can instead use the documented Docker image. The two commands below download the image, start a container named `bludit`, publish container port 80 on local port 8000, and run it in detached mode.

docker pull bludit/docker:latest
docker run -d --name bludit -p 8000:80 bludit/docker:latest

After the container starts, the README says to open the following address in a browser:

http://localhost:8000

The address should lead to the installation flow. Complete that flow to set up the website before creating the first post. The README also names PHP's built-in server as an alternative for testing, using this command:

php -S localhost:8000

The documentation does not give a `composer install` command, environment-variable list, or configuration file for this path. It presents the archive, built-in server, and Docker image as the available setup routes.

Reverse proxies can break Bludit's IP-based controls

Bludit has a deployment-specific weakness around client IP detection. According to the README, PHP code reads the client address from `REMOTE_ADDR` only. Proxy headers such as `X-Forwarded-For` and `CF-Connecting-IP` are not trusted by Bludit because those headers can be forged. Ignoring them is a defensible security choice, but it means the web server must translate trusted proxy information into `REMOTE_ADDR` before PHP receives the request.

This is not merely an analytics concern. The README says the login brute-force blocklist may block the proxy itself after enough failed login attempts. Because visitors may appear to share the proxy address, that condition can lock out every visitor. Visitor statistics can also collapse all proxy-routed traffic into what appears to be one visitor. A public installation behind Cloudflare, nginx, or Apache therefore requires server-side verification rather than assuming the default PHP view is correct.

For Apache, the README names `mod_remoteip`, `RemoteIPTrustedProxy`, `CF-Connecting-IP`, and Cloudflare's published IP ranges. For nginx, it names `ngx_http_realip_module`, `set_real_ip_from`, and `real_ip_header`. The repository deliberately leaves the exact upstream ranges and directives to the operator. Direct, localhost, and intranet deployments need no such configuration.

This limitation makes Bludit less transparent behind proxies than applications designed with an explicit trusted-proxy configuration. It is also a reason to inspect login behavior and visitor totals after moving an existing site behind a CDN or reverse proxy.

Bludit upgrades replace files and require complete backups

The documented upgrade path is file replacement rather than a migration command. It applies when moving between versions within the same major version, such as the 3.x series. The first step is to copy every file and directory into a new folder. Operators are also told to record the installed version so rollback remains possible if needed.

After downloading and extracting the new archive, existing files are replaced with the new files. The browser cache is then cleared, settings are reviewed in the admin area, and any server-side cache is purged. The README specifically warns that components such as TinyMCE may continue serving older files from a browser or server cache, which can produce interface problems or JavaScript errors.

This process keeps the upgrade understandable for a small flat-file site, but it places responsibility on the operator. A partial copy can miss content or site-specific files. The documentation does not describe a database migration because Bludit does not require one, but it also does not provide a selective list distinguishing core files from uploaded content. A complete directory copy is therefore the documented boundary.

The project was last pushed on 2026-10-15, so the repository was not archived at that point. Recent listed releases include 3.22.0 on 2026-05-11, 3.21.1 on 2026-05-01, and 3.21.0 on 2026-04-26. Those facts show recent release activity, while upgrade effort remains proportional to the need to preserve, replace, and verify the site's files. Bludit is distributed under the MIT license. That permits use and modification under the license's terms, but operators remain responsible for reviewing dependencies and complying with all applicable licenses.

Bludit versus a database-backed PHP CMS

The closest architectural alternative is a database-backed PHP CMS. Both can serve PHP-rendered pages, support themes or plugins, and run on a web server. The operational difference begins with content storage. Bludit uses JSON files and requires no database installation or configuration. A database-backed CMS adds a database engine, credentials, schema management, and query execution, but it provides a conventional transactional store for concurrent writes and structured querying.

Bludit is consequently easier to deploy when the hosting provider already offers PHP and filesystem access, especially for a small blog whose content can be copied directly. Static generation is not the same alternative here, because Bludit remains a PHP application with an admin area, plugins, themes, and server-side request handling. Database-backed systems are more suitable when shared writes, relational data, database administration, or centralized concurrency controls are part of the deployment.

The README does not document transaction isolation, multi-site storage, object storage, or a horizontal scaling model. Those omissions do not establish that such workloads are unsupported, but they leave the decision dependent on the file-oriented architecture and the operator's ability to manage a single writable site tree. Bludit should not be selected merely because its description says it is fast. The practical comparison is database-free operation versus storage features that the documentation does not claim.

Choosing Bludit around the filesystem boundary

Bludit's strongest case is a PHP blog or small website operated by someone who wants JSON-backed content and accepts file-based administration. Docker provides a quick local route through `bludit/docker:latest`, while an ordinary deployment needs PHP 8.0 or later plus four named extensions. Themes and plugins offer recognizable extension points without requiring the content model to be hosted in a separate database.

The key boundary is operational. Backups must include the complete file tree, upgrades replace files within a major version, and proxied deployments must rewrite `REMOTE_ADDR` correctly. The README does not document a rollback command, automatic schema migration, multi-writer coordination, or a transaction model. Those omissions matter more than the project's simple installer if content consistency across several writers or servers is central to the site.

For a single-server blog, start with the Docker command, complete the installer, create a Markdown post, and confirm that the required PHP modules are present. For an existing proxied site, check the login blocklist and visitor attribution first. The adoption decision should therefore turn on whether a complete JSON file tree is an acceptable unit of backup, deployment, and recovery.

Editorial conclusion

Bludit fits developers and site owners who want a PHP blog without database administration, especially when JSON files and direct file backups are acceptable. It is a poor fit for deployments that require database transactions, multi-node shared writes, or transparent proxy-header handling. Verify PHP 8.0 or later with `mbstring`, `gd`, `dom`, and `json`, confirm writable storage and backup procedures, then inspect `REMOTE_ADDR` behavior before enabling public login.

Frequently asked questions

Official sources

1. bludit/bludit on GitHub
2. License: MIT
3. Project website
4. README
5. Releases