docker docs - Glosses over the Dockerfile lines

[lukepuplett]

File: get-started/02_our_app.md

Hello. I'm new to Docker, having put off learning it for what feels like a decade. But that means I have a noob's perspective, uncorrupted by The Curse of Knowledge.

So, Part 2 of Get started under the section titled Build the app’s container image, step 1, you have a lovely Dockerfile with six commands and a syntax hint at the top. Step 2 follows but fails to discuss the lines in the Dockerfile.

It explains that we "copied in our application and used yarn ..." but I have no real idea how that maps to the lines in the Dockerfile. I especially don't understand whether the commands in the Dockerfile are run within the sandboxed process, or outside it. For example, WORKDIR /app is that basically a chdir? And is it run inside the container process? I guess that's not built yet. Perhaps it runs the base image and then runs all these commands inside that? Is the path relative to where the Dockerfile was found?

It feels like the author knows this so instinctively that they fail to mention it. Or perhaps they think it's obvious or maybe even that by explaining the most basic things, it somehow makes them appear less smart. Maybe you don't want to get into the weeds of all this yet, but the titles of parts 3 - 10 don't look like they're going to discuss it. And besides, you've showed me the commands already, so you have to explain it.

It should also explain why it has its own ENV and COPY commands, instead of relying on RUN cp ... or even explain why the whole thing isn't just a bash script.

The whole thing leaves me more confused.

Thanks

Luke

[lukepuplett]

Interestingly, this document explains things more clearly. It's still confusing in places but it feels as if the concepts in here should touch on in the tutorial with a link to a deeper dive article. Yet this is filed under 'reference' which normally implies materials that should be looked up once you know what you're doing, i.e. referring to the manual for facts, syntax, like a writer reaching for a thesaurus.

https://docs.docker.com/engine/reference/builder/

If you look at the docs for Google Cloud, you'll see that Guides and Reference are distinct sections; the former is what you read to learn the product and the latter is for looking up dry facts once you know what you're doing. The same can be seen in the Azure docs.

[docker-robott]

Closed issues are locked after 30 days of inactivity.
This helps our team focus on active issues.

If you have found a problem that seems similar to this, please open a new issue.

/lifecycle locked