User Guide needs to be updated (global issue). This issue is about the creation of a new "Customizing workspaces' containers (and other components)" section.
Describe the solution you'd like

We should explain what a Devfile is, how Che uses it (we recommed to version it in git) and link to the related documentation.

We should provide information on how to prepare an container image to be used in a Che workspace:

The entrypoint should be non terminating
Ready to run as an arbitrary user
A nice terminal experience ($PS1, $HOME, ...)
Some dedicated folders may be overridden (automouted git credentials, tokens, certs)

We should explain what should not be specified in a Devfile: infrastructure related, user related, IDE related configurations are not supposed to be in a Devfile.

We should cover attributes that are handled by Che/DevWorkspace but are not part of the Devfile spec.

We should specify how ports that need to be exposed or not can be defined to avoid pop-ups all the way.