Ruby: Add detail to Rails Assets Pipeline documentation.

[sophiewigmore]

Recently, we got feedback that the configuration options in the Rails Assets buildpack are difficult to figure out, and require some hacking to get working.

We should add some additional details to the Ruby How-To and Reference documentation about the configuration options and also what the buildpack expects the app to have. Check out the full thread at paketo-buildpacks/rails-assets#144 for some examples.

Checklist

• I have included links to page(s) that need to be changed

[kingdonb]

I think this was my entrypoint:

• https://github.com/pivotal/kpack/blob/main/docs/tutorial.md

A lot of the struggle that ensued here was simply because I had heard of cnb-shim first and was already "sold on" Heroku buildpacks, so my first-ditch effort was "can I do kpack and cnb-shim" – at the end of the first day, I came to the conclusion the answer was no, or if it was possible I'd be the first person to get it to work, and then I'd have to write some docs groan

Another pain point was that at first, on your main landing page (paketo.io) the Ruby support is a bit buried, so that gave me the impression it probably wasn't going to work very well. I hadn't heard of this group, I didn't know if it's the leading builder, but I assumed Heroku was going to be the best-in-class when it comes to buildpacks for Ruby because well, you know.

Eventually found my way here:

• https://github.com/paketo-buildpacks/ruby

I struggled for a little while to get kpack working at this point, then basically "fell back" and tried using pack CLI building locally with my rails app, that didn't take very long to get working.

I remember vaguely the point where I tipped/sort of gave up on Heroku+kpack was the point where I realized that paketo builder was actually going to produce an image without much effort (whereas early successes that I had with cnb-shim turned out to be harder than expected for me to reproduce again later on), and as long as I used full instead of base, since I've got gems that require obscure native extensions, the important libs were all there in the paketo full builder! 🎉

I had converted my app from a sqlite to postgres config because Heroku's buildpack demands it, (another advantage, paketo did not care if I decided that I wanted to use a sqlite database, so now I may still end up doing that...) anyway, that decision had already been made, and now I was going to do it on postgres, ...

The next struggle was I could only check that everything was working after crafting a proper Deployment.yaml and connecting it up to secrets so I could connect to that DB. Those things are not really in scope at all for buildpacks or kpack, although it would have been nice to see it included in the doc since it's a necessary requirement and this will make things more accessible for people that would have likely been intimidated by writing a Deployment from scratch.

• then this doc (I believe) got me most of the rest of the way, including that anchor you linked in our discussion on Missing secret_key_base rails-assets#144: (the ruby buildpack doc) https://paketo.io/docs/howto/ruby/

What would have really made things easy for me, is a complete example of using all these things (rails, postgres, optionally either RAILS_MASTER_KEY or SECRET_KEY_BASE, and a concrete example deployment.yaml, all with kpack.)

To get the end-to-end "rapid deployment experience" I'm using Flux, which if I'm being fully candid, I'd want to ask you to also make a part of this example (maybe we can collab on it!), so that people can get as close to the heroku deployment sort-of "git push and you're done" experience, as possible without compromising on cloud native practices and declarative configuration.

It just wasn't super clear how to start using kpack with ruby, I had no interest in building locally, I only did that because it helped to see I was making concrete progress. I wanted to do it all on the cluster, but of course I did wind up building locally with pack just to be sure I had all of the prerequisites in order and solve one problem at a time.

In the end, I think this is the best way to deploy my Rails apps on Kubernetes now, (I'd still like to find a way to use cnb-shim together with kpack but I'm not as optimistic about that anymore – more importantly, it's not any longer blocking me from presenting this to Ruby devs who probably didn't want to be on Kubernetes at all and quite understandably don't want to write Dockerfiles, or don't want to learn how to write a good Dockerfile just to use with maybe one Ruby/Rails app.)

[kingdonb]

Just one thing to add:

https://paketo.io/docs/reference/ruby-reference/#rails-asset-pipeline - you shared this link in the other thread, I see now that it has lots of the information I needed to learn about, but it was buried enough that I did not find it on my own perusing the docs.

It is more complicated than I thought to add a "Getting Started" for Ruby

Now that I am taking a sort of broader inventory of the docs format, not sure exactly how to make this better? Not all Ruby apps need Rails, many won't require a Postgres database, but you still sort of need to cover all of this, and by the time you're into databases, the question may come up "should we show how to deploy a postgres database on the cluster" now I've just more than blown up the complexity budget for an effective doc, (it would no longer fit well in the list of examples here):

At the same time, those are basically "table stakes" for Rails devs and many will walk away if they come and find your docs don't appear to cover all of that.

[sophiewigmore]

@kingdonb again, thank you for this feedback, it is majorly helpful! I'm really glad you took the time to walk us through your experience. From what I'm hearing there are a few actionable things from your experience we could take a look at improving:

• Adding some kpack documentation to the website seems to be important. A how-to guide could definitely help.
• Adding more specific/detailed how-to guides to the Ruby docs (for things like connecting to a DB) or at least including that it can be accomplished with the buildpacks and adding links to Ruby docs for realistic use cases might help?
• Add more samples. We have a samples repository with examples, but they're all documented using pack and the rails example could go a bit deeper.
• In our top level docs, we could probably make builder selection clearer
• Make all the different docs locations easier to find at a top-level

Separately, I've never used Flux but I'd be interested in seeing a demo with the buildpacks so I can get a better idea of what this workflow looks like. Would you be interested in doing a quick Zoom call or something to show us? Alternatively, we have a weekly working group meeting where we could chat about your use case more if you have questions or wanted to talk about what you had in mind? Whatever works.

[kingdonb]

Yeah, I'm definitely interested in joining the working group meeting. I had found the kpack working group meeting on their calendar already myself, but hadn't seen this one. I am generally available on Tuesdays at 2, so maybe I can join this week!

It just so happens I recorded a 15 minute demo that includes kpack and flux last weekend; it needed to have narration added and I am pretty green at video editing, but I gave it an attempt this morning. The first 7 minutes or so are standard kubeadm setup stuff, then I start to get to the kpack+flux parts... where an ImageRepository monitors for new app builds (tags) and notifies the automation when they are pushed to my registry by kpack.

Then the flux ImageUpdateAutomation resource, through an ImagePolicy, selects the latest one to deploy and updates a Deployment manifest with the new image tag. Finally Flux deploys our build and we can see it running.

I am currently rendering it out with OpenShot, I am crossing my fingers that the audio is going to be in sync, as I really don't know what I'm doing here, I'm pretty sure they were originally out of sync because of a difference in sample rates between my two recordings (I could use some help when it comes to video processing, this stuff isn't easy!)

(Sixteen minutes later...) I'm going to upload what I have, here welcome to check this out:

https://youtu.be/CZ1yvFQYiog