Permalink
Fetching contributors…
Cannot retrieve contributors at this time
388 lines (320 sloc) 16.3 KB
---
title: Staticfile Buildpack
owner: Buildpacks
---
<strong><%= modified_date %></strong>
## <a id='overview'></a> 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.
<p class="note"><strong>Note</strong>: <a href="http://bosh.io/docs/trusted-certs.html">BOSH configured custom trusted certificates</a> are not supported by the Staticfile buildpack.</p>
### <a id='definitions'></a>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](https://github.com/cloudfoundry/staticfile-buildpack/releases).
### <a id='staticfile'></a>Staticfile Requirement
<%= vars.product_full %> requires a file named `Staticfile` in the root directory of the app.
This file alerts <%= vars.product_short %> 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](#configure-and-push).
### <a id='memory'></a>Memory Usage
NGINX requires 20&nbsp;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&nbsp;GB allocated to containers by default.
### <a id='sample'></a>"Hello World" Tutorial
Follow the procedure below to create and push a single page app using the Staticfile buildpack.
<table border='1' class='nice'>
<tr>
<th>Step</th><th>Action</th>
</tr>
<tr>
<td valign="top">1</td>
<td>Create and move into a root directory for the sample app in your workspace:
<br>
<pre class="terminal">
$ mkdir sample
$ cd sample
</pre>
</td>
</tr>
<tr>
<td valign="top">2</td>
<td>Create an <code>index.html</code> file that contains some text:
<br>
<pre class="terminal">
$ echo 'Hello World' > index.html
</pre>
</td>
</tr>
<tr>
<td valign="top">3</td>
<td> Create an empty file named <code>Staticfile</code>:
<br>
<pre class="terminal">
$ touch Staticfile
</pre>
</td>
</tr>
<tr>
<td valign="top">4</td>
<td> Use the <code>cf login</code> command to log in to
<%= vars.product_short %>.<br>
For more information, see the <a href="../../cf-cli/getting-started.html#login">Login</a> section of the <em>Getting Started with the cf CLI</em> documentation.
<pre class="terminal">
$ cf login
</pre>
</td>
</tr>
<tr>
<td valign="top">5</td>
<td> Push the sample app:<br>
<pre class="terminal">
$ cf push hello -m 64M
</pre>
</td>
</tr>
<tr>
<td valign="top">6</td>
<td>Find the URL of the app in the output.<br>
A fragment of output is shown below:
<pre class='terminal'>
Creating app hello in org sample-org / space sample-space as username<span>@</span>example.com...
OK
&#8230;
requested state: started
instances: 1/1
usage: 64M x 1 instances
urls: hello.example.com
</pre>
</td>
</tr>
<tr>
<td valign="top">7</td>
<td>Navigate to the URL to see the sample app running.
</td>
</tr>
</table>
## <a id='configure-and-push'></a>Configuring the Buildpack and Pushing the App
This section describes ways you can configure the Staticfile buildpack options and how to push your Staticfile app.
### <a id='config-options'></a>Configuration Options
This table describes aspects of the Staticfile buildpack that you can configure using the [Configure Your App](#config-process) details in the next table</a>.
<table border='1' class='nice'>
<tr>
<th>Options</th>
<th>Description</th>
</tr>
<tr>
<td id="root">Alternative root</td>
<td>Allows you to specify a root directory other than the default, which is <code>index.html</code>.
For example, you can specify that the buildpack serves index.html and all other assets from an alternate folder where your HTML/CSS/JavaScript files exist, such as <code>dist/</code> or <code>public/</code>.</td>
</tr>
<tr>
<td id="dir-list">Directory list</td>
<td>An HTML page that displays a directory index for your site. A sample of a directory list is shown below.<br>
<img src="../images/directory-index.png" alt="directory index" style="margin: 20px"><br>
If your site is missing an index.html, your app displays a directory list instead of the standard 404 error page.</td>
</tr>
<tr>
<td id="ssi">SSI</td>
<td>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 <a href="https://en.wikipedia.org/wiki/Server_Side_Includes">Server Side Includes</a> entry on Wikipedia.</td>
<tr>
<td id="pushstate">Pushstate routing</td>
<td>Keeps browser-visible URLs clean for client-side JavaScript apps that serve multiple routes.
For example, pushstate routing allows a single JavaScript file route to multiple anchor-tagged URLs
that look like <code>/some/path1</code> instead of <code>/some#path1</code>.
</td>
</tr>
<tr>
<td id="gzip">GZip file serving and compressing</td>
<td>The <a href="http://nginx.org/en/docs/http/ngx_http_gzip_static_module.html">gzip_static</a>
and <a href="http://nginx.org/en/docs/http/ngx_http_gunzip_module.html">gunzip</a> 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. <br>You may want to disable compression in particular circumstances, for example if serving to very old browser clients.</td>
</tr>
<tr>
<td id="basic-auth">Basic authentication</td>
<td>Allows you to place simple access controls on your app.<br>
<img src="../images/basicauth.png" style="margin: 20px"></td>
</tr>
<tr>
<td>Proxy support</td>
<td>Allows you to use a proxy to download dependencies during staging.</td>
</tr>
<tr>
<td id="force-https">Force HTTPS</td>
<td>A way to enforce that all requests are sent through HTTPS.
This redirects non-HTTPS requests as HTTPS requests.
<p class="note"><strong>Note</strong>: Do not enable <code>FORCE_HTTPS</code> 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 <a href="https://support.cloudflare.com/hc/en-us/articles/200170416">Flexible SSL</a> with CloudFlare.</p></td>
</tr>
<tr>
<td id="host_dot_files">Dot Files</td>
<td>By default, hidden files (those starting with a <code>.</code>) are not served by this buildpack.</td>
</tr>
<tr>
<td id="strict-security">HTTP Strict Transport Security</td>
<td>Causes NGINX to respond to all requests with the header
<code>Strict-Transport-Security: max-age=31536000</code>. This forces browsers to make all subsequent requests over HTTPS. Defaults to a max-age of one year.</td>
</tr>
<tr>
<td id="strict-security-with-subdomains">HTTP Strict Transport Security Include SubDomains</td>
<td>Causes NGINX to respond to all requests with the header
<code>Strict-Transport-Security: max-age=31536000; includeSubDomains</code>. This forces browsers to make all subsequent requests over HTTPS including subdomains. Defaults to a max-age of one year.</td>
</tr>
<tr>
<td id="strict-security-with-preload">HTTP Strict Transport Security Preload</td>
<td>Causes NGINX to respond to all requests with the header
<code>Strict-Transport-Security: max-age=31536000; includeSubDomains; preload</code>. This forces browsers to make all subsequent requests over HTTPS including subdomains and requests inclusion in browser-managed HSTS preload lists (see <a href="https://hstspreload.org">https://hstspreload.org</a>). Defaults to a max-age of one year.</td>
</tr>
<tr>
<td>Custom Location configuration</td>
<td>To customize the <code>location</code> block of the NGINX configuration file, follow these steps:<br><br>
<ol>
<li>Set a <code>root</code> directory (<code>location_include</code> only works in conjunction with <code>root</code>)</li>
<li>Create a file with location scoped NGINX directives. See the following example, which causes visitors of your site to receive the <code>X-MySiteName</code> HTTP header:
<br><br>
<b>File</b>: <code>nginx/conf/includes/custom_header.conf</code><br>
<b>Content</b>:
<code>add_header X-MySiteName BestSiteEver;</code><br><br>
<li>Set the <code>location_include</code> variable in your <b>Staticfile</b> to the path of the file from the previous step. The path is relative to <code>nginx/conf</code>.<br>
<code style="width: 100%">
...<br>
root: public<br>
location_include: includes/*.conf<br>
...<br>
</code><br><br>
</li>
</ol>
For information about NGINX directives, see <a href="https://www.nginx.com/resources/wiki/start/topics/examples/full/">NGINX
documentation</a>.</td>
</tr>
<tr>
<td>Custom NGINX configuration</td>
<td>If you require additional custom NGINX configuration you should use the <a href="../nginx/index.html">NGINX Buildpack</a></td>
</tr>
</table>
### <a id='config-process'></a>Configure Your App
1. In the root directory of your app, create an empty file named `Staticfile`:
<pre class='terminal'>
$ touch Staticfile
</pre>
2. Configure the Staticfile buildpack for the needs of your app.
<table border='1' class='nice'>
<tr>
<th><strong>If you want to&hellip;</strong></th> <th><strong>Then&hellip;</strong></th><th>More information</th>
</tr>
<tr>
<td>serve <code>index.html</code> and other assets from a location other than the root directory</tc>
<td>add this line to the <code>Staticfile</code>:<br><code><strong>root: YOUR-DIRECTORY-NAME</strong></code><br><br>For example, <code>root: public</code></td>
<td><a href="#root">Alternative root</a></td>
</tr>
<tr>
<td>display a directory list instead of the standard 404 error</td>
<td>add this line to the <code>Staticfile</code>:<br><code><strong>directory: visible</strong></code></td>
<td><a href="#dir-list">Directory list</a></td>
</tr>
<tr>
<td>enable SSI</td>
<td>add this line to the <code>Staticfile</code>:<br><code><strong>ssi: enabled</strong></code></td>
<td><a href="#ssi">SSI</a></td>
</tr>
<tr>
<td>enable pushstate routing</td>
<td>add this line to the <code>Staticfile</code>:<br><code><strong>pushstate: enabled</strong></code></td>
<td><a href="#pushstate">Pushstate routing</a></td>
</tr>
<tr>
<td>disable gzip_static and gunzip modules</td>
<td>add this line to the <code>Staticfile</code>:<br><code><strong>gzip: off</strong></code></td>
<td><a href="#gzip">GZip</a></td>
</tr>
<tr>
<td valign="top">enable basic authentication for your app or website</td>
<td> 1. Create a hashed username and password pair for each user, using a site like <a href="http://www.htaccesstools.com/htpasswd-generator/">Htpasswd Generator</a><br>
&#50;. Create a file named <code>Staticfile.auth</code> in the root directory or alternative root directory, and add one or more user/password lines to it.
For example,<br> <code>bob:$apr1$DuUQEQp8$ZccZCHQElNSjrgerwSFC0<br>alice:$apr1$4IRQGcD/$UMFLnIHSD9ZHJ86TR4zx</code><br>
</td>
<td><a href="#basic-auth">Basic authentication</a></td>
</tr>
<tr>
<td>use a proxy for downloading dependencies during staging</td>
<td>set the <code>http_proxy</code> and <code>https_proxy</code> environment variables.</td>
<td><a href="../proxy-usage.html">Proxy support</a></td>
</tr>
<tr>
<td>force HTTPS</td>
<td>set the <code>FORCE_HTTPS</code> environment variable to <code>true</code> <strong>OR</strong><br>
add this line to the <code>Staticfile</code>:<br><code><strong>force_https: true</strong></code></td>
<td><a href="#force-https">Force HTTPS</a></td>
</tr>
<tr>
<td>host dot files</td>
<td>To enable serving hidden (dot files), use <code>host_dot_files: true</code> in the <code>Staticfile</code>.</td>
<td><a href="#host_dot_files">Dot Files</a></td>
</tr>
<tr>
<td>force the receiving browser to make subsequent requests over HTTPS</td>
<td>add this line to the <code>Staticfile</code>:<br><code><strong>http_strict_transport_security: true</strong></code><br>
<p class="note"><strong>Note</strong>: Because this setting persists in browsers for a long time, only enable this setting after ensuring you have completed your configuration.</p></td>
<td><a href="#strict-security">HTTP Strict Transport Security</a></td>
</tr>
<tr>
<td>force the receiving browser to make subsequent requests over HTTPS for all sub-domains</td>
<td>add this line to the <code>Staticfile</code>:<br><code><strong>http_strict_transport_security_include_subdomains: true</strong></code><br>
<p class="note"><strong>Note</strong>: This setting will default to http_strict_transport_security being true.</p></td>
<td><a href="#strict-security-with-subdomains">HTTP Strict Transport Security</a></td>
</tr>
<tr>
<td>force the receiving browser to make subsequent requests over HTTPS and add it to the Chrome's HSTS Preload list</td>
<td>add this line to the <code>Staticfile</code>:<br><code><strong>http_strict_transport_security_preload: true</strong></code><br>
<p class="note"><strong>Note</strong>: This setting will default to http_strict_transport_security being true.</p></td>
<p class="note"><strong>Note</strong>: This setting will default to http_strict_transport_security_include_subdomains being true.</p></td>
<td><a href="#strict-security-with-preload">HTTP Strict Transport Security</a></td>
</tr>
<tr>
<td>specify additional MIME types</td>
<td>add a <code><strong>mime.types</strong></code> file to your root folder, or to the alternate root folder if you specified one.</td>
<td><a href="https://www.nginx.com/resources/wiki/start/topics/examples/full/#mime-types">NGINX documentation</a></td>
</tr>
<tr>
<td>make additional configuration changes to NGINX</td>
<td>use the NGINX Buildpack instead of the Staticfile buildpack.</td>
<td><a href="../nginx/index.html">NGINX Buildpack</a></td>
</tr>
</table>
### <a id='custom_nginx_configuration'></a> Push Your App ###
Follow the steps below to push your application.
<table border='1' class='nice'>
<tr>
<th>Step</th>
<th>Action</th>
</tr>
<tr valign="top">
<td>1.</td>
<td>Use the <code>cf push APP_NAME -m 64M</code> command to push your app. Replace <code>APP_NAME</code> with the name you want to give your application. For example:<br>
<pre class='terminal'>
$ 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
</pre>
Or, if you do not have the buildpack, or the installed version is out-of-date, use the <code>-b</code> option to specify the buildpack as follows:<br>
<code>cf push APP_NAME -b https://github.com/cloudfoundry/staticfile-buildpack.git</code>
</td>
</tr>
<tr valign="top">
<td>2.</td>
<td>Find the URL of your app in the output from the push command and navigate to it to see your static app running.</td>
</tr>
</table>
## <a id='examples'></a>Example Staticfile Buildpack Apps
For different examples of apps that use the Staticfile buildpack, see the [fixtures](https://github.com/cloudfoundry/staticfile-buildpack/tree/master/fixtures) directory in the Staticfile buildpack GitHub repo.
## <a id='help'></a>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](https://github.com/cloudfoundry/staticfile-buildpack).
* **Release Notes**: Find current information about this buildpack on the Staticfile buildpack [release page](https://github.com/cloudfoundry/staticfile-buildpack/releases) in GitHub.
* **Slack**: Join the #buildpacks channel in the [Cloud Foundry Slack community](http://slack.cloudfoundry.org/).