Staticfile Buildpack

Page last updated:

Overview

This topic describes how to configure and use 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 Detection

If you create a file named Staticfile in the root directory of your app, Cloud Foundry automatically uses the Staticfile buildpack when you push your app.

The Staticfile file can be an empty file, or it can contain configuration settings for your app. For more information, see Configuring the Buildpack and Pushing an 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 64M option to reduce RAM allocation from the default 1 GB allocated to containers by default.

Configure the Buildpack

This section describes configuration options available for the Staticfile buildpack. If you need to make configuration changes to NGINX that are not listed in the table below, use the NGINX Buildpack instead of the Staticfile buildpack. For more information, see NGINX Buildpack.

Staticfile File Configuration

To configure these options, add the configuration property as a new line in your Staticfile file as described in the following table.

Staticfile Configuration Property Description
root: YOUR-DIRECTORY-NAME

Example:
root: public
Alternative root: Specifies a root directory other than the default. Use this option to serve index.html and other assets, such as HTML, CSS, or JavaScript files, from a location other than the root directory.

For example, you can specify an alternate folder such as dist or public.
directory: visible Directory list: Displays an HTML page that shows 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 file, your app displays a directory list instead of the standard 404 error page.
ssi: enabled SSI: Enables Server Side Includes (SSI), which allow you to embed the contents of one or more files into a web page on a web server. For general information about SSI, see the Server Side Includes entry on Wikipedia.
pushstate: enabled 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 to route to multiple anchor-tagged URLs that look like /some/path1 instead of /some#path1.
gzip: off GZip file serving and compression: Disables gzip_static and gunzip modules, which are enabled by default. These modules allow NGINX to serve files stored in compressed GZ format and to uncompress them for clients that do not support compressed content or responses.

You may want to disable compression under particular circumstances such as serving content to very old browser clients.
http_proxy: HTTP-URL
https_proxy: HTTPS-URL

Example:
http_proxy: http://www.example.com/
https_proxy: https://www.example.com/
Proxy support: Allows you to use a proxy when downloading dependencies during the staging of your app.
force_https: true

Alternatively, set the FORCE_HTTPS environment variable to true.
Force HTTPS: Forces all requests to be sent through HTTPS. This redirects non-HTTPS requests as HTTPS requests.

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.

host_dot_files: true Dot files: By default, hidden files, which are those starting with a ., are not served by this buildpack.
http_strict_transport_security: true HTTP Strict Transport Security (HSTS): Causes NGINX to respond to all requests with the header Strict-Transport-Security: max-age=31536000. This forces receiving browsers to make all subsequent requests over HTTPS. This setting defaults to a max-age of one year.

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

http_strict_transport_security_include_subdomains: true HSTS includes subdomains: Causes NGINX to respond to all requests with the following header: Strict-Transport-Security: max-age=31536000; includeSubDomains
This forces browsers to make all subsequent requests over HTTPS including subdomains. This setting defaults to a max-age of one year.

Note: Setting this property to true also makes http_strict_transport_security default to true.

http_strict_transport_security_preload: true HSTS preload: Causes NGINX to respond to all requests with the following header: Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
This forces browsers to make all subsequent requests over HTTPS including subdomains and requests inclusion in browser-managed HSTS preload lists. For more information, see https://hstspreload.org. This setting defaults to a max-age of one year. This setting defaults to a max-age of one year.

Note: Setting this property to true also makes http_strict_transport_security and http_strict_transport_security_include_subdomains default to true.

Other Configuration

Follow the instructions below to make other configuration changes.


Basic Authentication

Allows you to enable basic authentication for your app or website. A sample basic authentication dialog box is shown below:

You can create a hashed username and password pair for each user by using a site like Htpasswd Generator.

Configuration

Add a new Staticfile.auth file to the root or alternative root directory. In the new file, add one or more username and password entries using the following format: USERNAME:HASHED_PASSWORD

Example:

pat:$example1$DuUQEQp8$ZccZCHQElNSjrgerwSFC0
stevie:$example1$22derfaecZSJJRw4rKE$KKEWKSK


Custom Location

Allows you to specify custom location definitions with additional directives. For information about NGINX directives, see Creating NGINX Plus and NGINX Configuration Files and Alphabetical index of directives in the NGINX documentation.

Configuration

To customize the location block of the NGINX configuration file, follow the steps below.

  1. Set an alternative root directory. The location_include property only works in conjunction with an alternative root.

  2. 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;
  3. Set the location_include variable in your Staticfile to the path of the file from the previous step. This path is relative to nginx/conf.

    Example:

    ...
    root: public
    location_include: includes/*.conf
    ...
    


Additional MIME Type Support

Allows you to configure additional MIME types on your NGINX server.

Configuration

To add MIME types, add a mime.types file to your root folder, or to the alternate root folder if you specified one.

For more information about the mime.types file, see mime.types in the NGINX documentation.

Example MIME types file:

types {
    text/html     html htm shtml;
    text/css      css;
    text/xml      xml rss;
    image/gif     gif;
    ...
    }


Push an App

To push your app, you can use either the system Staticfile buildpack or specify a Staticfile buildpack.

Option 1: Use the System Staticfile Buildpack

To use the Staticfile buildpack installed in your deployment, run the command below in the root directory of the app. The root directory of the app must contain a file named Staticfile.

cf push APP-NAME

Where APP-NAME is the name you want to give your app.

For example:

$ cf push my-app
Creating app my-app in org sample-org / space sample-space as username@example.com...
OK
...
requested state: started
instances: 1/1
usage: 1G x 1 instances
urls: my-app.example.com
last uploaded: Wed Apr 1 12:55:41 UTC 2020
stack: cflinuxfs2
buildpack: staticfile

     state     since                    cpu    memory        disk         details
#0   running   2020-04-01 12:55:57 PM   0.0%   12.6M of 1G   5.9M of 1G

Option 2: Specify a Staticfile Buildpack

To explicitly specify a Staticfile buildpack, run the command below in the root directory of the app. You may want to specify a buildpack if your deployment does not have the Staticfile buildpack installed or the installed version is outdated.

cf push APP-NAME -b BUILDPACK-NAME-OR-PATH

Where:

  • APP-NAME is the name you want to give your app.
  • BUILDPACK-NAME-OR-PATH is either the name of a buildpack that is installed in your deployment or the path to a buildpack. You can find the Cloud Foundry Staticfile buildpack in the Staticfile repository on GitHub.

For example:

$ cf push my-app -b https://github.com/cloudfoundry/staticfile-buildpack.git
Creating app my-app in org sample-org / space sample-space as username@example.com...
OK
...
requested state: started
instances: 1/1
usage: 1G x 1 instances
urls: my-app.example.com
last uploaded: Wed Apr 1 12:55:41 UTC 2020
stack: cflinuxfs2
buildpack: https://github.com/cloudfoundry/staticfile-buildpack.git

     state     since                    cpu    memory        disk         details
#0   running   2020-04-01 12:55:57 PM   0.0%   12.6M of 1G   5.9M of 1G

Verifying the Push

After you push the app, follow the steps below to verify that the push was successful:

  1. Find the URL of your app in the output of the cf push command. For example, the URL in the terminal output above is my-app.example.com.

  2. In a browser, navigate to the URL to view your app.

Example Staticfile Buildpack Apps

For different examples of apps that use the Staticfile buildpack, see the fixtures directory in the Staticfile buildpack GitHub repo.

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 the Cloud Foundry Slack community.

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