Deprecate buildpack

[schneems]

This buildpack is currently not maintained by a team and has never progressed out of experimental status. Let's make this clearer by deprecating the buildpack.

This is done right before the release of heroku-22 as supporting new stacks require maintenance effort -- particularly so for Heroku-22, as it no longer ships with system Ruby, which means this buildpack will stop working without considerable changes - since it is written in Ruby (unlike most other buildpacks).

Users are encouraged to migrate to heroku-buildpack-nginx which is more actively maintained, lighter-weight, more performant and more customisable.

GUS-W-10346704.

[edmorley]

Thank you for working on this! It's great :-)

Some initial thoughts:

• Should we redirect the cat to stderr and add the relevant control codes so it shows up in red in the build log? eg like https://github.com/heroku/heroku-buildpack-php/blob/2acb8a055fa96289645d4b77a68a6cd41d67767c/bin/util/common.sh#L5-L23
• What do you think about adding links to https://github.com/heroku/heroku-buildpack-nginx , which is the NGINX buildpack that we'd recommend?
• For bonus points, should we say where to write the nginx config file in the app source, so heroku-buildpack-nginx picks it up? We could also link to the examples folder in the heroku-buildpack-nginx repo maybe?
• I think we might need to mention that the auto-generated nginx config (from static.json) doesn't cover the dynamic per-request rewriting feature this buildpack has - so we might need to describe the generated config as a "starting point" or call out the specific features that need manual changes afterwards (I'm not too sure what those features are; but perhaps @hone can remember)

[hone]

@schneems thanks for doing this. I do think there will be plenty of folks still using this on Heroku-18/20 and it sucks that we're just deleting the config in the README and forcing them to look at old history. If we want to move it, can we at least move it into a new file that is linked?

[Malax]

I agree with @hone's point of moving the README contents to a different file so folks that need it can still reference it. Otherwise:

[schneems]

Should we redirect the cat to stderr, so it shows up in red in the build log (at least I think Codon uses red for that? or maybe we have to add colours manually anyway, I forget?)

I don't know off the top of my head. The Ruby buildpack manually adds color codes. I think it's a nice to have. This is a pretty big block of warning text. If you really want people to take note I would start failing builds unless some flag is set like I_REALIZE_STATIC_BUILDPACK_IS_DEPRECATED=1 but I think that's a bit too heavy handed for this.

What do you think about adding links to https://github.com/heroku/heroku-buildpack-nginx , which is the NGINX buildpack that we'd recommend?

Done.

For bonus points, should we say where to write the file in the app source, so heroku-buildpack-nginx picks it up? We could also link to the examples folder in the heroku-buildpack-nginx repo maybe?

Seems good, looks like config/nginx.conf.erb is the place

I think we might need to mention that the auto-generated nginx config (from static.json) doesn't cover the dynamic per-request rewriting feature this buildpack has - so we might need to describe the generated config as a "starting point" or call out the specific features that need manual changes afterwards (I'm not too sure what those features are; but perhaps @hone can remember)

This is tricky. I tried to get clever and give them some more info so I whipped up this

$ heroku run bash
~ $ ruby -r./bin/config/lib/nginx_config_util.rb -rjson -e "NginxConfigUtil.parse_routes(JSON.parse(File.read('./static.json'))).each {|(key,value)| puts %Q(#{key}: #{value})}"

But apparently, it basically does nothing. Here's an example:

~ $ cat static.json
{
  "root": "_site",
  "https_only": true,
  "clean_urls": true,
  "error_page": "404.html",
  "routes": {
    "/*.html": "index.html",
    "/route/**": "bar/*.html"
  },
  "headers": {

    "/": {
      "Cache-Control": "no-store, no-cache"
    },
    "/assets/**": {
      "Cache-Control": "public, max-age=15552000"
    }
  }
}
~ $ ruby -r./bin/config/lib/nginx_config_util.rb -rjson -e "NginxConfigUtil.parse_routes(JSON.parse(File.read('./static.json'))).each {|(key,value)| puts %Q(#{key}: #{value})}"
root: _site
https_only: true
clean_urls: true
error_page: 404.html
routes: {"/*.html"=>"index.html", "/route/**"=>"bar/*.html"}
headers: {"/"=>{"Cache-Control"=>"no-store, no-cache"}, "/assets/**"=>{"Cache-Control"=>"public, max-age=15552000"}}

Maybe there's a better or more helpful script terence might have some more thoughts.

I added more concrete steps to the deprecation:

       - Write these contents to your local repo at `config/nginx.conf.erb`, commit them to git.
       - Replace path logic that previously used `mruby` with static logic.
       - Configure your app to use the NGINX buildpack via `heroku buildpacks:add https://github.com/heroku/heroku-buildpack-nginx`.
       - Remove this buildpack via `heroku buildpacks:remove https://github.com/heroku/heroku-buildpack-static`

Granted that second one is kind of like "draw the rest of the owl". Over time if others want to contribute ways to help migrate off of this buildpack we can accept those PRs. Actually, I'll update the readme to say that.

I do think there will be plenty of folks still using this on Heroku-18/20 and it sucks that we're just deleting the config in the README and forcing them to look at old history. If we want to move it, can we at least move it into a new file that is linked?

I reinstated the rest of the readme, seems fine to leave it.

[edmorley]

r+ with changes below

Thank you for working on this! :-)

[schneems]

Updated with your changes and suggestions

[edmorley]

Confirmed working in production with the buildpack-registry release :-)

$ mkdir static-test && cd $_
$ git init
$ h create --buildpack heroku-community/static
$ mkdir dist
$ echo 'hello' > dist/hello.txt
$ echo '{"root": "dist/"}' > static.json
$ git add -A && git commit -m 'Initial commit' && git push heroku main
...
remote: -----> Building on the Heroku-20 stack
remote: -----> Using buildpack: heroku-community/static
remote: -----> Static HTML app detected
remote:        ## WARNING: `heroku-buildpack-static` is deprecated
remote:
remote:        This buildpack is deprecated and is no longer being maintained.
remote:        If you are using this project, you can transition over to NGINX via an NGINX buildpack.
remote:        Use your project's existing configuration.
remote:        To find the NGINX configuration generated by the heroku-buildpack-static you can run:
remote:
remote:        ```
remote:        $ heroku run bash
remote:        ~ $ bin/config/make-config
remote:        ~ $ cat config/nginx.conf
remote:        ```
remote:
remote:        These commands will output your current NGINX config generated from your `static.json` contents.
remote:
remote:        - Write these contents to your local repo at `config/nginx.conf.erb`, commit them to git.
remote:        - Replace path logic that previously used `mruby` with static logic.
remote:        - Configure your app to use the NGINX buildpack via `heroku buildpacks:add heroku-community/nginx`.
remote:        - Remove this buildpack via `heroku buildpacks:remove heroku-community/static` (or `heroku buildpacks:remove https://github.com/heroku/heroku-buildpack-static`).
remote:
remote: -----> Installed nginx 1.21.3 to /app/bin
remote: -----> Discovering process types
remote:        Procfile declares types     -> (none)
remote:        Default types for buildpack -> web
remote:
remote: -----> Compressing...
remote:        Done: 6.6M

[edmorley]

Filed mars/create-react-app-buildpack#200 for create-react-app-buildpack migrating to a maintained buildpack.