As of February 2018, the most recent version (
v1.4.22) of the Staticfile buildpack has first-class support of custom error pages. You can now just enumerate various status codes and the page that you would like to display for them. Just add something like this to your
status_codes: 404: /path/to/404.html 500: /path/to/500.html
For my site, my
Staticfile now looks like this since my
404.html page is at the top level of my
root: public status_codes: 404: /404.html
The rest of the post still applies to older versions of the buildpack and still serves as an example of how to use the buildpack’s
error 404 - configuration options not found
Earlier this week I wrote about how to deploy a static site to Cloud Foundry, and once you’ve familiarized yourself with the basic of Cloud Foundry, it’s pretty darn simple. However, as I migrated one of my sites over from GitLab pages over to Pivotal Web Services I did run into one issue that was particularly annoying: my site was using the default NGINX 404 page and not my lovingly crafted
Now I figured this would be a simple fix. After all, Github pages will serve up a
404.html page automatically and even Amazon S3, despite its byzantine management console, makes it pretty intuitive to set up a “not found” document to serve. So I Googled.
And I didn’t have a whole lot of luck. I did see that you could replace the
nginx.conf that the Staticfile buildpack uses to deploy the NGINX server that serves up your static site, so I tried that. I used
cf ssh to ssh on to my app and downloaded copied the existing config so that I could append an
error_page declaration to it. This wasn’t ideal.
- This meant that I would no longer be able to automatically take advantage of improvements that the Staticfile buildpack might make to their
nginx.confin the future
- It also meant I had to get a bit too familiar with NGINX config to do something that should have been simple
There had to be an easier way. So I logged an issue to their project to request the ability to set a custom 404 page as a feature. They agreed that it might be valuable, but also let me know of a better way to do what I had already done.
configuring a custom 404 page
Turns out that you can include a
location_include directive in your
Staticfile (docs). This is a powerful directive that will pull in files specified from your
nginx/conf directory and include them in the generate
nginx.conf file here. So to get my site to serve my custom 404 page, I did the following:
1. Added an
nginx/conf/includes directory to the top-level of my project
2. Added an
error404.conf file to the
nginx/conf/includes directory that contained the following config:
This tells NGINX to look for a
/404.html page within its configured root (
_site for my example Jekyll site) that is set by the buildpack at the top of the NGINX
3. Added the following directives to my
This config instructs the Staticfile buildpack to set the Jekyll-generated
_site folder for the site as root and tells it to include every
.conf file within the
nginx/conf/includes directory that we created earlier. Make sure you include the
root directive since the docs mention that the buildpack requires it be configured alongside
location_include for it all to work properly.
After all that, just
cf push up your changes and your site should now be serving your custom 404 page instead of that nasty NGINX default.
Hopefully this will all be made simpler in the future, but in the meantime, this has been the simplest way I’ve found to add a custom 404 page to a static Cloud Foundry site. Thanks for following along!