grrr-amsterdam/simply-static-deploy

Deploy static WordPress sites easily to an AWS S3 bucket

v0.2.0 2020-03-19 08:57 UTC

This package is auto-updated.

Last update: 2020-03-19 08:58:57 UTC


README

Build Status

Deploy static sites easily to an AWS S3 bucket

  • Utilizes the excellent Simply Static plugin for static site generation.
  • Adds deployment to S3-compatible storage (AWS S3, DigitalOcean Spaces, ...).
  • Adds optional CloudFront CDN invalidation step.
  • Steps can be triggered via a simple user interface or programmatically.
  • Customizable using hooks and actions.

Built with ❤️ by GRRR.

Screenshot of Simply Static Deploy plugin interface for WordPress

Installation

Install via Composer:

$ composer require grrr-amsterdam/simply-static-deploy

This will install it in the plugin directory, assuming you have the right installer path configured in your composer.json:

"extra": {
  "installer-paths": {
    "web/app/plugins/{$name}/": ["type:wordpress-plugin"]
  }
}

Usage

First define SIMPLY_STATIC_DEPLOY_CONFIG in your WordPress configuration:

define('SIMPLY_STATIC_DEPLOY_CONFIG', [
    'aws' => [
        'key'           => '...', # AWS access key
        'secret'        => '...', # AWS secret key
        'region'        => '...', # AWS region
        'bucket'        => '...', # S3 bucket
        'bucket_acl'    => '...', # S3 bucket ACL (optional, defaults to `public-read`)
        'distribution'  => '...', # CloudFront distribution ID (optional, step is skipped when empty)
        'endpoint'      => '...', # For usage with providers other than AWS (optional)
    ],
    'url' => '...', # Website url (used for displaying url after deploy is finished)
]);

Then configure the Simply Static plugin via the admin interface, and hit Generate & Deploy in the Deploy tab.

Documentation

Available filters to modify settings and data passed to the plugin:

Available actions to invoke or act upon:

Available filters

Adjust additional files

Modify entries from the 'Additional Files and Directories' option. By default all paths are temporarily resolved to absolute paths via realpath, to ensure symbolic links are resolved. An array of unmodified files from the options is passed as an argument.

add_filter('simply_static_deploy_additional_files', function (array $files) {
    # Modify files, and possibly resolve paths with `realpath`.
    return $files;
});

Note: during generation of the static site, the additional_files setting is updated. It is restored when finished.

Adjust additional URLs

Modify entries from the 'Additional URLs' option. This can be useful to add pages that can't be found by Simply Static (not in the sitemap, are excluded by a password, have noindex, etc...). An array of unmodified URLs from the options is passed as an argument.

add_filter('simply_static_deploy_additional_urls', function (array $urls) {
    # Modify urls, for example by adding missing pages.
    return $urls;
});

Note: during generation of the static site, the additional_urls setting is updated. It is restored when finished.

Adjust PHP max execution time

Adjust the max_execution_time for the static site generation.

add_filter('simply_static_deploy_php_execution_time', function (int $time) {
    return 600;
});

Note: although this will increase the max_execution_time, it will not increase the execution time of your webserver. For Apache, you might have to increase the TimeOut Directive:

TimeOut 600

Enable static directory clearing

Clear the static folder before a new version is generated. Simply Static only allows you to delete the temporary files, but in some cases you might want to start with a clean slate (e.g. items deleted from the CMS, and a redirect being added in its place).

add_filter('simply_static_deploy_clear_directory', function (bool $value) {
    return true;
});

Note: this setting is explicitly set by a filter, since it will completely delete any folder set as the Local Directory.

Available actions

Handle errors

Called from the plugin, and receives a WP_Error object explaining the error. You can decide how to handle the error, for instance by logging it with a service of choice.

add_action('simply_static_deploy_error', function (\WP_Error $error) {
    # Handle the error.
});

Modify generated files

Called when Simply Static is done generating the static site. This allows you to modify the generated files before they're being deployed. The static site directory is passed as an argument.

add_action('simply_static_deploy_modify_generated_files', function (string $directory) {
    # Modify generated files, like renaming or moving them.
});

Schedule deploys

Schedule a deploy event.

Arguments:

  • Time: should be a simple time string, it is automatically converted to a UNIX timestamp in the configured WordPress timezone.
  • Interval: accepted values are hourly, twicedaily and daily. Can be extended via cron_schedules.
do_action('simply_static_deploy_schedule', '12:00', 'daily');

Note: it is important that WP-Cron is called regularly. You could do so by disabling the default WP-Cron mechanism and switch to calling it via a dedicated cronjob.

To disable the default WP–Cron (which is normally called when a user visits pages), add the following to your WordPress configuration:

define('DISABLE_WP_CRON', true);

Create a cronjob calling the WordPres WP-Cron. Setting it to every 5 minutes would be a good default. For example via crontab -e on a Linux machine:

*/5 * * * * curl https://example.com/wp/wp-cron.php?doing-cron > /dev/null 2>&1