LATEST VERSION: 1.9 - CHANGELOG
Pivotal Cloud Foundry v1.9

Staticfile Buildpack

Page last updated:

The Staticfile buildpack works for apps and content that require no backend code besides an Nginx webserver, which the buildpack provides. Examples include front-end JavaScript apps, static HTML content, and HTML/JavaScript forms. It also supports apps with backends hosted elsewhere.

To find which version of Nginx the current Staticfile buildpack uses, see the release notes.

Note: BOSH configured custom trusted certificates are not supported by the Staticfile buildpack.

Push an App

Follow the steps below to push an app using the Staticfile buildpack.

  1. Create a file named Staticfile in the root directory.

    $ touch Staticfile
    

  2. Push the app.

    $ cf push APPNAME -m 64M
    
    When using the -m 64M flag, static assets are served by Nginx, which only requires 20M. The -m 64M flag reduces the RAM allocation from the default 1G allocated to Cloud Foundry containers.

    Note: If you don’t have the buildpack or the installed version is out of date, use the latest version with the command: $ cf push APPNAME -b https://github.com/cloudfoundry/staticfile-buildpack.git

Test this procedure for yourself by creating a simple app that has an index.html file. You can push the app from the root directory.

$ echo 'Hello World' > index.html
$ touch Staticfile
$ cf push APPNAME -m 64M

Configure the Buildpack

You can configure how the Staticfile buildpack accesses and serves apps by editing the Staticfile or nginx.conf files.

Specify an Alternate Root Folder

By default, the buildpack serves index.html and all other assets from the root folder of your project.

In many cases, you may have an alternate folder where your HTML/CSS/JavaScript files are to be served from, such as dist/ or public/.

To configure the buildpack add the following line to your Staticfile:

root: dist

Enable or Disable Basic Authentication

Basic authentication for your app or website depends on whether you have a Staticfile.auth file in its root directory. If Staticfile.auth is present and contains hashed user/password pairs, basic auth is enabled. If this file is absent, the app is unprotected.

Basic Authentication

Follow these steps to enable basic auth:

  1. Convert the username / password to the required format: http://www.htaccesstools.com/htpasswd-generator/ For example, username bob and password bob becomes bob:$apr1$DuUQEQp8$ZccZCHQElNSjrg.erwSFC0.

  2. Create a file in the root of your application Staticfile.auth. This becomes the .htpasswd file for Nginx to project your site. It can include one or more user/password lines.

    bob:$apr1$DuUQEQp8$ZccZCHQElNSjrg.erwSFC0
    
  3. Push your application to apply changes to basic auth.

To disable basic auth, remove Staticfile.auth and push.

Display a Directory List Instead of 404

If your site doesn’t have an index.html, you can configure Staticfile to display a Directory Index of other files instead of a standard 404 error.

Directory Index

Add a line to your Staticfile that begins with directory:

directory: visible

Enable Server Side Includes (SSI)

Add the following line to your Staticfile to enable support for SSI:

ssi: enabled

Enable Pushstate Routing

With client-side JavaScript apps that serve multiple routes, pushstate routing keeps browser-visible URLs clean. For example, pushstate routing allows a single JavaScript file route to multiple anchor-tagged URLs that look like /some/path1 instead of /some#path1.

To enable support for pushstate routing, add the following line to your Staticfile:

pushstate: enabled

Disable Serving and Decompressing GZip Files

The gzip_static and gunzip modules are set to on by default. gzip_static enables Nginx to serve files stored in compressed .gz format, and gunzip uncompresses them for clients that do not support compressed content or responses.

To disable these modules, specify the following in your custom nginx.conf:

gunzip off;
gzip_static off;

Enable Force HTTPS

To only allow requests sent via HTTPS, set the FORCE_HTTPS environment variable. This redirects non-HTTPS requests as HTTPS requests.

The value that FORCE_HTTPS is set to does not matter, only that the environment variable is set. For example, FORCE_HTTPS: true and FORCE_HTTPS: enabled both force HTTPS.

Note: If you are using a reverse proxy like CloudFlare and have rules that redirect HTTP to HTTPS, these can cause redirect loops with your app if FORCE_HTTPS is also enabled. In the example of CloudFlare, when attempting to make an HTTPS request to the app, the connection between the user and CloudFlare is HTTPS but the connection between CloudFlare and your app is via HTTP, which your app then redirects as HTTPS.

Enable HTTP Strict Transport Security

To enable HTTP Strict Transport Security (HSTS), add the following line to your Staticfile:

http_strict_transport_security: true

This causes Nginx to respond to all requests with the header:

Strict-Transport-Security: max-age=31536000

Note: This header causes a browser that receives it to make all future requests over HTTPS. Because of the long amount of time this setting persists in the browser, only enable this setting once you are sure that everything is properly configured.

Custom Nginx Configuration

You can customize the Nginx configuration further, by adding nginx.conf and mime.types to your root folder. If you specified an alternate root folder, the files must be placed there.

If the buildpack detects either of these files, they are used in place of the built-in versions.

Enable Proxy Support

If you need to use a proxy to download dependencies during staging, you can set the http_proxy and https_proxy environment variables. For more information, see the Proxy Usage Docs.

Help and Support

Join the #buildpacks channel in our Slack community if you need any further assistance.

For more information about using and extending the Staticfile buildpack in Cloud Foundry, see the staticfile-buildpack GitHub repo.

You can find current information about this buildpack on the Staticfile buildpack release page in GitHub.

Was this helpful?
What can we do to improve?
View the source for this page in GitHub