Repository files navigation

NOTE: This buildpack is in an experimental OSS project.

This is a buildpack for handling static sites and single page web apps.

For a guide, read theGetting Started with Single Page Apps on Heroku.

This buildpack is deprecated and is no longer being maintained.If you are using this project, you can transition over to NGINX via an NGINX buildpack.Use your project's existing configuration.To find the NGINX configuration generated by the heroku-buildpack-static you can run:

$ heroku run bash~ $ bin/config/make-config~ $ cat config/nginx.conf

These commands will output your current NGINX config generated from yourstatic.json contents.

• Write these contents to your local repo atconfig/nginx.conf.erb, commit them to git.
• Replace path logic that previously usedmruby with static logic.
• Configure your app to use the NGINX buildpack viaheroku buildpacks:add heroku-community/nginx.
• Remove this buildpack viaheroku buildpacks:remove heroku-community/static (orheroku buildpacks:remove https://github.com/heroku/heroku-buildpack-static).

If you have tips or tricks for migrating off of this buildpack and want to add them to the instructions above please send a PR.

• serving static assets
• gzip on by default
• error/access logs support inheroku logs
• customconfiguration

Thestatic.json file is required to use this buildpack. This file handles all the configuration described below.

1. Set the app to this buildpack:$ heroku buildpacks:set heroku-community/static.
2. Deploy:$ git push heroku master

You can configure different options for your static application by writing astatic.json in the root folder of your application.

This allows you to specify a different asset root for the directory of your application. For instance, if you're using ember-cli, it naturally builds adist/ directory, so you might want to use that instead.

{"root":"dist/"}

By default this is set topublic_html/

This allows you to perform 301 redirects to a specific hostname, which can be useful for redirecting www to non-www (or vice versa).

{"canonical_host":"www.example.com"}

You can use environment variables as well:

{"canonical_host":"${HOST}"}

This allows you to specify a character set for your text assets (HTML, Javascript, CSS, and so on). For most apps, this should be the default value of "UTF-8", but you can override it by settingencoding:

{"encoding":"US-ASCII"}

For SEO purposes, you can drop the.html extension from URLs for say a blog site. This means users could go to/foo instead of/foo.html.

{"clean_urls":true}

By default this is set tofalse.

You can disable the access log and change the severity level for the error log.

{"logging": {"access":false,"error":"warn"  }}

By defaultaccess is set totrue anderror is set toerror.

The environment variableSTATIC_DEBUG can be set, to override theerror log level toerror.

You can define custom routes that combine to a single file. This allows you to preserve routing for a single page web application. The following operators are supported:

• * supports a single path segment in the URL. In the configuration below,/baz.html would match but/bar/baz.html would not.
• ** supports any length in the URL. In the configuration below, both/route/foo would work and/route/foo/bar/baz.

{"routes": {"/*.html":"index.html","/route/**":"bar/baz.html"  }}

When serving a single page app, it's useful to support wildcard URLs that serves the index.html file, while also continuing to serve JS and CSS files correctly. Route ordering allows you to do both:

{"routes": {"/assets/*":"/assets/","/**":"index.html"  }}

With custom redirects, you can move pages to new routes but still preserve the old routes for SEO purposes. By default, we return a301 status code, but you can specify the status code you want.

{"redirects": {"/old/gone/": {"url":"/","status":302    }  }}

It's common to want to be able to test the frontend against various backends. Theurl key supports environment variable substitution using${ENV_VAR_NAME}. For instance, if there was a staging and production Heroku app for your API, you could setup the config above like the following:

{"redirects": {"/old/gone/": {"url":"${NEW_SITE_DOMAIN}/new/here/"    }  }}

Then using theconfig vars, you can point the frontend app to the appropriate backend. To match the original proxy setup:

$ heroku config:set NEW_SITE_DOMAIN="https://example.herokapp.com"

You can replace the default nginx 404 and 500 error pages by defining the path to one in your config.

{"error_page":"errors/error.html"}

You can redirect all HTTP requests to HTTPS.

{  "https_only": true}

You can enable Basic Authentication so all requests require authentication.

{  "basic_auth": true}

This will generate.htpasswd using environment variablesBASIC_AUTH_USERNAME andBASIC_AUTH_PASSWORD if they are present. Otherwise it will use a standard.htpasswd file present in theapp directory.

Passwords set viaBASIC_AUTH_PASSWORD can be generated using OpenSSL or Apache Utils. For instance:openssl passwd -apr1.

For single page web applications like Ember, it's common to back the application with another app that's hosted on Heroku. The down side of separating out these two applications is that now you have to deal with CORS. To get around this (but at the cost of some latency) you can have the static buildpack proxy apps to your backend at a mountpoint. For instance, we can have all the api requests live at/api/ which actually are just requests to our API server.

{"proxies": {"/api/": {"origin":"https://hone-ember-todo-rails.herokuapp.com/"    }  }}

It's common to want to be able to test the frontend against various backends. Theorigin key supports environment variable substitution using${ENV_VAR_NAME}. For instance, if there was a staging and production Heroku app for your API, you could setup the config above like the following:

{"proxies": {"/api/": {"origin":"https://${API_APP_NAME}.herokuapp.com/"    }  }}

Then using theconfig vars, you can point the frontend app to the appropriate backend. To match the original proxy setup:

$ heroku config:set API_APP_NAME="hone-ember-todo-rails"

Using the headers key, you can set custom response headers. It uses the same operators for pathing asCustom Routes.

{"headers": {"/": {"Cache-Control":"no-store, no-cache"    },"/assets/**": {"Cache-Control":"public, max-age=512000"    },"/assets/webfonts/*": {"Access-Control-Allow-Origin":"*"    }  }}

For example, to enable CORS for all resources, you just need to enable it for all routes like this:

{"headers": {"/**": {"Access-Control-Allow-Origin":"*"    }  }}

When there are header conflicts, the last header definition always wins. The headers do not get appended. For example,

{"headers": {"/**": {"X-Foo":"bar","X-Bar":"baz"    },"/foo": {"X-Foo":"foo"    }  }}

when accessing/foo,X-Foo will have the value"foo" andX-Bar will not be present.

• HTTPS redirect
• Root Files
• Clean URLs
• Proxies
• Redirects
• Custom Routes
• 404

In case you have multiple buildpacks for the application you can ensure static rendering inProcfile withweb: bin/boot.

For testing we use Docker to replicate Heroku locally. You'll need to haveit setup locally. We're also using rspec for testing with Ruby. You'll need to have those setup and install those deps:

$ bundle install

To run the test suite just execute:

$ bundleexec rspec

To add a new test, add another example insidespec/simple_spec.rb or create a new file based off ofspec/simple_spec.rb. All the example apps live inspec/fixtures.

When writing a test,BuildpackBuilder creates the docker container we need that represents the heroku cedar-14 stack.AppRunner.new takes the name of a fixture and mounts it in the container built byBuildpackBuilder to run tests against. TheAppRunner instance provides convenience methods likeget that just wrapnet/http for analyzing the response.

If you are running docker with boot2docker, the buildpack will automatically send tests to the right ip address.You need to forward the docker's port 3000 to the virtual machine's port though.

VBoxManage modifyvm "boot2docker-vm" --natpf1 "tcp-port3000,tcp,,3000,,3000";

The steps buildpack maintainers need to perform when releasing new nginxbinaries (either for a new stack orngx_mruby version), are:

1. Update the stacks list inMakefile and/or the ngx_mruby versioninscripts/build_ngx_mruby.sh.
2. Runmake build to build all stacks ormake build-heroku-NN to build just one stack.
3. Ensure the AWS CLI is installed (egbrew install awscli).
4. Authenticate with the relevant AWS account (typically by setting the environment variables from PCSK).
5. Runmake sync (or if using a custom S3 bucket,S3_BUCKET=... make sync).
6. Updatebin/compile to reference the new stacks and/or nginx version URLs.
7. Open a PR with the changes from (1) and (6).