Installing Bludit 3.21.1 on Nginx

2026/05/11 in CMS Guides

Bludit is a flat-file CMS — no database, just text files and JSON on disk. Content is stored in flat files under /bl-content/pages/ and configuration lives in JSON. Depending on which editor you enable (TinyMCE, or the default Markdown processor), your posts will be stored as either HTML or Markdown — but the Nginx configuration is the same either way.

Prerequisites

  • Nginx 1.18+
  • PHP-FPM 8.1+ (Bludit 3.x requires PHP 7.4+, but 8.1+ is recommended for performance and security)
  • A domain name pointed to your server
  • SSL certificates — the examples below assume Let's Encrypt via Certbot

Step 1: Download and place Bludit

# Create the web root 
sudo mkdir -p /var/www/mysite.com/public_html 
# Download Bludit (free version) or grab the Pro zip from Patreon 
cd /tmp 
wget https://www.bludit.com/releases/bludit-3-21-1.zip 
sudo unzip bludit-3-21-1.zip -d /var/www/mysite.com/public_html 
# Set ownership — www-data (Debian/Ubuntu) or nginx (RHEL/Fedora) 
sudo chown -R www-data:www-data /var/www/mysite.com/public_html

Step 2: Base Nginx server block

Below is the smallest configuration that will get Bludit running. It omits security hardening, static caching, and several production niceties — don't use it as-is on a live site. The full, production-ready configuration is at the end of this article.

This is the minimal server block for Bludit:

server {
	listen 443 ssl http2;
	listen [::]:443 ssl http2;
	server_name mysite.com;

	# SSL certificates (Let's Encrypt)
	include /etc/letsencrypt/options-ssl-nginx.conf;
	ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
	ssl_certificate /etc/letsencrypt/live/mysite.com/fullchain.pem;
	ssl_certificate_key /etc/letsencrypt/live/mysite.com/privkey.pem;
	ssl_trusted_certificate /etc/letsencrypt/live/mysite.com/chain.pem;

	root /var/www/mysite.com/public_html;

	access_log /var/log/nginx/mysite.access.log;
	error_log /var/log/nginx/mysite.error.log;

	# Increase from Nginx's default 1M — needed for theme/plugin uploads
	client_max_body_size 8M;

	# Bludit's front controller — everything routes through index.php
	location / {
		try_files $uri $uri/ /index.php$is_args$args;
	}

	# PHP processing
	location ~ \.php$ {
		try_files $uri =404;
		include fastcgi_params;
		fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
	}
}

A few things to note:

  • try_files $uri $uri/ /index.php$is_args$args; — This is Bludit's entire routing mechanism. Static files and directories are served directly; everything else falls through to Bludit's index.php with any query string preserved.
  • listen 443 ssl http2; — If your server has multiple IPs and you want to bind to specific addresses, you can list them individually. For most setups, binding all IPv4 and IPv6 interfaces is fine.
  • listen [::]:443 ssl http2; — The IPv6 listener. Nginx's [::] covers both IPv4 and IPv6 on most systems unless you've set ipv6only=on.
  • client_max_body_size 8M; — Adjust this up or down depending on how large your media uploads will be. The default Nginx limit is only 1M, which won't cut it for most CMS use.

The include line pulls in Certbot's recommended TLS protocols, ciphers, OCSP stapling, and HSTS — all set to Mozilla's intermediate compatibility level by default. ssl_dhparam loads a 4096-bit Diffie-Hellman parameters file that Certbot generates on first install. Both are created automatically when you run certbot --nginx or certbot certonly, and they're safe to share across all your server blocks.

Step 3: Protect Bludit's internal directories

Bludit stores its content, user data, and workspace files in /bl-content/ and its core in /bl-kernel/. These should never be directly accessible from the web. Add this to your server block or include it as a separate file:

# bludit_security.conf — blocks direct access to Bludit internals
location ^~ /bl-content/databases/  { deny all; }
location ^~ /bl-content/workspaces/ { deny all; }
location ^~ /bl-content/pages/      { deny all; }
location ^~ /bl-kernel/*.php        { deny all; }

The ^~ prefix ensures these location blocks take priority over regex matches (like the PHP handler). bl-content/databases/ contains your users and security keys, bl-content/workspaces/ holds plugin data, and bl-content/pages/ is where your markdown content lives.