- Publication issues
The topics in this article explain how to determine, diagnose, and fix issues that you might encounter when you use Staatic for WordPress.
Publication does not start
In order for the publication process to work, Staatic relies on a background processing library that enables it to execute the potentially long-running publication process in the background.
In order to facilitate background processing, it is essential for the site to have the capability to send a POST request to its Admin Ajax URL, by utilizing the WordPress HTTP API. This action serves the purpose of initiating the processing of any pending tasks that have been queued.
To verify if your site supports background processing, go to the Tools > Site Health page within WordPress Admin and make sure the following tests pass:
- Scheduled events are running
- HTTP requests seem to be working as expected
- Your site can perform loopback requests
Publication fails or does not finish
The most common reason for a publication to hang is a fatal error or time-out during the publication process, which the plugin was not able to handle gracefully.
To determine if an error is the cause of the publication hanging, you can temporarily enable
WP_DEBUG_LOG. This can be done be adding these lines to your
wp-config.php configuration file, see also Debugging in WordPress:
define ( 'WP_DEBUG', true ); define ( 'WP_DEBUG_LOG', true );
After having started a new publication and waiting for the publication to hang, you should be able to find the following file in your WordPress installation:
wp-content/debug.log. If an error is causing the hang, it should be visible within this file.
Note: make sure to disable
WP_DEBUGmode afterwards, in order to prevent sensitive details leaking into the static version of your site.
If the publication stalls due to a timeout, it’s likely Staatic couldn’t adjust the PHP time limit. This issue might arise from server constraints or elements like PHP-FPM, web servers, and load balancers. To resolve, consider raising these limits or reducing the Publication Task Timeout.
Here is an overview of some of the relevant configuration values:
pool configuration files
You can also opt for the WP-CLI Publish Command. This command executes the publication using a singular PHP process, unlike the web-based publisher. Often, the command-line presents fewer constraints.
UNIX-based systems, including Linux and macOS, provide tools to monitor and control the use of resources such as threads, files, and network connections for each process and user. The “ulimits” function ensures that individual users don’t overconsume these resources. However, if these limits are set too low by default, Staatic may face operational challenges. However, low default values of these limits may lead to various issues during the regular operation of Staatic.
A crucial parameter to watch is the “Number of open files” limit. It’s typically set at a default of 1,024. Given the themes, plugins, and customizations of your site, this default can be quickly surpassed. For smoother operation, we suggest adjusting this limit to a minimum of 4,096.
Note: when limits are exceeded, this can lead to the occurrence of seemingly random errors, such as those associated with non-existent PHP classes.
Publication takes too long
To generate the static version of your WordPress site, Staatic follows the same process as a regular visitor. However, this can be time-consuming, particularly when there are numerous pages and assets to process, and the server resources are limited. The involvement of WordPress, PHP, and the database during content generation contributes to the overall time taken.
The crawler process has been optimized as much as possible to limit the time necessary (especially when using our Staatic Cloud offering) and a quick-publish feature is available to publish only the content that has changed since the last publication. Nevertheless, additional manual optimization might be necessary.
Below are key areas you might consider optimizing:
Deactivate unused plugins
Disabling unnecessary plugins can reduce the utilization of server resources, resulting in improved crawling speed.
Decrease logging verbosity
It is recommended to set the Logging setting to either Minimal Logging or No Logging during normal operations. Increasing the verbosity level consumes more server resources and should be limited to troubleshooting sessions only.
Tune HTTP concurrency
HTTP concurrency refers to the number of pages that are crawled simultaneously. Adjusting the HTTP concurrency setting to your server’s available resources can help optimize the crawl rate.
Note: Always monitor the server’s CPU and memory usage when adjusting the HTTP concurrency. Overloading the server by setting an excessively high concurrency value can lead to request failures and HTTP 5xx responses. Such issues might negatively impact the final generated static site..
When using the Local Directory deployment method, and running on in Linux environment, it is recommended to enable the Symlink/Copy Uploads setting.
By doing so, during the publication process a symlink is created for the
wp-content/uploads directory. This ensures that all content of the uploads directory is available on the static site, without the need to crawl and process each individual file, greatly reducing the publication time.