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

Swisscom Application Cloud requires a file named Staticfile in the root directory of the app. This file alerts App Cloud to use the Staticfile buildpack with the app.

The Staticfile can be an empty file or it can contain configuration settings for your app. For more information, see Configuring the Buildpack and Pushing 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 64M 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 App Cloud.
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

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.

To configure these options, add the configuration property as a new line in your Staticfile, unless otherwise instructed below.

Option Description Staticfile Configuration
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/. root: YOUR-DIRECTORY-NAME

For example:
root: public
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.
directory: visible
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. ssi: 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. pushstate: enabled
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.
gzip: off
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
Add a new Staticfile.auth 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

For example: bob:$apr1$DuUQEQp8$ZccZCHQElNSjrgerwSFC0
alice:$apr1$4IRQGcD/$UMFLnIHSD9ZHJ86TR4zx
Proxy support Allows you to use a proxy when downloading dependencies during the staging of your app. http_proxy: HTTP_URL
https_proxy: HTTPS_URL

For example:
http_proxy: http://www.example.com/
https_proxy: https://www.example.com/
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.

force_https: true

Alternatively, set the FORCE_HTTPS environment variable to true.
Dot files By default, hidden files, which are those starting with a ., are not served by this buildpack. host_dot_files: 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. 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 the configuration of your app.

http_strict_transport_security: true
HSTS includes subdomains Causes NGINX to respond to all requests with the header Strict-Transport-Security: max-age=31536000; includeSubDomains. This forces browsers to make all subsequent requests over HTTPS including subdomains. 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_include_subdomains: true
HSTS preload Causes NGINX to respond to all requests with the 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). 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.

http_strict_transport_security_preload: true
Custom location configuration 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. To customize the location block of the NGINX configuration file, follow these steps:

  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. The path is relative to nginx/conf.
    ...
    root: public
    location_include: includes/*.conf
    ...
Additional MIME type support Allows you to configure additional MIME types on your NGINX server.

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 Full Example Configuration in the NGINX documentation.
Sample MIME types file:
types {
        text/html     html htm shtml;
        text/css      css;
        text/xml      xml rss;
        image/gif     gif;
        ...
      }

Pushing the App

Follow the steps below to push your application.

  1. Create an empty file named Staticfile in the root directory of your app:

    touch Staticfile
    
  2. Modify Staticfile for the needs of your app. For a list of configuration options, see Configuring the Buildpack.

  3. To push your app, run the following command:

    cf push APP_NAME -m 64M
    

    Where APP_NAME correponds to 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
    

  4. 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 -m 64M -b https://github.com/cloudfoundry/staticfile-buildpack.git
    

    Where APP_NAME correponds to the name you want to give your application.

  5. Find the URL of your app in the output from the push command. For example, the URL in the output above is my-app.example.com.

  6. In a browser, navigate to the URL to see your static app running.

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.

View the source for this page in GitHub