Page last updated:
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.
Follow the steps below to push an app using the Staticfile buildpack.
Create a file named
Staticfilein the root directory.
$ touch Staticfile
Push the app.
$ cf push APPNAME -m 64MWhen using the
-m 64Mflag, static assets are served by Nginx, which only requires 20M. The
-m 64Mflag 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
You can configure how the Staticfile buildpack accesses and serves apps by editing the
By default, the buildpack serves
index.html and all other assets from the root folder of your project.
To configure the buildpack add the following line to your
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.
Follow these steps to enable basic auth:
Convert the username / password to the required format: http://www.htaccesstools.com/htpasswd-generator/ For example, username
Create a file in the root of your application
Staticfile.auth. This becomes the
.htpasswdfile for Nginx to project your site. It can include one or more user/password lines.
Push your application to apply changes to basic auth.
To disable basic auth, remove
Staticfile.auth and push.
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.
Add a line to your
Staticfile that begins with
Add the following line to your
Staticfile to enable support for SSI:
/some/path1 instead of
To enable support for pushstate routing, add the following line to your
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
gunzip off; gzip_static off;
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.
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.
To enable HTTP Strict Transport Security (HSTS), add the following line to your
This causes Nginx to respond to all requests with the header:
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.
You can customize the Nginx configuration further, by adding
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.
If you need to use a proxy to download dependencies during staging, you can set
https_proxy environment variables. For more information, see
the Proxy Usage Docs.
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.