Staticfile buildpack

Page last updated:

You can configure and use the Staticfile buildpack in Cloud Foundry.

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 back ends hosted elsewhere. To find which version of NGINX the current Staticfile buildpack uses, see Staticfile buildpack release notes.

Staticfile detection

If you create a file named Staticfile and locate it in the build 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, Cloud Foundry push the apps with the -m 64M option to reduce RAM allocation from the default 1 GB that are allocated to containers by default.

Configure the buildpack

This section describes configuration options that are available for the Staticfile buildpack. If you need to make configuration changes to NGINX that are not listed in the table, 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:

Other configuration changes

Use the following instructions to make other configuration changes.

Basic authentication

You can enable basic authentication for your app or website. 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

You can 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:

1. Set an alternative root directory. The location_include property only works in conjunction with an alternative root. See the following example that includes a static content file:
   • Directory: public
   • File: public/index.html

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

You can 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 following command 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.

Option 2: Specify a Staticfile buildpack

To explicitly specify a Staticfile buildpack, run the following command in the root directory of the app. You might 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.

Verifying the push

After you push the app, follow these steps 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, go 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.