LATEST VERSION: 1.10 - CHANGELOG
Pivotal Cloud Foundry v1.10

Staticfile Buildpack

Page last updated:

Overview

This topic describes how to configure the Staticfile buildpack and use it to push static content to the web. It also shows you how to serve a simple “Hello World” page using the Staticfile buildpack.

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

Definitions

Staticfile app: An app or content that requires no backend code other than the NGINX webserver, which the buildpack provides. Examples of staticfile apps are front-end JavaScript apps, static HTML content, and HTML/JavaScript forms.

Staticfile buildpack: The buildpack that provides runtime support for staticfile apps and apps with backends hosted elsewhere. To find which version of NGINX the current Staticfile buildpack uses, see the Staticfile buildpack release notes.

Staticfile Requirement

Elastic Runtime requires a file named Staticfile in the root directory of the app to use the Staticfile buildpack with the app.

Memory Usage

NGINX requires 20 MB of RAM to serve static assets. When using the Staticfile buildpack, we recommend pushing apps with the -m 64 M option to reduce RAM allocation from the default 1 GB allocated to containers by default.

“Hello World” Tutorial

Follow the procedure below to create and push a single page app using the Staticfile buildpack.

StepAction
1 Create and move into a root directory for the sample app in your workspace:
$ mkdir sample
$ cd sample
2 Create an index.html file that contains some text:
$ echo 'Hello World' > index.html
3 Create an empty file named Staticfile:
$ touch Staticfile
4 Use the cf login command to log in to Elastic Runtime.
For more information, see the Login section of the Getting Started with the cf CLI documentation.
$ cf login
5 Push the sample app:
$ cf push hello -m 64M
6 Find the URL of the app in the output.
A fragment of output is shown below:
Creating app hello in org sample-org / space sample-space as username@example.com...
OK
…
requested state: started
instances: 1/1
usage: 64M x 1 instances
urls: hello.example.com
7 Navigate to the URL to see the sample app running.

Configuring the Buildpack and Pushing the App

This section describes various ways you can configure the Staticfile buildpack options and how to push your Staticfile app.

Configuration Options

This table describes some of the aspects of the Staticfile buildpack that you can configure.

Options Description
Alternative root Allows you to specify a root directory other than the default, which is index.html. For example, you can specify that the buildpack serves index.html and all other assets from an alternate folder where your HTML/CSS/JavaScript files exist, such as dist/ or public/.
Directory list An HTML page that displays a directory index for your site. A sample of a directory list is shown below.
directory index
If your site is missing an index.html, your app displays a directory list instead of the standard 404 error page.
SSI Server Side Includes (SSI) allows you to show the contents of files on a web page on the web server. For general information about SSI, see the Server Side Includes entry on Wikipedia.
Pushstate routing Keeps browser-visible URLs clean for client-side JavaScript apps that serve multiple routes. For example, pushstate routing allows a single JavaScript file route to multiple anchor-tagged URLs that look like /some/path1 instead of /some#path1.
GZip file serving and compressing The gzip_static and gunzip modules are enabled by default. This allows NGINX to serve files stored in compressed GZ format, and to uncompresses them for clients that do not support compressed content or responses.
You may want to disable compression in particular circumstances, for example if serving to very old browser clients.
Basic authentication Allows you to place simple access controls on your app.
Proxy support Allows you to use a proxy to download dependencies during staging.
Force HTTPS A way to enforce that all requests are sent through HTTPS. This redirects non-HTTPS requests as HTTPS requests. For an example of when to avoid forcing HTTPS, see About FORCE_HTTPS with Reverse Proxies.
Dot Files By default, hidden files (those starting with a .) are not served by this buildpack.
HTTP Strict Transport Security Causes NGINX to respond to all requests with the header Strict-Transport-Security: max-age=31536000. This forces browsers to make all subsequent requests over HTTPS.
Custom Location configuration To customize the location block of the NGINX configuration file, follow these steps:

  1. Create a file with location scoped NGINX directives. See the following example, which causes visitors of your site to receive the X-MySiteName HTTP header:

    File: nginx/conf/includes/custom_header.conf
    Content: add_header X-MySiteName BestSiteEver;

  2. Set the location_include variable in your Staticfile to the path of the file from the previous step:
    ...
    location_include: includes/*.conf
    ...


For information about NGINX directives, see NGINX documentation.
Custom NGINX configuration Additional NGINX configuration can be applied, such as mapping file extensions to mime types. See the NGINX documentation for examples.

Configure Your App

  1. In the root directory of your app, create an empty file named Staticfile:

    $ touch Staticfile
    

  2. Configure the Staticfile buildpack for the needs of your app.

    If you want to… Then…More information
    serve index.html and other assets from a location other than the root directory add this line to the Staticfile:
    root: YOUR-DIRECTORY-NAME

    For example, root: public
    Alternative root
    display a directory list instead of the standard 404 error add this line to the Staticfile:
    directory: visible
    Directory list
    enable SSI add this line to the Staticfile:
    ssi: enabled
    SSI
    enable pushstate routing add this line to the Staticfile:
    pushstate: enabled
    Pushstate routing
    disable gzip_static and gunzip modules add this line to the Staticfile:
    directory: visible
    GZip
    enable basic authentication for your app or website 1. Create a hashed username and password pair for each user, using a site like Htpasswd Generator
    2. Create a file named Staticfile.auth in the root directory or alternative root directory, and add one or more user/password lines to it. For example,
    bob:$apr1$DuUQEQp8$ZccZCHQElNSjrgerwSFC0
    alice:$apr1$4IRQGcD/$UMFLnIHSD9ZHJ86TR4zx

    Basic authentication
    use a proxy for downloading dependencies during staging set the http_proxy and https_proxy environment variables. Proxy support
    force HTTPS set the FORCE_HTTPS environment variable to true.

    Note: Do not enable FORCE_HTTPS if you have a proxy server or load balancer that terminates SSL/TLS. Doing so can cause infinite redirect loops, for example, if you use Flexible SSL with CloudFlare.

    Force HTTPS
    host dot files To enable serving hidden (dot files), use host_dot_files: true in the Staticfile. Dot Files
    force the receiving browser to make subsequent requests over HTTPS add this line to the Staticfile:
    http_strict_transport_security: true

    Note: Because this setting persists in browsers for a long time, only enable this setting after ensuring you have completed your configuration.

    HTTP Strict Transport Security
    make additional configuration changes to NGINX add nginx.conf and mime.types files to your root folder, or to the alternate root folder if you specified one. NGINX documentation

Push Your App

Follow the steps below to push your application.

Step Action
1. Use the cf push APP_NAME -m 64M command to push your app. Replace APP_NAME with the name you want to give your application. For example:
$ cf push my-app -m 64M
Creating app my-app in org sample-org / space sample-space as username@example.com...
OK
…
requested state: started
instances: 1/1
usage: 64M x 1 instances
urls: my-app.example.com
Or, if you do not have the buildpack, or the installed version is out-of-date, use the -b option to specify the buildpack as follows:
cf push APP_NAME -b https://github.com/cloudfoundry/staticfile-buildpack.git
2. Find the URL of your app in the output from the push command and navigate to it to see your static app running.

Help and Support

A number of channels exist where you can get more help when using the Staticfile buildpack, or with developing your own Staticfile buildpack.

  • Staticfile Buildpack Repository in Github: Find more information about using and extending the Staticfile buildpack in GitHub repository.

  • Release Notes: Find current information about this buildpack on the Staticfile buildpack release page in GitHub.

  • Slack: Join the #buildpacks channel in our Slack community.

Create a pull request or raise an issue on the source for this page in GitHub