Page last updated:
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.
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.
Pivotal Web Services (PWS) requires a file named
Staticfile in the root directory of the app to use the Staticfile buildpack with the app.
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.
Follow the procedure below to create and push a single page app using the Staticfile buildpack.
|1||Create and move into a root directory for the sample app in your workspace:
$ mkdir sample $ cd sample
$ echo 'Hello World' > index.html
|3|| Create an empty file named
$ touch Staticfile
|4|| Use the
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 firstname.lastname@example.org... 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.|
This section describes various ways you can configure the Staticfile buildpack options and how to push your Staticfile app.
This table describes some of the aspects of the Staticfile buildpack that you can configure.
|Alternative root||Allows you to specify a root directory other than the default, which is
|Directory list||An HTML page that displays a directory index for your site. A sample of a directory list is shown below.
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.|
that look like
|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
|HTTP Strict Transport Security||Causes NGINX to respond to all requests with the header
|Custom Location configuration||To customize the
|Custom NGINX configuration||Additional NGINX configuration can be applied, such as mapping file extensions to mime types. See the NGINX documentation for examples.|
In the root directory of your app, create an empty file named
$ touch Staticfile
Configure the Staticfile buildpack for the needs of your app.
If you want to… Then… More information serve
index.htmland other assets from a location other than the root directory
add this line to the
Alternative root display a directory list instead of the standard 404 error add this line to the
Directory list enable SSI add this line to the
SSI enable pushstate routing add this line to the
Pushstate routing disable gzip_static and gunzip modules add this line to the
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.authin the root directory or alternative root directory, and add one or more user/password lines to it. For example,
Basic authentication use a proxy for downloading dependencies during staging set the
Proxy support force HTTPS set the
FORCE_HTTPSenvironment variable to
Note: Do not enable
FORCE_HTTPSif 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: truein the
Dot Files force the receiving browser to make subsequent requests over HTTPS add this line to the
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
mime.typesfiles to your root folder, or to the alternate root folder if you specified one.
Follow the steps below to push your application.
$ cf push my-app -m 64M Creating app my-app in org sample-org / space sample-space as email@example.com... OK … requested state: started instances: 1/1 usage: 64M x 1 instances urls: my-app.example.comOr, if you do not have the buildpack, or the installed version is out-of-date, use the
|2.||Find the URL of your app in the output from the push command and navigate to it to see your static app running.|
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.