Red Hat Bugzilla – Bug 1288488
[DOCS] Document s2i builder details
Last modified: 2017-12-23 19:32:52 EST
What happens precisely during a Python s2i build? How about for Ruby? (etc)
In terms of source code, it looks like we want to look at:
to describe how a particular "platform" is detected and how its constituent files (e.g., requirements.txt for Python) are processed.
This reference documentation should either be centralized in the main overview:
or added to each image's overview, with the main overview describing the general detection / processing scheme.
@Thien-Thi, that's not what I had in mind originally.
The starting point is documenting that the Python image will automatically install project dependencies from a requirements.txt or setup.py.
It should be documented here: https://docs.openshift.org/latest/using_images/s2i_images/python.html
And the code you want to look at is here: https://github.com/openshift/sti-python/blob/master/3.4/s2i/bin/assemble
Next, look at the assemble scripts for other images and document what they are able to do, what input they consume and how.
This is not about detecting what platform to use. No Go code involved...
I see Python-specific build details (i.e., `requirements.txt` and `setup.py`) are documented in:
but that there is no (direct) link from:
to it. So, how about we add one in the latter page's Overview? I think the word "dependencies" would be the best place. (I'd make an analogous change w/ the other languages.) WDYT?
It's a "coincidence" that language detection relies on files that I mentioned in https://github.com/openshift/openshift-docs/issues/1283.
The original point is to document, in a high level, what an s2i builder does.
On the OpenShift/Source-To-Image side, there's the git cloning of a repository, then the files are streamed into a container, without the .git dir, etc etc.
Then the assemble script is executed:
For Python, as an example:
It will do several steps, rely on env vars, etc.
What I miss is documentation explaining how your code gets from a Git repository into a final image, and what else has happened as part of the build (download and install dependencies, etc).
Most of it is language/builder-image independent, while some is specific to each builder image, like each language has a different package management solution, a different way to list dependencies, and so on.
We can chat face-to-face tomorrow or any other time for further clarification.
@Thien-Thi the Trello link above refers to new/proposed functionality.
The relationship with this BZ is that documentation produced out of this BZ would require updates in the future with that card implemented, do you agree?
We may want to cross reference -- add a link to this BZ in that card. If you don't have access to that, I can add the link there pointing here.
(In reply to Rodolfo Carvalho from comment #8)
> [...] new/proposed functionality. The relationship with this BZ
> is that documentation produced out of this BZ would require
> updates in the future with that card implemented, do you agree?
Thanks for the clarification. It sounds like you're saying that
card has no immediate relevance to this BZ, although in the
future, work that goes into this BZ will need to be modified once
the work for that card lands.
> We may want to [xref]
Good idea. Done.
By the way, thanks for the interview the other day. Here are my
notes from the session (additions/corrections welcome):
* explain flow:
*** input: code + builder image
*** builder image:
***** explicitly defined
***** auto-detected via ‘oc new-app’ (plan: link)
*** LANG-image provided assemble script capabilities
***** general flow
***** hooks for each LANG -- e.g., check requirements.txt (Python), etc
***** DOES NOT handle non-LANG-modules (cannot use yum, reason: not root)
*** user can provide assemble script