Configuration of Nginx and PHP‑FPM for Geeklog

Author: Joel Barrios Dueñas
Email: darkshram at gmail dot com
Website: https://www.alcancelibre.org

Creative Commons License
© 1999‑2026 Joel Barrios Dueñas. This manual is distributed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0) license. You are free to share and adapt the material under the following terms: you must give appropriate credit, you may not use the material for commercial purposes, and you must distribute your contributions under the same license. The full license is available at https://creativecommons.org/licenses/by-nc-sa/4.0/legalcode.

Introduction

Geeklog stands out as a robust content management system (CMS) suitable for large-scale deployments, particularly when optimized with the combination of Nginx and PHP‑FPM. Its modular architecture allows for extensive customization and enhancement through plugins, though many of them remain in beta. Geeklog’s community, while smaller than some other CMS projects, is highly specialized and produces excellent content. However, it is far from being the most popular CMS, which can result in fewer readily available themes compared to platforms like WordPress. A notable characteristic is that a significant portion of themes are legacy, predating the Geeklog 2.0 series, and lack support for newer templating features, although they maintain backward compatibility.

Secure Location of System Files

It is critical to avoid placing the system/ directory and the db-config.php file within the web server's publicly accessible document root (e.g., public_html/). A secure configuration involves keeping these sensitive files outside the web tree. The following structure is recommended:

/home/user/private/
├── db-config.php
└── system/
    ├── lib-common.php
    └── ... (other system files)
/home/user/public_html/
└── index.php (and other public files)

The siteconfig.php file, which is part of the public installation, must then point to the correct, secure location of the system files. An example configuration would be:

// In /home/user/public_html/siteconfig.php
$_CONF['path_system'] = '/home/user/private/system/';
$_CONF['path'] = '/home/user/public_html/';

SELinux Configuration for RHEL and Derivatives

Note for ALDOS Users: The policycoreutils-python-utils package is essential for managing SELinux contexts and is typically included by default.

For systems with SELinux in enforcing mode, it is necessary to assign the appropriate security context to the private directory and its contents. Use the following commands to set the context for httpd_sys_rw_content_t and apply it:

sudo semanage fcontext -a -t httpd_sys_rw_content_t "/home/user/private(/.*)?"
sudo restorecon -Rv /home/user/private/

To verify the applied contexts, use:

ls -Z /home/user/private/

Virtual Host Configuration in Nginx WITHOUT Friendly URLs

The following Nginx server block configuration serves Geeklog without URL rewriting for friendly links. Note the absence of rewrite directives in the location / block.

server {
    listen 80;
    server_name www.example.net;
    root /home/user/public_html;
    index index.php index.html index.htm;

    access_log /var/log/nginx/www.example.net.access.log;
    error_log /var/log/nginx/www.example.net.error.log;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/var/run/php/php-fpm-geeklog.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}

Activation and Configuration of Geeklog

Once the web server is configured, the next step involves configuring Geeklog itself through its administration panel and key configuration files.

The siteconfig.php File

This file, located in the public root (e.g., /home/user/public_html/), is the primary configuration file. To enable the basic setup, you must define the site URL and disable URL rewriting.

// /home/user/public_html/siteconfig.php
$_CONF['site_url'] = 'http://www.example.net';
$_CONF['url_rewrite'] = false; // Disables friendly URLs

SECURE ADMIN PATH: For enhanced security, change the default administration path. For example:

$_CONF['admin_url'] = $_CONF['site_url'] . '/panel_de_control_privado';

Advanced Customization with lib-custom.php

For advanced users requiring deep template customization without altering core files, Geeklog provides the lib-custom.php file. Place this file in the private/system/ directory. You can use it to inject custom variables into the template engine.

// /home/user/private/system/lib-custom.php
function CUSTOM_templateSetVars($type, $template, &$vars) {
    if ($type == 'article' && $template == 'story') {
        $vars['custom_message'] = 'This is a customized article view.';
    }
}

Virtual Host Configuration in Nginx WITH Friendly URLs

To enable friendly URLs (e.g., /article/title-of-the-article), URL rewriting rules are required. The order of these rules is critical: specific rules for the /print functionality must precede the general catch-all rule to prevent conflicts.

server {
    listen 80;
    server_name www.example.net;
    root /home/user/public_html;
    index index.php index.html index.htm;

    access_log /var/log/nginx/www.example.net.access.log;
    error_log /var/log/nginx/www.example.net.error.log;

    location / {
        try_files $uri $uri/ /index.php?$args;
        # Friendly URL rewrites for Geeklog
        rewrite ^/article/([^/]+)/?$ /index.php?topic=$1 last;
        rewrite ^/topic/([^/]+)/?$ /index.php?topic=$1 last;
        rewrite ^/staticpages/([^/]+)/?$ /staticpages/index.php?page=$1 last;
        # CRITICAL: Print rules MUST come before the general static page rule
        rewrite ^/staticpages/([^/]+)/print/?$ /staticpages/index.php?page=$1&mode=print last;
        rewrite ^/print/article/([^/]+)/?$ /index.php?topic=$1&mode=print last;
    }

    location ~ \.php$ {
        try_files $uri =404;
        fastcgi_split_path_info ^(.+\.php)(/.+)$;
        fastcgi_pass unix:/var/run/php/php-fpm-geeklog.sock;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }
}

Configuration for PHP‑FPM

A dedicated PHP‑FPM instance improves security and performance by isolating Geeklog's PHP processes. Below is an example configuration for a pool named geeklog.

[geeklog]
user = www-data
group = www-data
listen = /var/run/php/php-fpm-geeklog.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

pm = dynamic
pm.max_children = 10
pm.start_servers = 2
pm.min_spare_servers = 1
pm.max_spare_servers = 5
pm.max_requests = 500

php_admin_value[upload_max_filesize] = 16M
php_admin_value[post_max_size] = 16M
php_admin_value[max_execution_time] = 120
php_admin_value[date.timezone] = "America/Mexico_City"

env[HOSTNAME] = $HOSTNAME
env[PATH] = /usr/local/bin:/usr/bin:/bin
env[TMP] = /tmp
env[TMPDIR] = /tmp
env[TEMP] = /tmp

Troubleshooting Common Issues

The following are solutions to common problems encountered during the configuration of Geeklog with Nginx and PHP‑FPM.

The "Print" Mode of Static Pages is Failing

This issue commonly arises from the order of rewrite rules in the Nginx configuration. The rule that captures the /print mode for static pages must be placed before the more general rule that handles standard static pages.

Advanced Note: If the rule order is correct, verify that the theme's printable.thtml template file exists and is not corrupted. A missing template file prevents the print view from rendering correctly.

Friendly URLs for Articles, Topics, etc., Do Not Redirect

Confirm that the $_CONF['url_rewrite'] variable in siteconfig.php is set to true. Next, verify that the Nginx rewrite rules are correctly written and placed within the location / block. Finally, clear Geeklog's internal cache through the administration panel, as it may retain old URL structures.

PHP Files are Downloaded Instead of Executed

This indicates that PHP‑FPM is not processing .php files. First, ensure the location ~ \.php$ block is present and correctly configured in your Nginx virtual host. Second, confirm that the fastcgi_pass directive points to the correct socket or TCP address of your running PHP‑FPM instance (e.g., unix:/var/run/php/php-fpm-geeklog.sock). Finally, restart both the Nginx and PHP‑FPM services.

Error 403 When Accessing the Installation Directory

An HTTP 403 Forbidden error typically points to filesystem permission issues. Ensure the web server user (e.g., www-data or nginx) has execute (x) permission on all parent directories leading to the public_html/ folder, and read (r) permission on the files within. Also, double-check that the root directive in the Nginx configuration points to the correct absolute path.

Uploaded File Size Limits

When uploads fail, verify that the size limits are consistently set across three configuration points:

  1. In the PHP‑FPM instance configuration (php_admin_value[upload_max_filesize] and php_admin_value[post_max_size]).
  2. In the PHP configuration file (php.ini).
  3. Within Nginx (client_max_body_size directive in the http or server block).

Clarification on Units: In configuration files, M typically denotes Megabytes (MiB), where 16M equals 16 Megabytes (16 MiB). Ensure unit consistency to prevent miscalculations.

Final Considerations

Always test the configuration in a staging environment before applying it to a production server. Thoroughly check all website functionalities, including article posting, static page creation, plugin activation, and file uploads. For more complex redirection needs beyond the basic friendly URLs, consult the dedicated manual on URL redirections and rewrites available on the author's website.

Considerations for Creating Technical Documentation

When writing technical articles or documentation within Geeklog, be aware that the default editor may misinterpret the backslash (\) escape character, especially within code blocks. This can corrupt commands or configuration examples.

Recommended Workaround: Write code snippets and configuration examples in a plain text editor. Then, paste them into a Geeklog Static Page using the "Plaintext Editor" or "Source Mode" to avoid automatic formatting. For displaying a literal backslash character in the final rendered page, it is often necessary to use its HTML entity, \.

For instance, to correctly display a Linux path like /home/user/\$BACKUP, you might need to write it in the static page editor as:

/home/user/\$BACKUP