WordPress

Wordpress is a self-hosted content management web application, especially designed for blogging but also a good start to create your own website. It can customized with themes and an in-build site editor and further extended with plugins.

Installation

Note: Parts of this instruction and module are not yet stable and will be available in the upcoming NixOS 22.11 release.

A simple local setup of Wordpress can be enabled with the following setup

services.wordpress.sites."localhost" = {};

Visit http://localhost to setup your new Wordpress instance. By default, a Mysql server is configured automatically so you won't have to setup the database backend.

Configuration

Language

The default language of the Wordpress module will be English. It is possible to enable additional language support for languages which are already packaged. Using extraConfig you can configure the default language. In this example, we're going to enable the German language.

services.wordpress.sites."localhost" = {
  languages = [ pkgs.wordpressPackages.languages.de_DE ];
  extraConfig = ''
    define ('WPLANG', 'de_DE');
  '';
};

Alternatively you can package your own language files following this example:

{ pkgs, ... }: let

  wordpress-language-de = pkgs.stdenv.mkDerivation {
    name = "wordpress-${pkgs.wordpress.version}-language-de";
    src = pkgs.fetchurl {
      url = "https://de.wordpress.org/wordpress-${pkgs.wordpress.version}-de_DE.tar.gz";
      sha256 = "sha256-dlas0rXTSV4JAl8f/UyMbig57yURRYRhTMtJwF9g8h0=";
    };
    installPhase = "mkdir -p $out; cp -r ./wp-content/languages/* $out/";
  };

in {

  services.wordpress.sites."localhost".languages = [ wordpress-language-de ];

}

Consult the translation portal of Wordpress for the specific country and language codes available. This example is using the code de_DE (Germany/German) in the source URL and also the extraConfig part.

Themes and plugins

Themes and plugins which are already packaged can be integrated like this:

services.wordpress.sites."localhost" = {
  themes = [ pkgs.wordpressPackages.themes.twentytwentytwo ];
  plugins = with pkgs.wordpressPackages.plugins; [
    antispam-bee
    opengraph
  ];
};

Manually package a Wordpress theme or plugin can be accomplished like this:

let

wordpress-theme-responsive = pkgs.stdenv.mkDerivation {
  name = "responsive";
  src = pkgs.fetchurl {
    url = http://wordpress.org/themes/download/responsive.1.9.7.6.zip;
    sha256 = "06i26xlc5kdnx903b1gfvnysx49fb4kh4pixn89qii3a30fgd8r8";
  };
  buildInputs = [ pkgs.unzip ];
  installPhase = "mkdir -p $out; cp -R * $out/";
};

in {

  services.wordpress.sites."localhost" = {
    themes = [ wordpress-theme-responsive ];
  };

}

You can package any available Wordpress extension, for example from the official theme or plugin repository. Be sure to replace the name, url and sha256 part according to your desired extension.

If you want to automatically enable and activate the responsive theme, add this extraConfig line

extraConfig = ''
  define ('WP_DEFAULT_THEME', 'responsive');
'';

In case you want to automatically enable and activate the plugin, in this example akismet, you can add following to extraConfig

extraConfig = ''
  if ( !defined('ABSPATH') )
    define('ABSPATH', dirname(__FILE__) . '/');
  require_once(ABSPATH . 'wp-settings.php');
  require_once ABSPATH . 'wp-admin/includes/plugin.php';
  activate_plugin( 'akismet/akismet.php' );
'';

Mail delivery

Mail clients like Msmtp can be used to configure mail delivery for Wordpress. This can be useful for sending registration mails or notifications for new comments etc.

By default Wordpress will use the sender mail wordpress@example.org where example.org is the primary domain name configured for the Wordpress instance. By installing and using the plugin static-mail-sender-configurator it is possible to declaratively configure and change the sender address, for example to noreply@example.org.

services.wordpress.sites."example.org" = {
  plugins = [ pkgs.wordpressPackages.plugins.static-mail-sender-configurator ];
  extraConfig = ''
      // Enable the plugin 
      if ( !defined('ABSPATH') )
        define('ABSPATH', dirname(__FILE__) . '/');
      require_once(ABSPATH . 'wp-settings.php');
      require_once ABSPATH . 'wp-admin/includes/plugin.php';
      activate_plugin( 'wordpress-plugin-static-mail-sender-configurator-${pkgs.wordpressPackages.plugins.static-mail-sender-configurator.version}/static-mail-sender-configurator.php' );

    // Change sender mail address
    define ('WP_MAIL_FROM', 'noreply@localhost');
  '';
};

Tips and tricks

Force https-URLs behind reverse proxy

In case you're running Wordpress behind a reverse proxy which offers a SSL/https connection to the outside, you can force Wordpress to use the https protocol

services.wordpress.sites."localhost".extraConfig = ''
  // Needed to run behind reverse proxy
  define('FORCE_SSL_ADMIN', true);
  $_SERVER['HTTPS']='on';
'';

Search engine optimization (SEO)

Meta information

To be done

services.wordpress.sites."example.org" = {
  plugins = [ pkgs.wordpressPackages.plugins.wordpress-seo ];
};

Picture compression

To be done

services.wordpress.sites."example.org" = {
  plugins = [ pkgs.wordpressPackages.plugins.webp-express ];
};

Lazy load images

Using the Wordpress plugin Jetpack, it is possible to enable lazy loading of images. That means, images only visible in the current view of the web browser are loaded. This will speed up initial page load.

services.wordpress.sites."example.org" = {
  plugins = [ pkgs.wordpressPackages.plugins.jetpack ];
};

After enabling the plugin, in the Wordpress admin interface go to Jetpack -> Settings -> Performance and ensure that lazy loading of Images is enabled. Note that Jetpack comes with a lot of optional modules which should be disabled if not used. On the same page go to Debug in the bottom menu and click on the last link offering the list of all modules. Disable all modules you don't need instead of Lazy Images.

Webserver compression

services.nginx.extraConfig = ''
  gzip on;
  gzip_vary on;
  gzip_comp_level 4;
  gzip_min_length 256;
  gzip_proxied expired no-cache no-store private no_last_modified no_etag auth;
  gzip_types application/atom+xml application/javascript application/json application/ld+json application/manifest+json application/rss+xml application/vnd.geo+json application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/bmp image/svg+xml image/x-icon text/cache-manifest text/css text/plain text/vcard text/vnd.rim.location.xloc text/vtt text/x-component text/x-cross-domain-policy;
'';

Troubleshooting

Enable logging

To enable logging add the following lines to extraConfig

services.wordpress.sites."localhost".extraConfig = ''
  define( 'WP_DEBUG', true );
  define( 'WP_DEBUG_LOG', true );
  ini_set( 'error_log', '/var/lib/wordpress/localhost/debug.log' );
'';

Since the default location to the folder wp-content is not writable, we redirect the log file path to /var/lib/wordpress/localhost/debug.log. All error messages will be stored there. Change the folder name localhost to the name of your site.

In case you want to print error messages directly in your browser, append following line

services.wordpress.sites."localhost".extraConfig = ''
  @ini_set( 'display_errors', 1 );
'';

Please note that this exposes sensible information about your server setup therefore this option should not be enabled in production.