Rocket-Nginx Documentation

Starting with version 3.0, you can inject custom Nginx configuration snippets into specific stages of the request lifecycle by placing files in the rocket-nginx/conf.d/default/ directory using specific filename patterns:

Version 3.x is not backward-compatible with versions 1 or 2. To upgrade:

1. Save your existing configuration as a backup.
2. Start with a fresh configuration to ensure all new features and structural changes are correctly implemented.
3. Review the new configuration options, as many behaviors have changed.

To inspect how Nginx is serving files, enable debug mode in rocket-nginx.ini:

debug = true

Response Headers

All requests include the following header:

• X-Rocket-Nginx-Serving-Static: Indicates if the file was served directly (HIT, MISS, or BYPASS).

When debug = true, the following additional headers are added:

• X-Rocket-Nginx-Reason: If the status is not HIT, explains why WordPress was called (e.g., Post request, Arguments found, Maintenance mode, Cookie, Specific mobile cache activated, or File not cached). If HIT, shows the URL used.
• X-Rocket-Nginx-File: If HIT, shows the absolute path to the file on disk.
• X-Rocket-Nginx-Device: Indicates the detected device (desktop or mobile).

To install Rocket-Nginx, clone the repository into your Nginx configuration directory (typically /etc/nginx/).

cd /etc/nginx
git clone https://github.com/satellitewp/rocket-nginx.git

Since version 2.0, the configuration must be generated using the included parser:

cd rocket-nginx
cp rocket-nginx.ini.disabled rocket-nginx.ini
php rocket-parser.php

This generates a default.conf file. You must then include this file in your Nginx server block:

server {
  ...
  # Rocket-Nginx configuration
  include rocket-nginx/conf.d/default.conf;
  ...
}

Finally, test and reload Nginx:

nginx -t
service nginx reload

Because Rocket-Nginx serves cached files without executing PHP, standard WP-Cron jobs (which rely on site visits) may not trigger. It is strongly recommended to disable WordPress's internal cron and use a system-level cron job instead.

1. Add this to your wp-config.php:

define( 'DISABLE_WP_CRON', true );

2. Set up a manual cron job (e.g., every 15 minutes) using one of these methods:

Using wget:

*/15 * * * * wget -q -O - http://www.website.com/wp-cron.php?doing_wp_cron &>/dev/null

Using curl:

*/15 * * * * curl http://www.website.com/wp-cron.php?doing_wp_cron &>/dev/null

Using PHP CLI:

*/15 * * * * cd /home/user/public_html; php wp-cron.php &>/dev/null

Rocket-Nginx is configured using a rocket-nginx.ini file. You can add site-specific configurations by creating a new section. For example, to add a custom cookie that invalidates the cache:

[example.com : default]
cookie_invalidate[] = "my_custom_cookie"

Important: Every time you modify the .ini file, you must regenerate the Nginx configuration and reload the service:

1. Regenerate:

   php rocket-parser.php

2. Test Nginx config:

   nginx -t

3. Reload Nginx:

   service nginx reload

If you find that add_header directives are missing after enabling Rocket-Nginx, this is due to how Nginx manages headers. To fix this, use the 'hook' principle:

1. Define your custom headers in a separate configuration file.
2. Include that file within your Rocket-Nginx configuration.
3. If the header file is located outside the expected directory, you can use a symbolic link to ensure it is accessible.

Refer to the Configuration section of the documentation to identify the correct placement for these headers.

Encoded Slugs

Encoded slugs (e.g., non-Latin characters) may not be served correctly due to case-sensitivity differences between browsers and Nginx. Note: Version 3.1.0+ provides a preprocess.*.conf include to help mitigate this by forcing $rocket_uri_path to lowercase.

WebP Compatibility

Rocket-Nginx cannot serve WebP files generated by the WP Rocket WebP Compatibility feature. If this feature is enabled, Rocket-Nginx will bypass the cache and let WordPress/WP Rocket handle the request to ensure the correct image format is served.