grafted-in / wordpress-nginx-nix

One-stop shop for defining, testing, and deploying a WordPress CMS site using Nginx with Nix, NixOps, and NixOS

Nix Setup for Wordpress CMS

This repository contains everything necessary to test and deploy fully operational web servers for Wordpress CMS sites.

This setup uses the powerful Nix package management system and its accompanying toolset:

• NixOps for deployments
• NixOS as the Linux-based server OS

Note: Nix does not support Windows. If you're on Windows, you'll need to run this from within a Virtual Machine (VM).

With this setup, you can easily deploy your site to one or more servers with minimal effort. You can (and should) also deploy to local VirtualBox virtual machines. And, you can even use the Nix packages to install the site directly on your local host.

Features

• Automatically builds a working server with Nginx, PHP-FPM, MySQL, and WordPress.
• Automatically configures TLS/SSL using Let's Encrypt.
• Configures PHP OpCache and a WordPress plugin to manage it.
• Configures Nginx Fastcgi-cache with a cache-purging module and a WordPress plugin to manage it.
• Installs and configures Google's PageSpeed Nginx module.
• Allows WordPress configuration (settings, versions, plugins, themes, etc.) to be managed entirely by Nix. This means:
  • Upgrades and changes can be tracked in version control.
  • Deployments are reproducible for testing (e.g. in VirtualBox or on a staging server).
  • Security is enhanced by having most PHP files read-only.
• Highly configurable: most of these settings can be tweaked easily.

Requirements

1. First install Nix. It is not invasive and can be removed easily if you change your mind (using rm -r /nix).
2. Deployments are done with NixOps. You can install nixops with nix by running nix-env -i nixops. However, you don't need to because this repository has a deploy/manage script that you'll use which will run nixops tasks for you.
3. Install VirtualBox in order to test your server deployments.
4. If you plan to deploy to a real server, you will likely need to keep secrets in this repository. That will require installing git-crypt and setting it up. See SETUP-SECRETS.md for information on that.

Attention macOS Users!

This project requires that you build Linux binaries which can be deployed to a server (VirtualBox or otherwise). Since macOS cannot natively build Linux binaries, you will need a NixOS build slave running.

1. Install Docker and then use this script to set up a NixOS build slave. For example: * source <(curl -fsSL https://raw.githubusercontent.com/LnL7/nix-docker/master/start-docker-nix-build-slave) * deploy/manage vbox deploy (or some other deployment command)
2. If you can't/don't want to install Docker, you can use NixOps to create a NixOS build slave via VirtualBox using this. Note that using Docker is almost certainly going to be easier so I recommend that way instead.

Setting Up WordPress

1. Create unique WordPress keys for your site (must be in the same directory as default-app-config.nix):
   • curl https://api.wordpress.org/secret-key/1.1/salt/ > wordpress-keys.php.secret.
2. Configure your site by editing default-app-config.nix.
   • For automatic install using WP-CLI:
     • Configure the autoInstall section to use enable = true;.
     • Copy ./wordpress-admin.keys.nix.sample to ./wordpress-admin.keys.nix and replace ... with your credentials.
   • For a traditional install where WordPress is entirely managed by the admin panel, use freezeWordPress = false;.
   • To have Nix manage themes but not plugins, you can use freezeWordPress = true; freezeThemes = true; freezePlugins = false;.
   • When WordPress is frozen (i.e. managed by Nix), use wordpress.nix to govern the installed version.
   • When plugins are frozen (i.e. managed by Nix), use plugins.nix to govern which plugins are installed.
   • When themes are frozen (i.e. managed by Nix), use themes.nix to govern which themes are installed.
3. More complex settings can be managed in server/.
   • For example, change PHP-FPM configuration in server/php-fpm-config.nix.

Deploying to VirtualBox

Create a VirtualBox deployment:

1. deploy/manage vbox create '<server/logical.vbox.nix>' '<server/physical.vbox.nix>'
2. deploy/manage vbox deploy

Notes:

• nixops deployments can sometimes be finicky. If something hangs or fails, try running it again. It is a very deterministic system so this should not be a problem.
• Run deploy/manage --help to see all options (this is just nixops underneath).

You should then be able to open the IP of the VM in your browser and test it. If you don't know the IP, run deploy/manage vbox info.

Troubleshooting

• If you're on macOS (Darwin), be sure you have a NixOS build slave set up as described above.
• If the state of your VirtualBox VM changes in a way that nixops didn't notice, your deployments may fail. Try running deploy/manage deploy -d vbox --check (using the --check flag) to tell nixops to reassess the state of the machine.
• Sometimes VirtualBox will give your machine a new IP. If this happens, nixops (i.e. the manage script) may fail to connect to your machine via SSH. If this happens, remove the line with the old IP from your ~/.ssh/known_hosts file and try again with the --check flag.
• Sometimes nixops will fail to deploy because a VirtualBox disk from a previous deploy is still registered. To fix this, take the given disk UUID and run VBoxManage closemedium disk <disk UUID> --delete.

Deploying to Real Servers

With this setup you can deploy to any PaaS/IaaS service supported by nixops. Right now this repository contains prewritten configurations for

• Google Cloud Compute's Google Compute Engine (GCE) - see DEPLOY-GCE.md.
• DigitalOcean - see DEPLOY-DIGITAL-OCEAN.md.

We plan to add more (such as AWS) in the future. If you want to do it yourself and understand Nix, the work to add this configuration is minimal. Pull requests welcome!

NOTE: When SSL/TLS is enabled for production servers, the first deployment may take a long time (i.e. more than 20 minutes) to finish. A large chunk of first-deployment time will be spent generating new DH parameters for Nginx. This is normal!

Keeping Secrets

This repository setup assumes you want to keep some things a secret. See SETUP-SECRETS.md for a rundown of how that works.

Upgrading Nixpkgs

All dependencies are fixed to a specific version of Nixpkgs which is configured in deploy/nixpkgs-version.nix which contains instructions for upgrading. The nixpkgs version also governs the version of NixOps to use during deployments. This can be overridden in nixpkgs-version.sh.

Acknowledgements

• The server setup is highly influenced by
  • https://github.com/nystudio107/nginx-craft
  • https://www.nginx.com/blog/9-tips-for-improving-wordpress-performance-with-nginx/
  • https://easyengine.io/wordpress-nginx/tutorials/single-site/fastcgi-cache-with-purging/
• Special thanks to @khalwat

wordpress-nginx-nix's Issues

Add rolling backups module

I've written a lot of functions to set up rolling backups that could be generally useful. I need to turn them into a NixOS module and include them here, or via some other repo.

Skip WP installation

@3noch Is it possible to configure the site from the configuration (Site title, Username, etc)? Now I get the installation wizard asking me to setup the site.

Edit: I'm thinking something like this, but realising that this is out of scope. Nice to have :)

Use a nix file to pin nixpkgs

Right now nixpkgs is pinned by the nixpkgs-version.sh script as part of deploy/manage. This works but it's not possible to refer to that nixpkgs version from within a nix derivation. This makes it hard to create a fully pinned repo. Move the nixpkgs version to a .nix file and import it in the deploy/manage script.

Attempt to call something which is not a function but a set

This seems like a very interesting repo, however I'm having some trouble getting it to run on Virtualbox on my mac. I'm new to Nix, so maybe I'm missing something. Any help would be appreciated.

deploy/manage vbox create '<server/logical.vbox.nix>' '<server/physical.vbox.nix>'
created deployment ‘7c1eaaf3...'

deploy/manage vbox deploy
error: attempt to call something which is not a function but a set, at ... wordpress-nginx-nix/server/physical.vbox.nix:1:6

deploy/manage vbox deploy --show-trace
error: while evaluating ‘flip’ at /nix/store/1lgppap4jzgw7gq8zdnma4pfcsm1ggqq-nixexprs.tar.xz/lib/trivial.nix:82:16, called from /nix/store/acwqszlzgai4h1dl8rvspbd439l633va-1gy62jcxjc09n9gk0ns4qk3d9b9kcda7-nixops-1.5pre2121_fc43d9c/share/nix/nixops/eval-machine-info.nix:264:7:
while evaluating ‘mapAttrs’ at /nix/store/1lgppap4jzgw7gq8zdnma4pfcsm1ggqq-nixexprs.tar.xz/lib/attrsets.nix:198:17, called from /nix/store/1lgppap4jzgw7gq8zdnma4pfcsm1ggqq-nixexprs.tar.xz/lib/trivial.nix:82:19:
while evaluating ‘zipAttrsWith’ at /nix/store/1lgppap4jzgw7gq8zdnma4pfcsm1ggqq-nixexprs.tar.xz/lib/attrsets.nix:346:21, called from /nix/store/acwqszlzgai4h1dl8rvspbd439l633va-1gy62jcxjc09n9gk0ns4qk3d9b9kcda7-nixops-1.5pre2121_fc43d9c/share/nix/nixops/eval-machine-info.nix:31:13:
while evaluating ‘zipAttrsWithNames’ at /nix/store/1lgppap4jzgw7gq8zdnma4pfcsm1ggqq-nixexprs.tar.xz/lib/attrsets.nix:331:33, called from /nix/store/1lgppap4jzgw7gq8zdnma4pfcsm1ggqq-nixexprs.tar.xz/lib/attrsets.nix:346:27:
while evaluating ‘concatMap’ at /nix/store/1lgppap4jzgw7gq8zdnma4pfcsm1ggqq-nixexprs.tar.xz/lib/lists.nix:79:18, called from /nix/store/1lgppap4jzgw7gq8zdnma4pfcsm1ggqq-nixexprs.tar.xz/lib/attrsets.nix:346:46:
while evaluating ‘operator’ at /nix/store/acwqszlzgai4h1dl8rvspbd439l633va-1gy62jcxjc09n9gk0ns4qk3d9b9kcda7-nixops-1.5pre2121_fc43d9c/share/nix/nixops/eval-machine-info.nix:25:20, called from undefined position:
while evaluating ‘getNetworkFromExpr’ at /nix/store/acwqszlzgai4h1dl8rvspbd439l633va-1gy62jcxjc09n9gk0ns4qk3d9b9kcda7-nixops-1.5pre2121_fc43d9c/share/nix/nixops/eval-machine-info.nix:18:28, called from /nix/store/acwqszlzgai4h1dl8rvspbd439l633va-1gy62jcxjc09n9gk0ns4qk3d9b9kcda7-nixops-1.5pre2121_fc43d9c/share/nix/nixops/eval-machine-info.nix:25:45:
while evaluating ‘call’ at /nix/store/acwqszlzgai4h1dl8rvspbd439l633va-1gy62jcxjc09n9gk0ns4qk3d9b9kcda7-nixops-1.5pre2121_fc43d9c/share/nix/nixops/eval-machine-info.nix:29:10, called from /nix/store/acwqszlzgai4h1dl8rvspbd439l633va-1gy62jcxjc09n9gk0ns4qk3d9b9kcda7-nixops-1.5pre2121_fc43d9c/share/nix/nixops/eval-machine-info.nix:19:10:
while evaluating the file ‘... wordpress-nginx-nix/server/physical.vbox.nix’:
attempt to call something which is not a function but a set, at ... wordpress-nginx-nix/server/physical.vbox.nix:1:6
error: evaluation of the deployment specification failed

macOS 10.12.3
nix-env (Nix) 1.11.6
NixOps 1.5 (installed prior to finding this repo)
Virtualbox 5.0.16r105871

Add support for secure redirection

Redirecting from http://www.site.com to https://site.com works, but not https://www.site.com to https://site.com. This is easy to add, just need to do it.

Plugin activation

@3noch Regarding #14 and plugin activation. I would use wp-cli for this as well and extend the install script. You could either pass a list of plugins to activate or activate them all with the --all option.

Move all secrets to a common directory?

@niklaswallerstedt had the idea of putting all files that need to be kept secret in one directory. This would remove a some complexity and add predictability. Up till now I've been relying on git-crypt status -e to tell me what files are encrypted, which works pretty well. But there is an advantage to having a very simple scheme to know which files will be encrypted and which ones won't. Another possible benefit to putting everything in one directory is that it would make it much easier to pull those files out into submodule, which could be a git repo with different permissions. It could even be symlinked to a vault of some sort.

The only downside is that it's a bit more awkward to reference several totally unrelated files that are all in one directory. The natural organization scheme you'd expect gets broken. I'm not sure this is a meaningful problem though in a small project like this.

Any other thoughts?

Make max upload size configurable

I just need to port these changes to this template.

Demo how to use this setup for a site without copying the code

With nix or subrepos it's entirely possible to create a site configuration that doesn't require you to copy this entire repo's source code into a new repo. That would be preferable for simple sites since they can effectively avoid "forking" this code base and continue to benefit from future enhancements/fixes.

The README needs to show how to do this.

Traditional website setup includes symlinks which can't be upgraded

Somehow I'm leaving symlinks to plugins and themes even when the site is built with traditional setup (non-frozen).

Update to use NixOS 17.09

Some significant changes were made to how PHP-FPM is served and I think it may require some refactoring to support it.

Document macOS deployment

Add automatic configuration of DH params

The new dhparams module lets us get better security with almost no extra work. We need to use it in this template. I'm already using it for my sites.

Any way to deploy on replit?

Any way to deploy on replit?