diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 003b7090bc..444bee41b8 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -3,7 +3,7 @@ # For more details, see https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners -/build/ @crazy-max @usha-mandya +/build/ @crazy-max @usha-mandya @jedevc /compose/ @usha-mandya diff --git a/.github/vale/Docker/Acronyms.yml b/.github/vale/Docker/Acronyms.yml new file mode 100644 index 0000000000..85f7136c2e --- /dev/null +++ b/.github/vale/Docker/Acronyms.yml @@ -0,0 +1,65 @@ +extends: conditional +message: "'%s' has no definition." +link: https://docs.docker.com/contribute/style/grammar/#acronyms-and-initialisms +level: warning +ignorecase: false +# Ensures that the existence of 'first' implies the existence of 'second'. +first: '\b([A-Z]{3,5})\b' +second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)' +# ... with the exception of these: +exceptions: + - API + - ASP + - CLI + - CPU + - CSS + - CSV + - DEBUG + - DOM + - DPI + - FAQ + - GCC + - GDB + - GET + - GPU + - GTK + - GUI + - HEAD + - HTML + - HTTP + - HTTPS + - IDE + - JAR + - JSON + - JSX + - LESS + - LLDB + - NET + - NOTE + - NVDA + - OSS + - PATH + - PDF + - PHP + - POST + - RAM + - REPL + - RSA + - SCM + - SCSS + - SDK + - SQL + - SSH + - SSL + - SVG + - TBD + - TCP + - TODO + - URI + - URL + - USB + - UTF + - XML + - XSS + - YAML + - ZIP diff --git a/.github/vale/Docker/Adverbs.yml b/.github/vale/Docker/Adverbs.yml new file mode 100644 index 0000000000..630a31698b --- /dev/null +++ b/.github/vale/Docker/Adverbs.yml @@ -0,0 +1,269 @@ +extends: existence +message: "Consider removing '%s'." +ignorecase: true +level: warning +tokens: + - abnormally + - absentmindedly + - accidentally + - adventurously + - anxiously + - arrogantly + - awkwardly + - bashfully + - beautifully + - bitterly + - bleakly + - blindly + - blissfully + - boastfully + - boldly + - bravely + - briefly + - brightly + - briskly + - broadly + - busily + - calmly + - carefully + - carelessly + - cautiously + - cheerfully + - cleverly + - closely + - coaxingly + - colorfully + - continually + - coolly + - courageously + - crossly + - cruelly + - curiously + - currently + - daintily + - dearly + - deceivingly + - deeply + - defiantly + - deliberately + - delightfully + - diligently + - dimly + - doubtfully + - dreamily + - easily + - elegantly + - energetically + - enormously + - enthusiastically + - excitedly + - extremely + - fairly + - faithfully + - famously + - ferociously + - fervently + - fiercely + - fondly + - foolishly + - fortunately + - frankly + - frantically + - freely + - frenetically + - frightfully + - furiously + - generally + - generously + - gently + - gladly + - gleefully + - gracefully + - gratefully + - greatly + - greedily + - happily + - hastily + - healthily + - heavily + - helplessly + - honestly + - hopelessly + - hungrily + - innocently + - inquisitively + - intensely + - intently + - interestingly + - inwardly + - irritably + - jaggedly + - jealously + - jovially + - joyfully + - joyously + - jubilantly + - judgmentally + - justly + - keenly + - kiddingly + - kindheartedly + - knavishly + - knowingly + - knowledgeably + - lazily + - lightly + - limply + - lively + - loftily + - longingly + - loosely + - loudly + - lovingly + - loyally + - madly + - majestically + - meaningfully + - mechanically + - merrily + - miserably + - mockingly + - mortally + - mysteriously + - naturally + - nearly + - neatly + - nervously + - nicely + - noisily + - obediently + - obnoxiously + - oddly + - offensively + - optimistically + - overconfidently + - painfully + - partially + - patiently + - perfectly + - playfully + - politely + - poorly + - positively + - potentially + - powerfully + - promptly + - properly + - punctually + - quaintly + - queasily + - queerly + - questionably + - quickly + - quietly + - quirkily + - quizzically + - randomly + - rapidly + - rarely + - readily + - really + - reassuringly + - recklessly + - regularly + - reluctantly + - repeatedly + - reproachfully + - respectively + - restfully + - righteously + - rightfully + - rigidly + - roughly + - rudely + - safely + - scarcely + - scarily + - searchingly + - sedately + - seemingly + - selfishly + - separately + - seriously + - shakily + - sharply + - sheepishly + - shrilly + - shyly + - silently + - sleepily + - slowly + - smoothly + - softly + - solemnly + - solidly + - speedily + - stealthily + - sternly + - strictly + - suddenly + - supposedly + - surprisingly + - suspiciously + - sweetly + - swiftly + - sympathetically + - tenderly + - tensely + - terribly + - thankfully + - thoroughly + - thoughtfully + - tightly + - tremendously + - triumphantly + - truthfully + - ultimately + - unabashedly + - unaccountably + - unbearably + - unethically + - unexpectedly + - unfortunately + - unimpressively + - unnaturally + - unnecessarily + - urgently + - usefully + - uselessly + - utterly + - vacantly + - vaguely + - vainly + - valiantly + - vastly + - verbally + - very + - viciously + - victoriously + - violently + - vivaciously + - voluntarily + - warmly + - weakly + - wearily + - wetly + - wholly + - wildly + - willfully + - wisely + - woefully + - wonderfully + - worriedly + - yawningly + - yearningly + - yieldingly + - youthfully + - zealously + - zestfully + - zestily diff --git a/.github/vale/Docker/Callouts.yml b/.github/vale/Docker/Callouts.yml new file mode 100644 index 0000000000..a5b7c21c3b --- /dev/null +++ b/.github/vale/Docker/Callouts.yml @@ -0,0 +1,12 @@ +extends: existence +message: "Use a liquid tag for 'Important' or 'Warning' callouts." +link: https://docs.docker.com/contribute/components/call-outs/ +level: warning +nonword: true +scope: raw +raw: + - '[:blank:]*\> .*?' + - "(?i)(?:important|warning|danger|caution)(?-i)" + - '.*\n' + - '(?:[:blank:]*\>.*\n)+?' + - '[:blank:]*(?!\{: \.(important|warning))' diff --git a/.github/vale/Docker/ComplexWords.yml b/.github/vale/Docker/ComplexWords.yml new file mode 100644 index 0000000000..add7baf389 --- /dev/null +++ b/.github/vale/Docker/ComplexWords.yml @@ -0,0 +1,117 @@ +extends: substitution +message: "Consider using '%s' instead of '%s'." +ignorecase: true +level: suggestion +swap: + "approximate(?:ly)?": about + abundance: plenty + accelerate: speed up + accentuate: stress + accompany: go with + accomplish: carry out|do + accorded: given + accordingly: so + accrue: add + accurate: right|exact + acquiesce: agree + acquire: get|buy + additional: more|extra + address: discuss + addressees: you + adjacent to: next to + adjustment: change + admissible: allowed + advantageous: helpful + advise: tell + aggregate: total + aircraft: plane + alleviate: ease + allocate: assign|divide + alternatively: or + alternatives: choices|options + ameliorate: improve + amend: change + anticipate: expect + apparent: clear|plain + ascertain: discover|find out + assistance: help + attain: meet + attempt: try + authorize: allow + belated: late + bestow: give + cease: stop|end + collaborate: work together + commence: begin + compensate: pay + component: part + comprise: form|include + concept: idea + concerning: about + confer: give|award + consequently: so + consolidate: merge + constitutes: forms + contains: has + convene: meet + demonstrate: show|prove + depart: leave + designate: choose + desire: want|wish + determine: decide|find + detrimental: bad|harmful + disclose: share|tell + discontinue: stop + disseminate: send|give + eliminate: end + elucidate: explain + employ: use + enclosed: inside|included + encounter: meet + endeavor: try + enumerate: count + equitable: fair + equivalent: equal + exclusively: only + expedite: hurry + facilitate: ease + females: women + finalize: complete|finish + frequently: often + identical: same + incorrect: wrong + indication: sign + initiate: start|begin + itemized: listed + jeopardize: risk + liaise: work with|partner with + maintain: keep|support + methodology: method + modify: change + monitor: check|watch + multiple: many + necessitate: cause + notify: tell + numerous: many + objective: aim|goal + obligate: bind|compel + optimum: best|most + permit: let + portion: part + possess: own + previous: earlier + previously: before + prioritize: rank + procure: buy + provide: give|offer + purchase: buy + relocate: move + solicit: request + state-of-the-art: latest + subsequent: later|next + substantial: large + sufficient: enough + terminate: end + transmit: send + utilization: use + utilize: use diff --git a/.github/vale/Docker/Contractions.yml b/.github/vale/Docker/Contractions.yml new file mode 100644 index 0000000000..a814a1c8e9 --- /dev/null +++ b/.github/vale/Docker/Contractions.yml @@ -0,0 +1,47 @@ +extends: substitution +message: "Consider using '%s' instead of '%s'." +level: warning +ignorecase: true +swap: + are not: aren't + cannot: can't + could not: couldn't + did not: didn't + do not: don't + does not: doesn't + has not: hasn't + have not: haven't + how is: how's + is not: isn't + + 'it is(?!\.)': it's + 'it''s(?=\.)': it is + + should not: shouldn't + + 'that is(?!\.)': that's + 'that''s(?=\.)': that is + + 'they are(?!\.)': they're + 'they''re(?=\.)': they are + + was not: wasn't + + 'we are(?!\.)': we're + 'we''re(?=\.)': we are + + 'we have(?!\.)': we've + 'we''ve(?=\.)': we have + + were not: weren't + + 'what is(?!\.)': what's + 'what''s(?=\.)': what is + + 'when is(?!\.)': when's + 'when''s(?=\.)': when is + + 'where is(?!\.)': where's + 'where''s(?=\.)': where is + + will not: won't diff --git a/.github/vale/Docker/DateFormat.yml b/.github/vale/Docker/DateFormat.yml new file mode 100644 index 0000000000..ff9b641724 --- /dev/null +++ b/.github/vale/Docker/DateFormat.yml @@ -0,0 +1,10 @@ +extends: existence +message: Use 'July 31, 2016' format, not '%s'. +link: https://docs.docker.com/contribute/style/grammar/#dates +ignorecase: true +level: error +nonword: true +tokens: + - '\d{1,2} + (?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?) + \d{4}' diff --git a/.github/vale/Docker/DateMonthName.yml b/.github/vale/Docker/DateMonthName.yml new file mode 100644 index 0000000000..26ba757d4e --- /dev/null +++ b/.github/vale/Docker/DateMonthName.yml @@ -0,0 +1,8 @@ +extends: existence +message: "When possible, spell out the name of the month." +link: https://docs.docker.com/contribute/style/grammar/#dates +ignorecase: true +level: warning +nonword: true +tokens: + - '\b\d{1,2}/\d{1,2}/(?:\d{4}|\d{2})\b' diff --git a/.github/vale/Docker/DateNumber.yml b/.github/vale/Docker/DateNumber.yml new file mode 100644 index 0000000000..fbd2abbc4a --- /dev/null +++ b/.github/vale/Docker/DateNumber.yml @@ -0,0 +1,40 @@ +extends: existence +message: "Don't use ordinal numbers for dates." +link: https://docs.docker.com/contribute/style/grammar/#dates +level: error +nonword: true +ignorecase: true +raw: + - \b(?:Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)|May|Jun(?:e)|Jul(?:y)|Aug(?:ust)|Sep(?:tember)?|Oct(?:ober)|Nov(?:ember)?|Dec(?:ember)?)\b\s* +tokens: + - first + - second + - third + - fourth + - fifth + - sixth + - seventh + - eighth + - ninth + - tenth + - eleventh + - twelfth + - thirteenth + - fourteenth + - fifteenth + - sixteenth + - seventeenth + - eighteenth + - nineteenth + - twentieth + - twenty-first + - twenty-second + - twenty-third + - twenty-fourth + - twenty-fifth + - twenty-sixth + - twenty-seventh + - twenty-eighth + - twenty-ninth + - thirtieth + - thirty-first diff --git a/.github/vale/Docker/Decimals.yml b/.github/vale/Docker/Decimals.yml new file mode 100644 index 0000000000..d01d3ca9cf --- /dev/null +++ b/.github/vale/Docker/Decimals.yml @@ -0,0 +1,8 @@ +extends: existence +message: Use decimals instead of fractions. +link: https://docs.docker.com/contribute/style/grammar/#decimals-and-fractions +level: warning +raw: + - '[\w\s]' + - \d+\/\d+ + - '(?!\/\d+)' diff --git a/.github/vale/Docker/GenericCTA.yml b/.github/vale/Docker/GenericCTA.yml new file mode 100644 index 0000000000..1d588c277a --- /dev/null +++ b/.github/vale/Docker/GenericCTA.yml @@ -0,0 +1,10 @@ +extends: existence +message: "Avoid generic calls to action: '%s'" +link: https://docs.docker.com/contribute/style/formatting/#links +level: warning +scope: link +ignorecase: true +tokens: + - click here + - find out more + - learn more diff --git a/.github/vale/Docker/HeadingLength.yml b/.github/vale/Docker/HeadingLength.yml new file mode 100644 index 0000000000..270ccf80ae --- /dev/null +++ b/.github/vale/Docker/HeadingLength.yml @@ -0,0 +1,7 @@ +extends: occurrence +message: "Try to keep headings short (< 8 words)." +link: https://docs.docker.com/contribute/style/formatting/#headings-and-subheadings +scope: heading +level: suggestion +max: 8 +token: \b(\w+)\b diff --git a/.github/vale/Docker/LinkLength.yml b/.github/vale/Docker/LinkLength.yml new file mode 100644 index 0000000000..85c1de98e0 --- /dev/null +++ b/.github/vale/Docker/LinkLength.yml @@ -0,0 +1,7 @@ +extends: occurrence +message: "Try to keep link text short (< 5 words)." +scope: link +link: https://docs.docker.com/contribute/style/formatting/#links +level: suggestion +max: 5 +token: \b(\w+)\b diff --git a/.github/vale/Docker/LinkPunctuation.yml b/.github/vale/Docker/LinkPunctuation.yml new file mode 100644 index 0000000000..118c7c191a --- /dev/null +++ b/.github/vale/Docker/LinkPunctuation.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Don't use end punctuation in links." +link: https://docs.docker.com/contribute/style/formatting/#links +nonword: true +level: warning +scope: link +tokens: + - '[a-z0-9][.?!](?:\s|$)' diff --git a/.github/vale/Docker/ListComma.yml b/.github/vale/Docker/ListComma.yml new file mode 100644 index 0000000000..2af0bc710d --- /dev/null +++ b/.github/vale/Docker/ListComma.yml @@ -0,0 +1,6 @@ +extends: existence +message: Don’t add commas (,) or semicolons (;) to the ends of list items. +link: https://docs.docker.com/contribute/style/grammar/#lists +level: warning +scope: list +raw: '[,;]$' diff --git a/.github/vale/Docker/ListLength.yml b/.github/vale/Docker/ListLength.yml new file mode 100644 index 0000000000..2e187ea1ba --- /dev/null +++ b/.github/vale/Docker/ListLength.yml @@ -0,0 +1,7 @@ +extends: occurrence +message: List items should contain relatively few words or short phrases. +link: https://docs.docker.com/contribute/style/grammar/#lists +level: suggestion +scope: list +max: 20 +token: \b(\w+)\b diff --git a/.github/vale/Docker/OxfordComma.yml b/.github/vale/Docker/OxfordComma.yml new file mode 100644 index 0000000000..8344e91d64 --- /dev/null +++ b/.github/vale/Docker/OxfordComma.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Use the Oxford comma in '%s'." +scope: sentence +level: suggestion +nonword: true +tokens: + - '(?:[^\s,]+,){1,} \w+ (?:and|or) \w+[.?!]' diff --git a/.github/vale/Docker/Passive.yml b/.github/vale/Docker/Passive.yml new file mode 100644 index 0000000000..b25cff6241 --- /dev/null +++ b/.github/vale/Docker/Passive.yml @@ -0,0 +1,9 @@ +extends: existence +message: "'%s' looks like passive voice." +link: https://docs.docker.com/contribute/checklist/ +ignorecase: true +level: suggestion +raw: + - \b(am|are|were|being|is|been|was|be)\b\s* +tokens: + - '[\w]+ed' diff --git a/.github/vale/Docker/SentenceCase.yml b/.github/vale/Docker/SentenceCase.yml new file mode 100644 index 0000000000..148ab96766 --- /dev/null +++ b/.github/vale/Docker/SentenceCase.yml @@ -0,0 +1,11 @@ +extends: capitalization +message: "Use sentence case for headings: '%s'." +level: warning +scope: heading +match: $sentence +indicators: + - ":" +exceptions: + - Vocab/Docker/accept.txt + - Vocab/Technology/accept.txt + - Vocab/Industry/accept.txt diff --git a/.github/vale/Docker/SentenceLength.yml b/.github/vale/Docker/SentenceLength.yml new file mode 100644 index 0000000000..d08241cd16 --- /dev/null +++ b/.github/vale/Docker/SentenceLength.yml @@ -0,0 +1,7 @@ +extends: occurrence +message: "Write short, concise sentences." +scope: sentence +link: https://docs.docker.com/contribute/checklist/ +level: warning +max: 25 +token: \b(\w+)\b diff --git a/.github/vale/Docker/Spacing.yml b/.github/vale/Docker/Spacing.yml new file mode 100644 index 0000000000..81d79e2c10 --- /dev/null +++ b/.github/vale/Docker/Spacing.yml @@ -0,0 +1,7 @@ +extends: existence +message: "'%s' should have one space." +level: error +nonword: true +tokens: + - "[a-z][.?!] {2,}[A-Z]" + - "[a-z][.?!][A-Z]" diff --git a/.github/vale/Docker/Substitute.yml b/.github/vale/Docker/Substitute.yml new file mode 100644 index 0000000000..d225ff7369 --- /dev/null +++ b/.github/vale/Docker/Substitute.yml @@ -0,0 +1,38 @@ +extends: substitution +message: "Consider using '%s' instead of '%s'" +link: https://docs.docker.com/contribute/style/recommended-words/ +ignorecase: true +level: suggestion +swap: + '\b(?:eg|e\.g\.)[\s,]': for example + '\b(?:ie|i\.e\.)[\s,]': that is + (?:sign on|log on|log in): sign in + above: previous + adaptor: adapter + administrate: administer + afterwards: afterward + alphabetic: alphabetical + alphanumerical: alphanumeric + anti-aliasing: antialiasing + anti-malware: antimalware + anti-spyware: antispyware + anti-virus: antivirus + appendixes: appendices + assembler: assembly language + below: following + check box: checkbox + click: select + deselect: clear + ergo: therefore + execute: invoke + gb: GB + gbps: Gbps + kb: KB + keypress: keystroke + mb: MB + mutices: mutexes + paas: PaaS + pb: PB + scroll: navigate + sign up: register + tb: TB diff --git a/.github/vale/Docker/URLFormat.yml b/.github/vale/Docker/URLFormat.yml new file mode 100644 index 0000000000..c81b486c4c --- /dev/null +++ b/.github/vale/Docker/URLFormat.yml @@ -0,0 +1,9 @@ +extends: substitution +message: "Use '%s' instead of '%s'." +ignorecase: true +level: error +action: + name: replace +swap: + URL for: URL of + an URL: a URL diff --git a/.github/vale/Docker/VersionText.yml b/.github/vale/Docker/VersionText.yml new file mode 100644 index 0000000000..3210997efc --- /dev/null +++ b/.github/vale/Docker/VersionText.yml @@ -0,0 +1,12 @@ +extends: existence +message: Use later when talking about version numbers. +link: https://docs.docker.com/contribute/style/recommended-words/#later +scope: raw +raw: + - '\bv?' + - '(?P0|[1-9]\d*)\.?' + - '(?P0|[1-9]\d*)?\.?' + - '(?P0|[1-9]\d*)?' + - '(?:-(?P(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?' + - '(?:\+(?P[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?' + - '\b (and|or) (higher|above)' diff --git a/.github/vale/Docker/We.yml b/.github/vale/Docker/We.yml new file mode 100644 index 0000000000..65d3a7dd6e --- /dev/null +++ b/.github/vale/Docker/We.yml @@ -0,0 +1,11 @@ +extends: existence +message: "Avoid using first-person plural like '%s'." +link: https://docs.microsoft.com/en-us/style-guide/grammar/person#avoid-first-person-plural +level: warning +ignorecase: true +tokens: + - we + - we'(?:ve|re) + - ours? + - us + - let's diff --git a/.github/vale/Vocab/Docker/accept.txt b/.github/vale/Vocab/Docker/accept.txt new file mode 100644 index 0000000000..d1b0f6466b --- /dev/null +++ b/.github/vale/Vocab/Docker/accept.txt @@ -0,0 +1,26 @@ +(Certified|Verified) Publisher( Program)? +Autotest +BuildKit +Docker +Dockerize +Dockerizing +Docker Business +Docker Dasboard +Docker Desktop +Docker Engine +Docker Hub +Docker Team +Docker Extension +Dockerfile +HyperKit +Kitematic +LinuxKit +Official Images? +Sponsored (OSS|Open Source Software) +Swarm +Swarm Mode +[Bb]uildx +[Cc]ompose +[Mm]oby +dockerd +dockerignore diff --git a/.github/vale/Vocab/Industry/accept.txt b/.github/vale/Vocab/Industry/accept.txt new file mode 100644 index 0000000000..d17cc955bb --- /dev/null +++ b/.github/vale/Vocab/Industry/accept.txt @@ -0,0 +1,52 @@ +AWS +Amazon +Apple +Artifactory +BusyBox +CentOS +Ceph +CloudFront +Codefresh +CouchDB +Couchbase +Ddosify +Django +Fargate +Fedora +Flink +GeoNetwork +GitHub( Actions)? +Google +Intel +JetBrains +Kubernetes +Lightstreamer +Linux +Logstash +Mac +Mail(chimp|gun) +Microsoft +MySQL +Nginx +Nuxeo +OAuth +Okta +Postgres +PowerShell +Python +QEMU +RHEL +S3 +SQLite +Slack +Snyk +Solr +SonarQube +Syft +Twilio +Ubuntu +WSL +Windows +XWiki +Zsh +macOS diff --git a/.github/vale/Vocab/Technology/accept.txt b/.github/vale/Vocab/Technology/accept.txt new file mode 100644 index 0000000000..1f8b56f6cb --- /dev/null +++ b/.github/vale/Vocab/Technology/accept.txt @@ -0,0 +1,48 @@ +APIs? +Ethernet +Git +HTTP +IPs? +IPv[46] +IPvlan +MAC +SDKs? +SSO +TCP +UDP +VLAN +VM +cgroup +config +containerd +deserialization +deserialize +filepath +glibc +goroutine +hostname +inotify +iptables +kubectl +kubelet +lookup +macvlan +mfsymlinks +musl +namespace +osquery +osxfs +paravirtualization +proxying +real-time +runc +runtime +stdin +stdout +subnet +swappable +systemd +ungated +virtiofs +virtualize +walkthrough diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 53e260337c..7277d56550 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -7,6 +7,9 @@ on: - master pull_request: +permissions: + contents: read # to fetch code (actions/checkout) + jobs: build: runs-on: ubuntu-20.04 diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 0000000000..6b33d3939b --- /dev/null +++ b/.vale.ini @@ -0,0 +1,8 @@ +StylesPath = .github/vale +MinAlertLevel = suggestion + +Vocab = Docker, Industry, Technology + +[*.md] +BasedOnStyles = Vale, Docker +TokenIgnores = ({%.*%}) diff --git a/README.md b/README.md index 0b4d87d98c..7eb0c56ba4 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ We've made it really easy for you to file new issues. We value your contribution. We'd like to make it as easy as possible to submit your contributions to the Docker docs repository. Changes to the docs are handled through pull requests against the `master` branch. To learn how to -contribute, see our [Contribute section](contribute/overview.md). +contribute, see our [Contribute section](/contribute/overview). ## Copyright and license diff --git a/_config.yml b/_config.yml index 00428041d5..a14ea0a235 100644 --- a/_config.yml +++ b/_config.yml @@ -40,7 +40,7 @@ exclude: latest_engine_api_version: "1.41" docker_ce_version: "20.10" compose_v1_version: "1.29.2" -compose_version: "v2.10.2" +compose_version: "v2.11.0" compose_file_v3: "3.9" compose_file_v2: "2.4" machine_version: "0.16.0" @@ -165,10 +165,10 @@ fetch-remote: default_branch: "master" ref: "master" paths: - - dest: "build/bake" + - dest: "build/customize/bake" src: - "docs/guides/bake/**" - - dest: "build/buildx/drivers" + - dest: "build/building/drivers" src: - "docs/guides/drivers/**" diff --git a/_data/toc.yaml b/_data/toc.yaml index a9a74e5b85..ab225238c2 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -128,8 +128,6 @@ guides: title: Dockerfile best practices - path: /develop/develop-images/build_enhancements/ title: Build images with BuildKit - - path: /develop/develop-images/multistage-build/ - title: Use multi-stage builds - path: /develop/develop-images/image_management/ title: Manage images - path: /develop/develop-images/baseimages/ @@ -1179,8 +1177,6 @@ manuals: title: Known issues for Mac - sectiontitle: Additional resources section: - - path: /desktop/multi-arch/ - title: Multi-arch support - path: /desktop/kubernetes/ title: Deploy on Kubernetes - path: /desktop/backup-and-restore/ @@ -1337,8 +1333,6 @@ manuals: title: Optional post-installation steps - path: /engine/deprecated/ title: Deprecated features - - path: /buildx/working-with-buildx/ - title: Docker Buildx - path: /engine/context/working-with-contexts/ title: Docker Context - path: /engine/scan/ @@ -1389,44 +1383,48 @@ manuals: section: - path: /build/ title: Overview - - path: /build/hellobuild/ - title: Hello Build + - sectiontitle: Building images + section: + - path: /build/building/packaging/ + title: Packaging your software + - sectiontitle: Choosing a build driver + section: + - path: /build/building/drivers/ + title: Overview + - path: /build/building/drivers/docker/ + title: Docker driver + - path: /build/building/drivers/docker-container/ + title: Docker container driver + - path: /build/building/drivers/kubernetes/ + title: Kubernetes driver + - path: /build/building/drivers/remote/ + title: Remote driver + - path: /build/building/multi-stage/ + title: Multi-stage builds + - path: /build/building/multi-platform/ + title: Multi-platform images + - sectiontitle: Customizing builds + section: + - sectiontitle: Orchestrating builds with Bake + section: + - path: /build/customize/bake/ + title: Overview + - path: /build/customize/bake/file-definition/ + title: File definition + - path: /build/customize/bake/configuring-build/ + title: Configuring builds + - path: /build/customize/bake/hcl-funcs/ + title: User defined HCL functions + - path: /build/customize/bake/build-contexts/ + title: Build contexts and linking targets + - path: /build/customize/bake/compose-file/ + title: Building from Compose file - sectiontitle: Buildx section: - - path: /build/buildx/ - title: Buildx overview - path: /build/buildx/install/ title: Install Buildx - - sectiontitle: Drivers - section: - - path: /build/buildx/drivers/ - title: Overview - - path: /build/buildx/drivers/docker/ - title: Docker driver - - path: /build/buildx/drivers/docker-container/ - title: Docker container driver - - path: /build/buildx/drivers/kubernetes/ - title: Kubernetes driver - - path: /build/buildx/drivers/remote/ - title: Remote driver - path: /build/buildx/multiple-builders/ title: Using multiple builders - - path: /build/buildx/multiplatform-images/ - title: Building multi-platform images - - sectiontitle: Bake - section: - - path: /build/bake/ - title: Bake overview - - path: /build/bake/file-definition/ - title: File definition - - path: /build/bake/configuring-build/ - title: Configuring builds - - path: /build/bake/hcl-funcs/ - title: User defined HCL functions - - path: /build/bake/build-contexts/ - title: Build contexts and linking targets - - path: /build/bake/compose-file/ - title: Building from Compose file - path: /build/release-notes/ title: Release notes - sectiontitle: Docker Compose diff --git a/_layouts/landing.html b/_layouts/landing.html index 2f64045f76..a62902a913 100644 --- a/_layouts/landing.html +++ b/_layouts/landing.html @@ -135,7 +135,7 @@
Configure the Docker daemon
Build and run an image
Manage Docker objects
-
Use multi-stage builds
+
Multi-stage builds
Scale apps using Swarm
diff --git a/_scss/_layout.scss b/_scss/_layout.scss index 650f53f3fd..e994212140 100755 --- a/_scss/_layout.scss +++ b/_scss/_layout.scss @@ -101,7 +101,9 @@ section.section { } .col-nav { - background-color: $bg-sidebar; +// background-color: $bg-sidebar; +border-right: 1px solid #ddd; + } .col-toc { diff --git a/_scss/_navigation.scss b/_scss/_navigation.scss index 53d99410ed..61a5d45097 100755 --- a/_scss/_navigation.scss +++ b/_scss/_navigation.scss @@ -42,6 +42,7 @@ // Some links don't have 'href' attr, hence no mouse pointer .nav-sidebar li a { cursor: pointer; + color: $light-palette-grey-800; } .nav-sidebar>li>a { @@ -78,7 +79,7 @@ .nav-sidebar ul li a, .nav-sidebar ul li a:focus { border-bottom: none; - border-left: 1px solid $primary-links; + border-left: 1px solid $light-palette-grey-200; } .nav-sidebar .nav > li > a { @@ -96,6 +97,7 @@ background: $bg-sidebar-active; border-left: 4px solid $primary-links; font-weight: 600; + color: #2089C4; } .nav-sidebar ul li ul li a { diff --git a/build/buildx/drivers/docker-container.md b/build/building/drivers/docker-container.md similarity index 71% rename from build/buildx/drivers/docker-container.md rename to build/building/drivers/docker-container.md index de11b89f52..5703fb490b 100644 --- a/build/buildx/drivers/docker-container.md +++ b/build/building/drivers/docker-container.md @@ -1,6 +1,8 @@ --- title: "Docker container driver" keywords: build, buildx, driver, builder, docker-container +redirect_from: +- /build/buildx/drivers/docker-container/ fetch_remote: line_start: 2 line_end: -1 diff --git a/build/buildx/drivers/docker.md b/build/building/drivers/docker.md similarity index 72% rename from build/buildx/drivers/docker.md rename to build/building/drivers/docker.md index 8b263b3df4..c834fe6614 100644 --- a/build/buildx/drivers/docker.md +++ b/build/building/drivers/docker.md @@ -1,6 +1,8 @@ --- title: "Docker driver" keywords: build, buildx, driver, builder, docker +redirect_from: +- /build/buildx/drivers/docker/ fetch_remote: line_start: 2 line_end: -1 diff --git a/build/buildx/drivers/index.md b/build/building/drivers/index.md similarity index 66% rename from build/buildx/drivers/index.md rename to build/building/drivers/index.md index 0be093e099..970d18c85a 100644 --- a/build/buildx/drivers/index.md +++ b/build/building/drivers/index.md @@ -1,6 +1,8 @@ --- -title: "Buildx drivers overview" +title: "Drivers overview" keywords: build, buildx, driver, builder, docker-container, kubernetes, remote +redirect_from: +- /build/buildx/drivers/ fetch_remote: line_start: 2 line_end: -1 diff --git a/build/buildx/drivers/kubernetes.md b/build/building/drivers/kubernetes.md similarity index 72% rename from build/buildx/drivers/kubernetes.md rename to build/building/drivers/kubernetes.md index d89d6e7ac7..89f2dc723a 100644 --- a/build/buildx/drivers/kubernetes.md +++ b/build/building/drivers/kubernetes.md @@ -1,6 +1,8 @@ --- title: "Kubernetes driver" keywords: build, buildx, driver, builder, kubernetes +redirect_from: +- /build/buildx/drivers/kubernetes/ fetch_remote: line_start: 2 line_end: -1 diff --git a/build/building/drivers/remote.md b/build/building/drivers/remote.md new file mode 100644 index 0000000000..c81a0d4415 --- /dev/null +++ b/build/building/drivers/remote.md @@ -0,0 +1,9 @@ +--- +title: "Remote driver" +keywords: build, buildx, driver, builder, remote +redirect_from: +- /build/buildx/drivers/remote/ +fetch_remote: + line_start: 2 + line_end: -1 +--- diff --git a/build/building/multi-platform.md b/build/building/multi-platform.md new file mode 100644 index 0000000000..16a2da96e2 --- /dev/null +++ b/build/building/multi-platform.md @@ -0,0 +1,276 @@ +--- +title: Multi-platform images +description: Different strategies for building multi-platform images +keywords: build, buildx, buildkit, multi-platform images +redirect_from: +- /build/buildx/multiplatform-images/ +- /desktop/multi-arch/ +- /docker-for-mac/multi-arch/ +- /mackit/multi-arch/ +--- + +Docker images can support multiple platforms, which means that a single image +may contain variants for different architectures, and sometimes for different +operating systems, such as Windows. + +When running an image with multi-platform support, `docker` automatically +selects the image that matches your OS and architecture. + +Most of the Docker Official Images on Docker Hub provide a [variety of architectures](https://github.com/docker-library/official-images#architectures-other-than-amd64){: target="_blank" rel="noopener" class="_" }. +For example, the `busybox` image supports `amd64`, `arm32v5`, `arm32v6`, +`arm32v7`, `arm64v8`, `i386`, `ppc64le`, and `s390x`. When running this image +on an `x86_64` / `amd64` machine, the `amd64` variant is pulled and run. + +## Building multi-platform images + +Docker is now making it easier than ever to develop containers on, and for Arm +servers and devices. Using the standard Docker tooling and processes, you can +start to build, push, pull, and run images seamlessly on different compute +architectures. In most cases, you don't have to make any changes to Dockerfiles +or source code to start building for Arm. + +BuildKit with Buildx is designed to work well for building for multiple +platforms and not only for the architecture and operating system that the user +invoking the build happens to run. + +When you invoke a build, you can set the `--platform` flag to specify the target +platform for the build output, (for example, `linux/amd64`, `linux/arm64`, or +`darwin/amd64`). + +When the current builder instance is backed by the `docker-container` driver, +you can specify multiple platforms together. In this case, it builds a manifest +list which contains images for all specified architectures. When you use this +image in [`docker run`](../../engine/reference/commandline/run.md) or +[`docker service`](../../engine/reference/commandline/service.md), Docker picks +the correct image based on the node's platform. + +You can build multi-platform images using three different strategies that are +supported by Buildx and Dockerfiles: + +1. Using the QEMU emulation support in the kernel +2. Building on multiple native nodes using the same builder instance +3. Using a stage in Dockerfile to cross-compile to different architectures + +QEMU is the easiest way to get started if your node already supports it (for +example. if you are using Docker Desktop). It requires no changes to your +Dockerfile and BuildKit automatically detects the secondary architectures that +are available. When BuildKit needs to run a binary for a different architecture, +it automatically loads it through a binary registered in the `binfmt_misc` +handler. + +For QEMU binaries registered with `binfmt_misc` on the host OS to work +transparently inside containers, they must be statically compiled and registered +with the `fix_binary` flag. This requires a kernel >= 4.8 and +binfmt-support >= 2.1.7. You can check for proper registration by checking if +`F` is among the flags in `/proc/sys/fs/binfmt_misc/qemu-*`. While Docker +Desktop comes preconfigured with `binfmt_misc` support for additional platforms, +for other installations it likely needs to be installed using +[`tonistiigi/binfmt`](https://github.com/tonistiigi/binfmt){:target="_blank" rel="noopener" class="_"} +image. + +```console +$ docker run --privileged --rm tonistiigi/binfmt --install all +``` + +Using multiple native nodes provide better support for more complicated cases +that are not handled by QEMU and generally have better performance. You can +add additional nodes to the builder instance using the `--append` flag. + +Assuming contexts `node-amd64` and `node-arm64` exist in `docker context ls`; + +```console +$ docker buildx create --use --name mybuild node-amd64 +mybuild +$ docker buildx create --append --name mybuild node-arm64 +$ docker buildx build --platform linux/amd64,linux/arm64 . +``` + +Finally, depending on your project, the language that you use may have good +support for cross-compilation. In that case, multi-stage builds in Dockerfiles +can be effectively used to build binaries for the platform specified with +`--platform` using the native architecture of the build node. A list of build +arguments like `BUILDPLATFORM` and `TARGETPLATFORM` is available automatically +inside your Dockerfile and can be leveraged by the processes running as part +of your build. + +```dockerfile +# syntax=docker/dockerfile:1 +FROM --platform=$BUILDPLATFORM golang:alpine AS build +ARG TARGETPLATFORM +ARG BUILDPLATFORM +RUN echo "I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /log +FROM alpine +COPY --from=build /log /log +``` + +## Getting started + +Run the [`docker buildx ls` command](../../engine/reference/commandline/buildx_ls.md) +to list the existing builders: + +```console +$ docker buildx ls +NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS +default * docker + default default running 20.10.17 linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 +``` + +This displays the default builtin driver, that uses the BuildKit server +components built directly into the docker engine, also known as the [`docker` driver](../building/drivers/docker.md). + +Create a new builder using the [`docker-container` driver](../building/drivers/docker-container.md) +which gives you access to more complex features like multi-platform builds +and the more advanced cache exporters, which are currently unsupported in the +default `docker` driver: + +```console +$ docker buildx create --name mybuilder --driver docker-container --bootstrap +mybuilder +``` + +Switch to the new builder: + +```console +$ docker buildx use mybuilder +``` + +> **Note** +> +> Alternatively, run `docker buildx create --name mybuilder --driver docker-container --bootstrap --use` +> to create a new builder and switch to it using a single command. + +And inspect it: + +```console +$ docker buildx inspect +Name: mybuilder +Driver: docker-container + +Nodes: +Name: mybuilder0 +Endpoint: unix:///var/run/docker.sock +Status: running +Buildkit: v0.10.4 +Platforms: linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/mips64le, linux/mips64, linux/arm/v7, linux/arm/v6 +``` + +Now listing the existing builders again, we can see our new builder is +registered: + +```console +$ docker buildx ls +NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS +mybuilder docker-container + mybuilder0 unix:///var/run/docker.sock running v0.10.4 linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/mips64le, linux/mips64, linux/arm/v7, linux/arm/v6 +default * docker + default default running 20.10.17 linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 +``` + +## Example + +Test the workflow to ensure you can build, push, and run multi-platform images. +Create a simple example Dockerfile, build a couple of image variants, and push +them to Docker Hub. + +The following example uses a single `Dockerfile` to build an Alpine image with +cURL installed for multiple architectures: + +```dockerfile +# syntax=docker/dockerfile:1 +FROM alpine:3.16 +RUN apk add curl +``` + +Build the Dockerfile with buildx, passing the list of architectures to +build for: + +```console +$ docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t /:latest --push . +... +#16 exporting to image +#16 exporting layers +#16 exporting layers 0.5s done +#16 exporting manifest sha256:71d7ecf3cd12d9a99e73ef448bf63ae12751fe3a436a007cb0969f0dc4184c8c 0.0s done +#16 exporting config sha256:a26f329a501da9e07dd9cffd9623e49229c3bb67939775f936a0eb3059a3d045 0.0s done +#16 exporting manifest sha256:5ba4ceea65579fdd1181dfa103cc437d8e19d87239683cf5040e633211387ccf 0.0s done +#16 exporting config sha256:9fcc6de03066ac1482b830d5dd7395da781bb69fe8f9873e7f9b456d29a9517c 0.0s done +#16 exporting manifest sha256:29666fb23261b1f77ca284b69f9212d69fe5b517392dbdd4870391b7defcc116 0.0s done +#16 exporting config sha256:92cbd688027227473d76e705c32f2abc18569c5cfabd00addd2071e91473b2e4 0.0s done +#16 exporting manifest list sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 0.0s done +#16 ... + +#17 [auth] /:pull,push token for registry-1.docker.io +#17 DONE 0.0s + +#16 exporting to image +#16 pushing layers +#16 pushing layers 3.6s done +#16 pushing manifest for docker.io//:latest@sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 +#16 pushing manifest for docker.io//:latest@sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 1.4s done +#16 DONE 5.6s +``` + +> **Note** +> +> * `` must be a valid Docker ID and `` and valid repository on +> Docker Hub. +> * The `--platform` flag informs buildx to create Linux images for AMD 64-bit, +> Arm 64-bit, and Armv7 architectures. +> * The `--push` flag generates a multi-arch manifest and pushes all the images +> to Docker Hub. + +Inspect the image using [`docker buildx imagetools` command](../../engine/reference/commandline/buildx_imagetools.md): + +```console +$ docker buildx imagetools inspect /:latest +Name: docker.io//:latest +MediaType: application/vnd.docker.distribution.manifest.list.v2+json +Digest: sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 + +Manifests: + Name: docker.io//:latest@sha256:71d7ecf3cd12d9a99e73ef448bf63ae12751fe3a436a007cb0969f0dc4184c8c + MediaType: application/vnd.docker.distribution.manifest.v2+json + Platform: linux/amd64 + + Name: docker.io//:latest@sha256:5ba4ceea65579fdd1181dfa103cc437d8e19d87239683cf5040e633211387ccf + MediaType: application/vnd.docker.distribution.manifest.v2+json + Platform: linux/arm64 + + Name: docker.io//:latest@sha256:29666fb23261b1f77ca284b69f9212d69fe5b517392dbdd4870391b7defcc116 + MediaType: application/vnd.docker.distribution.manifest.v2+json + Platform: linux/arm/v7 +``` + +The image is now available on Docker Hub with the tag `/:latest`. +You can use this image to run a container on Intel laptops, Amazon EC2 Graviton +instances, Raspberry Pis, and on other architectures. Docker pulls the correct +image for the current architecture, so Raspberry PIs run the 32-bit Arm version +and EC2 Graviton instances run 64-bit Arm. + +The digest identifies a fully qualified image variant. You can also run images +targeted for a different architecture on Docker Desktop. For example, when +you run the following on a macOS: + + ```console +$ docker run --rm docker.io//:latest@sha256:2b77acdfea5dc5baa489ffab2a0b4a387666d1d526490e31845eb64e3e73ed20 uname -m +aarch64 +``` + +```console +$ docker run --rm docker.io//:latest@sha256:723c22f366ae44e419d12706453a544ae92711ae52f510e226f6467d8228d191 uname -m +armv7l +``` + +In the above example, `uname -m` returns `aarch64` and `armv7l` as expected, +even when running the commands on a native macOS or Windows developer machine. + +## Support on Docker Desktop + +[Docker Desktop](../../desktop/index.md) provides `binfmt_misc` +multi-architecture support, which means you can run containers for different +Linux architectures such as `arm`, `mips`, `ppc64le`, and even `s390x`. + +This does not require any special configuration in the container itself as it +uses [qemu-static](https://wiki.qemu.org/Main_Page){: target="_blank" rel="noopener" class="_" } +from the **Docker for Mac VM**. Because of this, you can run an ARM container, +like the `arm32v7` or `ppc64le` variants of the busybox image. diff --git a/develop/develop-images/multistage-build.md b/build/building/multi-stage.md similarity index 83% rename from develop/develop-images/multistage-build.md rename to build/building/multi-stage.md index 611b6aea13..e5d1eba545 100644 --- a/develop/develop-images/multistage-build.md +++ b/build/building/multi-stage.md @@ -1,18 +1,19 @@ --- -description: Keeping your images small with multi-stage images -keywords: images, containers, best practices, multi-stage, multistage -title: Use multi-stage builds +title: Multi-stage builds +description: Keeping your images small with multi-stage builds +keywords: build, best practices redirect_from: - /engine/userguide/eng-image/multistage-build/ +- /develop/develop-images/multistage-build/ --- -Multistage builds are useful to anyone who has struggled to optimize Dockerfiles -while keeping them easy to read and maintain. +Multi-stage builds are useful to anyone who has struggled to optimize +Dockerfiles while keeping them easy to read and maintain. -> **Acknowledgment**: +> **Acknowledgment** +> > Special thanks to [Alex Ellis](https://twitter.com/alexellisuk) for granting -> permission to use his blog post -> [Builder pattern vs. Multi-stage builds in Docker](https://blog.alexellis.io/mutli-stage-docker-builds/) +> permission to use his blog post [Builder pattern vs. Multi-stage builds in Docker](https://blog.alexellis.io/mutli-stage-docker-builds/) > as the basis of the examples below. ## Before multi-stage builds @@ -31,10 +32,10 @@ to use for production, which only contained your application and exactly what was needed to run it. This has been referred to as the "builder pattern". Maintaining two Dockerfiles is not ideal. -Here's an example of a `Dockerfile.build` and `Dockerfile` which adhere to the +Here's an example of a `build.Dockerfile` and `Dockerfile` which adhere to the builder pattern above: -**`Dockerfile.build`**: +**`build.Dockerfile`**: ```dockerfile # syntax=docker/dockerfile:1 @@ -42,7 +43,7 @@ FROM golang:1.16 WORKDIR /go/src/github.com/alexellis/href-counter/ COPY app.go ./ RUN go get -d -v golang.org/x/net/html \ - && CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app . + && CGO_ENABLED=0 go build -a -installsuffix cgo -o app . ``` Notice that this example also artificially compresses two `RUN` commands together @@ -58,7 +59,7 @@ FROM alpine:latest RUN apk --no-cache add ca-certificates WORKDIR /root/ COPY app ./ -CMD ["./app"] +CMD ["./app"] ``` **`build.sh`**: @@ -66,16 +67,13 @@ CMD ["./app"] ```bash #!/bin/sh echo Building alexellis2/href-counter:build - -docker build --build-arg https_proxy=$https_proxy --build-arg http_proxy=$http_proxy \ - -t alexellis2/href-counter:build . -f Dockerfile.build +docker build -t alexellis2/href-counter:build . -f build.Dockerfile docker container create --name extract alexellis2/href-counter:build docker container cp extract:/go/src/github.com/alexellis/href-counter/app ./app docker container rm -f extract echo Building alexellis2/href-counter:latest - docker build --no-cache -t alexellis2/href-counter:latest . rm ./app ``` @@ -93,24 +91,23 @@ With multi-stage builds, you use multiple `FROM` statements in your Dockerfile. Each `FROM` instruction can use a different base, and each of them begins a new stage of the build. You can selectively copy artifacts from one stage to another, leaving behind everything you don't want in the final image. To show -how this works, let's adapt the Dockerfile from the previous section to use +how this works, let's adapt the `Dockerfile` from the previous section to use multi-stage builds. -**`Dockerfile`**: - ```dockerfile # syntax=docker/dockerfile:1 + FROM golang:1.16 WORKDIR /go/src/github.com/alexellis/href-counter/ RUN go get -d -v golang.org/x/net/html COPY app.go ./ -RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app . +RUN CGO_ENABLED=0 go build -a -installsuffix cgo -o app . FROM alpine:latest RUN apk --no-cache add ca-certificates WORKDIR /root/ COPY --from=0 /go/src/github.com/alexellis/href-counter/app ./ -CMD ["./app"] +CMD ["./app"] ``` You only need the single Dockerfile. You don't need a separate build script, @@ -122,7 +119,7 @@ $ docker build -t alexellis2/href-counter:latest . The end result is the same tiny production image as before, with a significant reduction in complexity. You don't need to create any intermediate -images and you don't need to extract any artifacts to your local system at all. +images, and you don't need to extract any artifacts to your local system at all. How does it work? The second `FROM` instruction starts a new build stage with the `alpine:latest` image as its base. The `COPY --from=0` line copies just the @@ -140,11 +137,12 @@ Dockerfile are re-ordered later, the `COPY` doesn't break. ```dockerfile # syntax=docker/dockerfile:1 + FROM golang:1.16 AS builder WORKDIR /go/src/github.com/alexellis/href-counter/ RUN go get -d -v golang.org/x/net/html -COPY app.go ./ -RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app . +COPY app.go ./ +RUN CGO_ENABLED=0 go build -a -installsuffix cgo -o app . FROM alpine:latest RUN apk --no-cache add ca-certificates @@ -186,10 +184,12 @@ COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf ## Use a previous stage as a new stage -You can pick up where a previous stage left off by referring to it when using the `FROM` directive. For example: +You can pick up where a previous stage left off by referring to it when using +the `FROM` directive. For example: ```dockerfile # syntax=docker/dockerfile:1 + FROM alpine:latest AS builder RUN apk --no-cache add build-base @@ -204,4 +204,4 @@ RUN g++ -o /binary source.cpp ## Version compatibility -Multistage build syntax was introduced in Docker Engine 17.05. +Multi-stage build syntax was introduced in Docker Engine 17.05. diff --git a/build/building/packaging.md b/build/building/packaging.md new file mode 100644 index 0000000000..6205b023b5 --- /dev/null +++ b/build/building/packaging.md @@ -0,0 +1,213 @@ +--- +title: Packaging your software +keywords: build, buildx, buildkit, getting started, dockerfile +redirect_from: +- /build/hellobuild/ +--- + +## Dockerfile + +It all starts with a Dockerfile. + +Docker builds images by reading the instructions from a Dockerfile. This is a +text file containing instructions that adhere to a specific format needed to +assemble your application into a container image and for which you can find +its specification reference in the [Dockerfile reference](../../engine/reference/builder.md). + +Here are the most common types of instructions: + +| Instruction | Description | +|--------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`FROM `](../../engine/reference/builder.md#from) | Defines a base for your image. | +| [`RUN `](../../engine/reference/builder.md#run) | Executes any commands in a new layer on top of the current image and commits the result. `RUN` also has a shell form for running commands. | +| [`WORKDIR `](../../engine/reference/builder.md#workdir) | Sets the working directory for any `RUN`, `CMD`, `ENTRYPOINT`, `COPY`, and `ADD` instructions that follow it in the Dockerfile. | +| [`COPY `](../../engine/reference/builder.md#copy) | Copies new files or directories from `` and adds them to the filesystem of the container at the path ``. | +| [`CMD `](../../engine/reference/builder.md#cmd) | Lets you define the default program that is run once you start the container based on this image. Each Dockerfile only has one `CMD`, and only the last `CMD` instance is respected when multiple exist. | + +Dockerfiles are crucial inputs for image builds and can facilitate automated, +multi-layer image builds based on your unique configurations. Dockerfiles can +start simple and grow with your needs and support images that require complex +instructions. For all the possible instructions, see the [Dockerfile reference](../../engine/reference/builder.md). + +Docker images consist of **read-only layers**, each resulting from an +instruction in the Dockerfile. Layers are stacked sequentially and each one is +a delta representing the changes applied to the previous layer. + +## Example + +Here's a simple Dockerfile example to get you started with building images. +We'll take a simple "Hello World" Python Flask application, and bundle it into +a Docker image that can test locally or deploy anywhere! + +Let's say we have a `hello.py` file with the following content: + +```python +from flask import Flask +app = Flask(__name__) + +@app.route("/") +def hello(): + return "Hello World!" +``` + +Don't worry about understanding the full example if you're not familiar with +Python, it's just a simple web server that will contain a single page that +says "Hello World". + +> **Note** +> +> If you test the example, make sure to copy over the indentation as well! For +> more information about this sample Flask application, check the +> [Flask Quickstart](https://flask.palletsprojects.com/en/2.1.x/quickstart/){:target="_blank" rel="noopener" class="_"} +> page. + +Here's the Dockerfile that will be used to create an image for our application: + +```dockerfile +# syntax=docker/dockerfile:1 +FROM ubuntu:22.04 + +# install app dependencies +RUN apt-get update && apt-get install -y python3 python3-pip +RUN pip install flask==2.1.* + +# install app +COPY hello.py / + +# final configuration +ENV FLASK_APP=hello +EXPOSE 8000 +CMD flask run --host 0.0.0.0 --port 8000 +``` + +We start by specifying the [syntax directive](../../engine/reference/builder.md#syntax). +It pins the exact version of the Dockerfile syntax we're using: + +```dockerfile +# syntax=docker/dockerfile:1 +``` + +As a [best practice](../../develop/dev-best-practices.md), this should be the +very first line in all our Dockerfiles as it informs BuildKit the right version +of the Dockerfile to use. + +Next we define the first instruction: + +```dockerfile +FROM ubuntu:22.04 +``` + +Here the [`FROM` instruction](../../engine/reference/builder.md#from) sets our +base image to the 22.04 release of Ubuntu. All following instructions are +executed on this base image, in this case, an Ubuntu environment. The notation +`ubuntu:22:04`, follows the `name:tag` standard for naming docker images. When +you build your image you use this notation to name your images and use it to +specify any existing Docker image. There are many public images you can +leverage in your projects. Explore [Docker Hub](https://hub.docker.com/search?image_filter=official&q=&type=image){:target="_blank" rel="noopener" class="_"} +to find out. + +```dockerfile +# install app dependencies +RUN apt-get update && apt-get install -y python3 python3-pip +``` + +This [`RUN` instruction](../../engine/reference/builder.md#run) executes a shell +command in the build context. A build's context is the set of files located in +the specified PATH or URL. + +In this example, our context is a full Ubuntu operating system, so we have +access to its package manager, apt. The provided commands update our package +lists and then, after that succeeds, installs `python3` and `pip`, the package +manager for Python. + +Also note `# install app dependencies` line. This is a comment. Comments in +Dockerfiles begin with the `#` symbol. As your Dockerfile evolves, comments can +be instrumental to document how your dockerfile works for any future readers +and editors of the file. + +> **Note** +> +> Starting your Dockerfile by a `#` like regular comments is treated as a +> directive when you are using BuildKit (default), otherwise it is ignored. + +```dockerfile +RUN pip install flask==2.1.* +``` + +This second `RUN` instruction requires that we've installed pip in the layer +before. After applying the previous directive, we can use the pip command to +install the flask web framework. This is the framework we've used to write +our basic "Hello World" application from above, so to run it in Docker, we'll +need to make sure it's installed. + +```dockerfile +COPY hello.py / +``` + +Now we use the [`COPY` instruction](../../engine/reference/builder.md#copy) to +copy our `hello.py` file from the local build context into the root directory +of our image. After being executed, we'll end up with a file called `/hello.py` +inside the image. + +```dockerfile +ENV FLASK_APP=hello +``` + +This [`ENV` instruction](../../engine/reference/builder.md#env) sets a Linux +environment variable we'll need later. This is a flask-specific variable, +that configures the command later used to run our `hello.py` application. +Without this, flask wouldn't know where to find our application to be able to +run it. + +```dockerfile +EXPOSE 8000 +``` + +This [`EXPOSE` instruction](../../engine/reference/builder.md#expose) marks that +our final image has a service listening on port `8000`. This isn't required, +but it is a good practice, as users and tools can use this to understand what +your image does. + +```dockerfile +CMD flask run --host 0.0.0.0 --port 8000 +``` + +Finally, [`CMD` instruction](../../engine/reference/builder.md#cmd) sets the +command that is run when the user starts a container based on this image. In +this case we'll start the flask development server listening on all addresses +on port `8000`. + +## Testing + +To test our Dockerfile, we'll first build it using the [`docker build` command](../../engine/reference/commandline/build.md): + +```console +$ docker build -t test:latest . +``` + +* `-t test:latest` option specifies the name (required) and tag (optional) of + the image we're building. +* `.` specifies the build context as the current directory. In this example, + this is where build expects to find the Dockerfile and the local files the + Dockerfile needs to access, in this case your python application. + +So, in accordance with the build command issued and how build context works, +your Dockerfile and python app need to be in the same directory. + +Now run your newly built image: + +```console +$ docker run -p 8000:8000 test:latest +``` + +From your computer, open a browser and navigate to `http://localhost:8000` + +> **Note** +> +> You can also build and run using [Play with Docker](https://labs.play-with-docker.com){:target="_blank" rel="noopener" class="_"} +> that provides you with a temporary Docker instance in the cloud. + +## Other resources + +If you are interested in examples in other languages, such as Go, check out +our [language-specific guides](../../language/index.md) in the Guides section. diff --git a/build/buildx/drivers/remote.md b/build/buildx/drivers/remote.md deleted file mode 100644 index e3eb1cdccf..0000000000 --- a/build/buildx/drivers/remote.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: "Remote driver" -keywords: build, buildx, driver, builder, remote -fetch_remote: - line_start: 2 - line_end: -1 ---- - -> Beta -> -> Remote driver is currently available as a beta feature. We recommend that you -> do not use this feature in production environments. You can [build Buildx from source](https://github.com/docker/buildx#building){: target="_blank" rel="noopener" class="_"} -> to test the remote driver or use the following command to download and -> install an edge release of Buildx: -> -> ```console -> $ echo "FROM docker/buildx-bin:master" | docker buildx build --platform=local --output . -f - . -> $ mkdir -p ~/.docker/cli-plugins/ -> $ mv buildx ~/.docker/cli-plugins/docker-buildx -> ``` -{: .important} - diff --git a/build/buildx/index.md b/build/buildx/index.md deleted file mode 100644 index 8b9ba0f110..0000000000 --- a/build/buildx/index.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Working with Buildx -description: Working with Docker Buildx -keywords: build, buildx, buildkit -redirect_from: -- /buildx/working-with-buildx/ ---- - -## Overview - -Docker Buildx is a CLI plugin that extends the docker command with the full -support of the features provided by [Moby BuildKit](https://github.com/moby/buildkit){:target="_blank" rel="noopener" class="_"} -builder toolkit. It provides the same user experience as docker build with many -new features like creating scoped builder instances and building against -multiple nodes concurrently. - -## Build with Buildx - -To start a new build, run the command `docker buildx build .` - -```console -$ docker buildx build . -[+] Building 8.4s (23/32) - => ... -``` - -Buildx builds using the BuildKit engine and does not require `DOCKER_BUILDKIT=1` -environment variable to start the builds. - -The [`docker buildx build` command](../../engine/reference/commandline/buildx_build.md) -supports features available for `docker build`, including features such as -outputs configuration, inline build caching, and specifying target platform. -In addition, Buildx also supports new features that are not yet available for -regular `docker build` like building manifest lists, distributed caching, and -exporting build results to OCI image tarballs. - -Buildx is flexible and can be run in different configurations that are exposed -through various "drivers". Each driver defines how and where a build should -run, and have different feature sets. - -We currently support the following drivers: - -* The `docker` driver ([guide](drivers/docker.md), [reference](/engine/reference/commandline/buildx_create/#driver)) -* The `docker-container` driver ([guide](drivers/docker-container.md), [reference](/engine/reference/commandline/buildx_create/#driver)) -* The `kubernetes` driver ([guide](drivers/kubernetes.md), [reference](/engine/reference/commandline/buildx_create/#driver)) -* The `remote` driver ([guide](drivers/remote.md)) - -For more information on drivers, see the [drivers guide](drivers/index.md). - -## High-level build options with Bake - -Check out our guide about [Bake](../bake/index.md) to get started with the -[`docker buildx bake` command](../../engine/reference/commandline/buildx_bake.md). diff --git a/build/buildx/multiplatform-images.md b/build/buildx/multiplatform-images.md deleted file mode 100644 index 21fda31c31..0000000000 --- a/build/buildx/multiplatform-images.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Building multi-platform images -description: Different strategies for building multi-platform images -keywords: build, buildx, buildkit, multi-platform images ---- - -BuildKit is designed to work well for building for multiple platforms and not -only for the architecture and operating system that the user invoking the build -happens to run. - -When you invoke a build, you can set the `--platform` flag to specify the target -platform for the build output, (for example, `linux/amd64`, `linux/arm64`, or -`darwin/amd64`). - -When the current builder instance is backed by the `docker-container` driver, -you can specify multiple platforms together. In this case, it builds a manifest -list which contains images for all specified architectures. When you use this -image in [`docker run`](../../engine/reference/commandline/run.md) or -[`docker service`](../../engine/reference/commandline/service.md), Docker picks -the correct image based on the node's platform. - -You can build multi-platform images using three different strategies that are -supported by Buildx and Dockerfiles: - -1. Using the QEMU emulation support in the kernel -2. Building on multiple native nodes using the same builder instance -3. Using a stage in Dockerfile to cross-compile to different architectures - -QEMU is the easiest way to get started if your node already supports it (for -example. if you are using Docker Desktop). It requires no changes to your -Dockerfile and BuildKit automatically detects the secondary architectures that -are available. When BuildKit needs to run a binary for a different architecture, -it automatically loads it through a binary registered in the `binfmt_misc` -handler. - -For QEMU binaries registered with `binfmt_misc` on the host OS to work -transparently inside containers, they must be statically compiled and registered -with the `fix_binary` flag. This requires a kernel >= 4.8 and -binfmt-support >= 2.1.7. You can check for proper registration by checking if -`F` is among the flags in `/proc/sys/fs/binfmt_misc/qemu-*`. While Docker -Desktop comes preconfigured with `binfmt_misc` support for additional platforms, -for other installations it likely needs to be installed using -[`tonistiigi/binfmt`](https://github.com/tonistiigi/binfmt){:target="_blank" rel="noopener" class="_"} -image. - -```console -$ docker run --privileged --rm tonistiigi/binfmt --install all -``` - -Using multiple native nodes provide better support for more complicated cases -that are not handled by QEMU and generally have better performance. You can -add additional nodes to the builder instance using the `--append` flag. - -Assuming contexts `node-amd64` and `node-arm64` exist in `docker context ls`; - -```console -$ docker buildx create --use --name mybuild node-amd64 -mybuild -$ docker buildx create --append --name mybuild node-arm64 -$ docker buildx build --platform linux/amd64,linux/arm64 . -``` - -Finally, depending on your project, the language that you use may have good -support for cross-compilation. In that case, multi-stage builds in Dockerfiles -can be effectively used to build binaries for the platform specified with -`--platform` using the native architecture of the build node. A list of build -arguments like `BUILDPLATFORM` and `TARGETPLATFORM` is available automatically -inside your Dockerfile and can be leveraged by the processes running as part -of your build. - -```dockerfile -# syntax=docker/dockerfile:1 -FROM --platform=$BUILDPLATFORM golang:alpine AS build -ARG TARGETPLATFORM -ARG BUILDPLATFORM -RUN echo "I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /log -FROM alpine -COPY --from=build /log /log -``` diff --git a/build/bake/build-contexts.md b/build/customize/bake/build-contexts.md similarity index 78% rename from build/bake/build-contexts.md rename to build/customize/bake/build-contexts.md index 7026e6f005..556900ee52 100644 --- a/build/bake/build-contexts.md +++ b/build/customize/bake/build-contexts.md @@ -1,6 +1,8 @@ --- title: "Defining additional build contexts and linking targets" keywords: build, buildx, bake, buildkit, hcl +redirect_from: +- /build/bake/build-contexts/ fetch_remote: line_start: 2 line_end: -1 diff --git a/build/bake/compose-file.md b/build/customize/bake/compose-file.md similarity index 76% rename from build/bake/compose-file.md rename to build/customize/bake/compose-file.md index d38ef185bd..9accdcbf67 100644 --- a/build/bake/compose-file.md +++ b/build/customize/bake/compose-file.md @@ -1,6 +1,8 @@ --- title: "Building from Compose file" keywords: build, buildx, bake, buildkit, compose +redirect_from: +- /build/bake/compose-file/ fetch_remote: line_start: 2 line_end: -1 diff --git a/build/bake/configuring-build.md b/build/customize/bake/configuring-build.md similarity index 73% rename from build/bake/configuring-build.md rename to build/customize/bake/configuring-build.md index f56cc62bba..156750c519 100644 --- a/build/bake/configuring-build.md +++ b/build/customize/bake/configuring-build.md @@ -1,6 +1,8 @@ --- title: "Configuring builds" keywords: build, buildx, bake, buildkit, hcl, json +redirect_from: +- /build/bake/configuring-build/ fetch_remote: line_start: 2 line_end: -1 diff --git a/build/bake/file-definition.md b/build/customize/bake/file-definition.md similarity index 75% rename from build/bake/file-definition.md rename to build/customize/bake/file-definition.md index 02fdb5c8b6..2ee188cedb 100644 --- a/build/bake/file-definition.md +++ b/build/customize/bake/file-definition.md @@ -1,6 +1,8 @@ --- title: "Bake file definition" keywords: build, buildx, bake, buildkit, hcl, json, compose +redirect_from: +- /build/bake/file-definition/ fetch_remote: line_start: 2 line_end: -1 diff --git a/build/bake/hcl-funcs.md b/build/customize/bake/hcl-funcs.md similarity index 77% rename from build/bake/hcl-funcs.md rename to build/customize/bake/hcl-funcs.md index c4dde8f340..3773921185 100644 --- a/build/bake/hcl-funcs.md +++ b/build/customize/bake/hcl-funcs.md @@ -1,6 +1,8 @@ --- title: "User defined HCL functions" keywords: build, buildx, bake, buildkit, hcl +redirect_from: +- /build/bake/hcl-funcs/ fetch_remote: line_start: 2 line_end: -1 diff --git a/build/bake/index.md b/build/customize/bake/index.md similarity index 83% rename from build/bake/index.md rename to build/customize/bake/index.md index 9f61a12efc..63f7a41c80 100644 --- a/build/bake/index.md +++ b/build/customize/bake/index.md @@ -1,6 +1,8 @@ --- title: "High-level build options with Bake" keywords: build, buildx, bake, buildkit, hcl, json, compose +redirect_from: +- /build/bake/ fetch_remote: line_start: 2 line_end: -1 diff --git a/build/hellobuild.md b/build/hellobuild.md deleted file mode 100644 index c516317792..0000000000 --- a/build/hellobuild.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: Hello Build -description: Build Hello World -keywords: build, buildx, buildkit, getting started, dockerfile, image layers, build instructions, build context ---- - -## Hello Build! - -It all starts with a Dockerfile. - -Dockerfiles are text files containing instructions. Dockerfiles adhere to a specific format and contain a **set of instructions** for which you can find a full reference in the [Dockerfile reference](../../engine/reference/builder). -Docker builds images by reading the instructions from a Dockerfile. - -Docker images consist of **read-only layers**, each resulting from an instruction in the Dockerfile. Layers are stacked sequentially and each one is a delta representing the changes applied to the previous layer. - -## Dockerfile basics - -A Dockerfile is a text file containing all necessary instructions needed to assemble your application into a Docker container image. - -Here are the most common types of instructions: - -* [**FROM \**](../../engine/reference/builder/#from) - defines a base for your image. -* [**RUN \**](../../engine/reference/builder/#run) - executes any commands in a new layer on top of the current image and commits the result. - RUN also has a shell form for running commands. -* [**WORKDIR \**](../../engine/reference/builder/#workdir) - sets the working directory for any RUN, CMD, ENTRYPOINT, COPY, and ADD instructions that follow it in the Dockerfile. -* [**COPY \ \**](../../engine/reference/builder/#copy) - copies new files or directories from `` and adds them to the filesystem of the container at the path ``. -* [**CMD \**](../../engine/reference/builder/#cmd) - lets you define the default program that is run once you start the container based on this image. -Each Dockerfile only has one CMD, and only the last CMD instance is respected when multiple exist. - -Dockerfiles are crucial inputs for image builds and can facilitate automated, multi-layer image builds based on your unique configurations. Dockerfiles can start simple and grow with your needs and support images that require complex instructions. -For all the possible instructions, see the [Dockerfile reference](../../engine/reference/builder/). - -## Example -Here’s a simple Dockerfile example to get you started with building images. We’ll take a simple "Hello World" Python Flask application, and bundle it into a Docker image that we can test locally or deploy anywhere! - -**Sample A** -Let’s say we have the following in a `hello.py` file in our local directory: - -```python -from flask import Flask -app = Flask(__name__) - -@app.route("/") -def hello(): - return "Hello World!" -``` - -Don’t worry about understanding the full example if you’re not familiar with Python - it’s just a simple web server that will contain a single page that says “Hello World”. - -> **Note** -> -> If you test the example, make sure to copy over the indentation as well! For more information about this sample Flask application, check the [Flask Quickstart](https://flask.palletsprojects.com/en/2.1.x/quickstart/){:target="_blank" rel="noopener" class="_"} page. - - -**Sample B** -Here’s a Dockerfile that Docker Build can use to create an image for our application: - -```dockerfile -# syntax=docker/dockerfile:1 -FROM ubuntu:22.04 - -# install app dependencies -RUN apt-get update && apt-get install -y python3 python3-pip -RUN pip install flask==2.1.* - -# install app -COPY hello.py / - -# final configuration -ENV FLASK_APP=hello -EXPOSE 8000 -CMD flask run --host 0.0.0.0 --port 8000 -``` - -* `# syntax=docker/dockerfile:1` - - This is our syntax directive. It pins the exact version of the dockerfile syntax we’re using. As a [best practice](../../develop/dev-best-practices/), this should be the very first line in all our Dockerfiles as it informs Buildkit the right version of the Dockerfile to use. - See also [Syntax](../../engine/reference/builder/#syntax). - - > **Note** - > - > Initiated by a `#` like regular comments, this line is treated as a directive when you are using BuildKit (default), otherwise it is ignored. - - -* `FROM ubuntu:22.04` - - Here the `FROM` instruction sets our base image to the 22.04 release of Ubuntu. All following instructions are executed on this base image, in this case, a Ubuntu environment. - The notation `ubuntu:22:04`, follows the `name:tag` standard for naming docker images. - When you build your image you use this notation to name your images and use it to specify any existing Docker image. - There are many public images you can leverage in your projects. - Explore [Docker Hub](https://hub.docker.com/search?image_filter=official&q=&type=image){:target="_blank" rel="noopener" class="_"} to find out. - -* `# install app dependencies` - - Comments in dockerfiles begin with the `#` symbol. - As your Dockerfile evolves, comments can be instrumental to document how your dockerfile works for any future readers and editors of the file. - See also the [FROM instruction](../../engine/reference/builder/#from) page in the Dockerfile reference. - -* `RUN apt-get update && apt-get install -y python3 python3-pip` - - This `RUN` instruction executes a shell command in the build context. A build's context is the set of files located in the specified PATH or URL. In this example, our context is a full Ubuntu operating system, so we have access to its package manager, apt. The provided commands update our package lists and then, after that succeeds, installs python3 and pip, the package manager for Python. - See also the [RUN instruction](../../engine/reference/builder/#run) page in the Dockerfile reference. - -* `RUN pip install flask` - - This second `RUN` instruction requires that we’ve installed pip in the layer before. After applying the previous directive, we can use the pip command to install the flask web framework. This is the framework we’ve used to write our basic “Hello World” application from above, so to run it in Docker, we’ll need to make sure it’s installed. - See also the [RUN instruction](../../engine/reference/builder/#run) page in the Dockerfile reference. - -* `COPY hello.py /` - - This COPY instruction copies our `hello.py` file from the build’s context local directory into the root directory of our image. After this executes, we’ll end up with a file called `/hello.py` inside the image, with all the content of our local copy! - See also the [COPY instruction](../../engine/reference/builder/#copy) page in the Dockerfile reference. - - -* `ENV FLASK_APP=hello` - - This ENV instruction sets a Linux environment variable we’ll need later. This is a flask-specific variable, that configures the command later used to run our `hello.py` application. Without this, flask wouldn’t know where to find our application to be able to run it. - See also the [ENV instruction](../../engine/reference/builder/#env) page in the Dockerfile reference. - - -* `EXPOSE 8000` - - This EXPOSE instruction marks that our final image has a service listening on port 8000. This isn’t required, but it is a good practice, as users and tools can use this to understand what your image does. - See also the [EXPOSE instruction](../../engine/reference/builder/#expose) page in the Dockerfile reference. - -* `CMD flask run --host 0.0.0.0 --port 8000` - - This CMD instruction sets the command that is run when the user starts a container based on this image. In this case we’ll start the flask development server listening on all hosts on port 8000. - [CMD instruction](../../engine/reference/builder/#cmd) page in the Dockerfile reference. - -## Test the example - -Go ahead and try this example in your local Docker installation or you can use [Play with Docker](https://labs.play-with-docker.com){:target="_blank" rel="noopener" class="_"} that provides you with a temporary Docker instance on the cloud. - -To test this example: - -1. Create a file hello.py with the content of sample A. - -2. Create a file named Dockerfile without an extension with the contents of sample B. - -3. From your Docker instance build it with `docker build -t test:latest .` - - Breaking down the docker build command: - * **`-t test:latest`** option specifies the name (required) and tag (optional) of the image we’re building. - * **`.`** specifies the build context as the current directory. In this example, this is where build expects to find the Dockerfile and the local files the Dockerfile needs to access, in this case your python application. - - So, in accordance with the build command issued and how build context works, your Dockerfile and python app need to be on the same directory. - -4. Run your newly built image with `docker run -p 8000:8000 test:latest` - - From your computer, open a browser and navigate to `http://localhost:8000` or, if you’re using [Play with Docker](https://labs.play-with-docker.com){:target="_blank" rel="noopener" class="_"}, click on Open Port. - -## Other resources - -If you are interested in examples in other languages, such as GO, check out our [language-specific guides](../../language) in the Guides section. diff --git a/build/index.md b/build/index.md index 085349c41f..58635c18cc 100644 --- a/build/index.md +++ b/build/index.md @@ -2,82 +2,111 @@ title: Overview of Docker Build description: Introduction and overview of Docker Build keywords: build, buildx, buildkit +redirect_from: +- /build/buildx/ +- /buildx/working-with-buildx/ --- -Docker Build is one of Docker Engine’s most used features. Whenever you are +## Overview + +Docker Build is one of Docker Engine's most used features. Whenever you are creating an image you are using Docker Build. Build is a key part of your software development life cycle allowing you to package and bundle your code and ship it anywhere. Engine uses a client-server architecture and is composed of multiple components and tools. The most common method of executing a build is by issuing a -`docker build` command from the Docker CLI. The CLI sends the request to Docker -Engine which, in turn, executes your build. +[`docker build` command](../engine/reference/commandline/build.md). The CLI +sends the request to Docker Engine which, in turn, executes your build. -There are now two components in Engine that can be used to create the build. -Starting with the 18.09 release, Engine is shipped with [Moby BuildKit](https://github.com/moby/buildkit){:target="_blank" rel="noopener" class="_"}, +There are now two components in Engine that can be used to build an image. +Starting with the [18.09 release](../engine/release-notes/18.09.md#18090), Engine is +shipped with Moby [BuildKit](https://github.com/moby/buildkit){:target="_blank" rel="noopener" class="_"}, the new component for executing your builds by default. -With BuildKit, the new client [Docker Buildx](buildx/index.md), becomes -available as a CLI plugin. Docker Buildx extends the docker build command - -namely through the additional `docker buildx build` command - and fully -supports the new features BuildKit offers. - BuildKit is the backend evolution from the Legacy Builder, it comes with new and much improved functionality that can be powerful tools for improving your builds' performance or reusability of your Dockerfiles, and it also introduces support for complex scenarios. -## Docker Build features +The new client [Docker Buildx](https://github.com/docker/buildx){:target="_blank" rel="noopener" class="_"}, +is a CLI plugin that extends the docker command with the full support of the +features provided by BuildKit builder toolkit. `docker buildx build` provides +the same user experience as `docker build` with many new features like creating +scoped builder instances, building against multiple nodes concurrently, outputs +configuration, inline build caching, and specifying target platform. In +addition, Buildx also supports new features that are not yet available for +regular `docker build` like building manifest lists, distributed caching, and +exporting build results to OCI image tarballs. -Docker Build is way more than your `docker build` command and is not only about packaging your code, it’s a whole ecosystem of tools and features that support you not only with common workflow tasks but also provides you with support for more complex and advanced scenarios. -Here’s an overview of all the use cases with which Build can support you: +Docker Build is way more than a simple build command and is not only about +packaging your code, it's a whole ecosystem of tools and features that support +not only common workflow tasks but also provides support for more complex and +advanced scenarios: -### Building your images +## Building your images -* **Packaging your software** -Bundle and package your code to run anywhere, from your local Docker Desktop, to Docker Engine and Kubernetes on the cloud. -To get started with Build, see the [Hello Build](hellobuild.md) page. +### Packaging your software + +Bundle and package your code to run anywhere, from your local Docker Desktop, +to Docker Engine and Kubernetes on the cloud. To get started with Build, +see the [Packaging your software](building/packaging.md) page. + +### Choosing a build driver -* **Choosing a build driver** Run Buildx with different configurations depending on the scenario you are working on, regardless of whether you are using your local machine or a remote compute cluster, all from the comfort of your local working environment. -For more information on drivers, see the [drivers guide](buildx/drivers/index.md). +For more information on drivers, see the [drivers guide](building/drivers/index.md). -* **Optimizing builds with cache management** -Improve build performance by using a persistent shared build cache to avoid repeating costly operations such as package installations, downloading files from the internet, or code build steps. +### Optimizing builds with cache management -* **Creating build-once, run-anywhere with multi-platform builds** -Collaborate across platforms with one build artifact. -See [Build multi-platform images](buildx/multiplatform-images.md). +Improve build performance by using a persistent shared build cache to avoid +repeating costly operations such as package installations, downloading files +from the internet, or code build steps. -### Automating your builds +### Creating build-once, run-anywhere with multi-platform builds -* **Integrating with GitHub** -Automate your image builds to run in GitHub actions using the official docker build actions. See: - * [GitHub Action to build and push Docker images with Buildx](https://github.com/docker/build-push-action). - * [GitHub Action to extract metadata from Git reference and GitHub events](https://github.com/docker/metadata-action/). +Collaborate across platforms with one build artifact. See +[Multi-platform images](building/multi-platform.md) page. -* **Orchestrating builds across complex projects together** -Connect your builds together and easily parameterize your images using buildx bake. -See [High-level build options with Bake](bake/index.md). +## Continuous integration -### Customizing your Builds +### GitHub Actions -* **Select your build output format** -Choose from a variety of available output formats, to export any artifact you like from BuildKit, not just docker images. -See [Set the export action for the build result](../engine/reference/commandline/buildx_build.md/#output). +Automate your image builds to run in GitHub actions using the official docker +build actions: -* **Managing build secrets** -Securely access protected repositories and resources at build time without leaking data into the final build or the cache. +* [GitHub Action to build and push Docker images with Buildx](https://github.com/docker/build-push-action). +* [GitHub Action to extract metadata from Git reference and GitHub events](https://github.com/docker/metadata-action/). -### Extending BuildKit +## Customizing your builds -* **Custom syntax on Dockerfile** -Use experimental versions of the Dockerfile frontend, or even just bring your own to BuildKit using the power of custom frontends. -See also the [Syntax directive](../engine/reference/builder/#syntax). +### Select your build output format -* **Configure BuildKit** -Take a deep dive into the internal BuildKit configuration to get the most out of your builds. -See also [`buildkitd.toml`](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md), the configuration file for `buildkitd`. +Choose from a variety of available output formats, to export any artifact you +like from BuildKit, not just docker images. See [Set the export action for the build result](../engine/reference/commandline/buildx_build.md#output). + +### Managing build secrets + +Securely access protected repositories and resources at build time without +leaking data into the final build or the cache. + +### Orchestrating builds using Bake + +Connect your builds together and easily parameterize your images using buildx bake. +See [High-level build options with Bake](customize/bake/index.md). + +## Extending BuildKit + +### Custom syntax on Dockerfile + +Use experimental versions of the Dockerfile frontend, or even just bring your +own to BuildKit using the power of custom frontends. See also the +[Syntax directive](../engine/reference/builder.md#syntax). + +### Configure BuildKit + +Take a deep dive into the internal BuildKit configuration to get the most out +of your builds. See also [`buildkitd.toml`](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md), +the configuration file for `buildkitd`. diff --git a/build/release-notes.md b/build/release-notes.md index 5f88700dcf..efb93bb7cd 100644 --- a/build/release-notes.md +++ b/build/release-notes.md @@ -6,7 +6,7 @@ toc_max: 2 --- This page contains information about the new features, improvements, and bug -fixes in [Buildx](buildx/index.md). +fixes in [Docker Buildx](https://github.com/docker/buildx){:target="_blank" rel="noopener" class="_"}. ## 0.9.1 @@ -29,7 +29,7 @@ For more details, see the complete release notes in the [Buildx GitHub repositor ### New features -* Support for new [driver `remote`](buildx/drivers/remote.md) that you can use +* Support for new [driver `remote`](building/drivers/remote.md) that you can use to connect to any already running BuildKit instance {% include github_issue.md repo="docker/buildx" number="1078" %} {% include github_issue.md repo="docker/buildx" number="1093" %} {% include github_issue.md repo="docker/buildx" number="1094" %} {% include github_issue.md repo="docker/buildx" number="1103" %} {% include github_issue.md repo="docker/buildx" number="1134" %} @@ -153,7 +153,7 @@ For more details, see the complete release notes in the [Buildx GitHub repositor * Build command now accepts `--build-context` flag to [define additional named build contexts](/engine/reference/commandline/buildx_build/#build-context) for your builds {% include github_issue.md repo="docker/buildx" number="904" %} -* Bake definitions now support [defining dependencies between targets](bake/build-contexts.md) +* Bake definitions now support [defining dependencies between targets](customize/bake/build-contexts.md) and using the result of one target in another build {% include github_issue.md repo="docker/buildx" number="928" %} {% include github_issue.md repo="docker/buildx" number="965" %} {% include github_issue.md repo="docker/buildx" number="963" %} {% include github_issue.md repo="docker/buildx" number="962" %} {% include github_issue.md repo="docker/buildx" number="981" %} diff --git a/compose/compose-file/build.md b/compose/compose-file/build.md index aa86248a9a..62d681ade3 100644 --- a/compose/compose-file/build.md +++ b/compose/compose-file/build.md @@ -430,4 +430,4 @@ services: ## Implementations * [docker-compose](../../compose/index.md) -* [buildx bake](../../build/bake/index.md) +* [buildx bake](../../build/customize/bake/index.md) diff --git a/compose/compose-file/compose-file-v2.md b/compose/compose-file/compose-file-v2.md index d3b97f5a9a..2c526f8caa 100644 --- a/compose/compose-file/compose-file-v2.md +++ b/compose/compose-file/compose-file-v2.md @@ -357,7 +357,7 @@ build: > Added in [version 2.3](compose-versioning.md#version-23) file format Build the specified stage as defined inside the `Dockerfile`. See the -[multi-stage build docs](../../develop/develop-images/multistage-build.md) for +[multi-stage build docs](../../build/building/multi-stage.md) for details. ```yaml diff --git a/compose/compose-file/compose-file-v3.md b/compose/compose-file/compose-file-v3.md index 323426c64f..0d780c34bc 100644 --- a/compose/compose-file/compose-file-v3.md +++ b/compose/compose-file/compose-file-v3.md @@ -392,7 +392,7 @@ build: > Added in [version 3.4](compose-versioning.md#version-34) file format Build the specified stage as defined inside the `Dockerfile`. See the -[multi-stage build docs](../../develop/develop-images/multistage-build.md) for +[multi-stage build docs](../../build/building/multi-stage.md) for details. ```yaml diff --git a/contribute/components/images.md b/contribute/components/images.md index 647dab37ca..3687b947d9 100644 --- a/contribute/components/images.md +++ b/contribute/components/images.md @@ -6,11 +6,13 @@ toc_max: 3 ## Example -- A small image: ![a small cute image](/assets/images/footer_moby_icon.png) +- A small image: ![a small image](/assets/images/footer_moby_icon.png) - A small image that is a link. The extra newline here makes it not show inline: - [![a small cute image](/assets/images/footer_moby_icon.png)](https://www.docker.com/) + [![a small image](/assets/images/footer_moby_icon.png)](https://www.docker.com/) + +- Make the image open in a new tab: [![an image](/assets/images/footer_moby_icon.png)](/assets/images/footer_moby_icon.png){: target="_blank" rel="noopener" class="_"} - Set the size of an image: ![a pretty wide image](/assets/images/banner_image_24512.png){:width="750px"} diff --git a/contribute/components/links.md b/contribute/components/links.md index 7fc916696c..e94157a7e6 100644 --- a/contribute/components/links.md +++ b/contribute/components/links.md @@ -24,6 +24,8 @@ An example of a link to an auto-generated reference page that we pull in during - Keep in mind that this link doesn't resolve until you merge the PR and your docs are published on [docs.docker.com](/). +- It is best practice to avoid the use of absolute links when linking to other docs pages. Otherwise broken links may not be picked up. + ## HTML ```html diff --git a/contribute/contribute-guide.md b/contribute/contribute-guide.md index ac470000ad..353aed2aec 100644 --- a/contribute/contribute-guide.md +++ b/contribute/contribute-guide.md @@ -13,7 +13,7 @@ The live docs are published from the `master` branch. Therefore, you must create There are two ways to contribute a pull request to the docs repository: -1. You can click **Edit this page** option in the right column of every page on [https://docs.docker.com/](https://docs.docker.com/). +1. You can click **Edit this page** option in the right column of every page on [https://docs.docker.com/](/). This opens the GitHub editor, which means you don't need to know a lot about Git, or even about Markdown. When you save, Git prompts you to create a fork if you don't already have one, and to create a branch in your fork and submit the pull request. @@ -21,9 +21,9 @@ There are two ways to contribute a pull request to the docs repository: This is the manual, more advanced version of clicking 'Edit this page' on a published docs page. Initiating a docs changes in a PR from your own branch gives you more flexibility, as you can submit changes to multiple pages or files under a single pull request, and even create new topics. - For a demo of the components, tags, Markdown syntax, styles, etc we use at [https://docs.docker.com/](https://docs.docker.com/), see the Useful components section. + For a demo of the components, tags, Markdown syntax, styles, etc we use at [https://docs.docker.com/](/), see the Useful components section. -### Important files +## Important files Here’s a list of some of the important files: @@ -43,10 +43,10 @@ Help us review your PRs more quickly by following these guidelines. - Try not to touch a large number of files in a single PR if possible. - Don't change whitespace or line wrapping in parts of a file you are not editing for other reasons. Make sure your text editor is not configured to automatically reformat the whole file when saving. -- We highly recommend that you build the docs locally and verify your changes before submitting a PR. See the section [Build and preview the docs locally](#build-and-preview-the-docs-locally). +- We highly recommend that you [build](#build-and-preview-the-docs-locally) and [test](#test-the-docs-locally) the docs locally before submitting a PR. - A Netlify test runs for each PR that is against the `master` branch, and deploys the result of your PR to a staging site. The URL will be available at in the **Conversation** tab. Check the staging site to verify how your changes look and fix issues, if necessary. -## Collaborate on a pull request +### Collaborate on a pull request Unless the PR author specifically disables it, you can push commits into another contributor's PR. You can do it from the command line by adding and fetching @@ -58,7 +58,7 @@ If a PR consists of multiple small addendum commits on top of a more significant one, the commit will usually be "squash-merged", so that only one commit is merged into the `master` branch. In some scenarios where a squash and merge isn't appropriate, all commits are kept separate when merging. -## Per-PR staging on GitHub +### Per-PR staging on GitHub A Netlify test runs for each PR created against the `master` branch and deploys the result of your PR to a staging site. When the site builds successfully, you will see a comment in the **Conversation** tab in the PR stating **Deploy Preview for docsdocker ready!**. Click the **Browse the preview** URL and check the staging site to verify how your changes look and fix issues, if necessary. Reviewers also check the staged site before merging the PR to protect the integrity of the docs site. @@ -71,14 +71,14 @@ git clone --recursive https://github.com/docker/docker.github.io.git cd docker.github.io ``` -Then, build and run the documentation using [Docker Compose](https://docs.docker.com/compose/) +Then, build and run the documentation using [Docker Compose](../compose/index.md) ```bash docker compose up -d --build ``` -> You need Docker Compose to build and run the docs locally. Docker Compose is included with [Docker Desktop](https://docs.docker.com/desktop/). -> If you don't have Docker Desktop installed, follow the [instructions](https://docs.docker.com/compose/install/) to install Docker Compose. +> You need Docker Compose to build and run the docs locally. Docker Compose is included with [Docker Desktop](../desktop/index.md). +> If you don't have Docker Desktop installed, follow the [instructions](../compose/install/index.md) to install Docker Compose. When the container is built and running, visit [http://localhost:4000](http://localhost:4000) in your web browser to view the docs. @@ -99,7 +99,7 @@ docker compose down The default configuration for local builds of the documentation disables some features to allow for a shorter build-time. The following options differ between -local builds, and builds that are deployed to [docs.docker.com](https://docs.docker.com/): +local builds, and builds that are deployed to [docs.docker.com](/): - search auto-completion, and generation of `js/metadata.json` - Google Analytics @@ -119,6 +119,24 @@ When the container is built and running, visit [http://localhost:4000](http://lo To rebuild the docs after you make changes, repeat the steps above. -## Copyright and license +### Test the docs locally + +We use a command-line tool called [vale](https://vale.sh/) to check the style and help you find +errors in your writing. We highly recommend that you use vale to lint your documentation before +you submit your pull request. + +You can run vale as a stand-alone tool using the command-line, or you can integrate it with +your editor to get real-time feedback on your writing. + +To get started, follow the [vale installation instructions](https://vale.sh/docs/vale-cli/installation/) +for your operating system. To enable the vale integration for your editor, install the relevant plugin: + +- [VS Code](https://github.com/errata-ai/vale-vscode) +- [Neovim](https://github.com/jose-elias-alvarez/null-ls.nvim/blob/main/doc/BUILTINS.md#vale) +- [Emacs](https://github.com/tpeacock19/flymake-vale) +- [Jetbrains](https://vale.sh/docs/integrations/jetbrains/) + +The vale rules that implement the Docker style guide are included in the Docker docs repository, +in the `.github/vale` directory. Vale will automatically apply these rules when invoked in this +repository. -Copyright 2013-2022 Docker, inc, released under the Apache 2.0 license. \ No newline at end of file diff --git a/desktop/dev-environments/share.md b/desktop/dev-environments/share.md index 2e88abde82..051a9be7e5 100644 --- a/desktop/dev-environments/share.md +++ b/desktop/dev-environments/share.md @@ -5,7 +5,7 @@ title: Share your Dev Environment --- {% include upgrade-cta.html - body="Docker Pro, Team, and Business users can now share Dev Environments with their team members." + body="Docker Team and Business users can now share Dev Environments with their team members." header-text="This feature requires a paid Docker subscription" target-url="https://www.docker.com/pricing?utm_source=docker&utm_medium=webreferral&utm_campaign=docs_driven_upgrade" %} @@ -22,6 +22,6 @@ This creates an image of your Dev Environment, uploads it to the Docker Hub name ## Open a Dev Environment that has been shared with you -To open a Dev Environment that has been shared with you, select the **Create** button in the top right-hand corner, select the **Existing Dev Environment** tab, and then paste the URL. +To open a Dev Environment that was shared with you, select the **Create** button in the top right-hand corner, select the **Existing Dev Environment** tab, and then paste the URL. -Using this shared Dev Environment, your team members can access the code, any dependencies, and the current Git branch you are working on. They can also review your changes and provide feedback even before you create a pull request! +Using this shared Dev Environment, your team members can access the code, any dependencies, and the current Git branch you are working on. They can also review your changes and give feedback even before you create a pull request! diff --git a/desktop/extensions-sdk/dev/api/backend.md b/desktop/extensions-sdk/dev/api/backend.md index d3c356f5c7..04e144d096 100644 --- a/desktop/extensions-sdk/dev/api/backend.md +++ b/desktop/extensions-sdk/dev/api/backend.md @@ -170,3 +170,7 @@ window.ddClient.spawnHostCmd( } ); ``` + +> You cannot use this to chain commands in a single `exec()` invocation (like `cmd1 $(cmd2)` or using pipe between commands). +> +> You need to invoke `exec()` for each command and parse results to pass parameters to the next command if needed. diff --git a/desktop/extensions-sdk/dev/api/docker.md b/desktop/extensions-sdk/dev/api/docker.md index 6ff2208202..687e0b5a7c 100644 --- a/desktop/extensions-sdk/dev/api/docker.md +++ b/desktop/extensions-sdk/dev/api/docker.md @@ -1,5 +1,5 @@ --- -title: Docker +title: Docker description: Docker extension API keywords: Docker, extensions, sdk, API --- @@ -128,6 +128,10 @@ await ddClient.docker.cli.exec( ); ``` +> You cannot use this to chain commands in a single `exec()` invocation (like `docker kill $(docker ps -q)` or using pipe between commands). +> +> You need to invoke `exec()` for each command and parse results to pass parameters to the next command if needed. + See the [Exec API reference](reference/interfaces/Exec.md) for details about these methods. > Deprecated execution of Docker commands diff --git a/desktop/extensions-sdk/extensions/images/hub-multi-arch-extension.png b/desktop/extensions-sdk/extensions/images/hub-multi-arch-extension.png deleted file mode 100644 index de7f6226cf..0000000000 Binary files a/desktop/extensions-sdk/extensions/images/hub-multi-arch-extension.png and /dev/null differ diff --git a/desktop/extensions-sdk/extensions/multi-arch.md b/desktop/extensions-sdk/extensions/multi-arch.md index cc8d910b86..93a27f23f6 100644 --- a/desktop/extensions-sdk/extensions/multi-arch.md +++ b/desktop/extensions-sdk/extensions/multi-arch.md @@ -13,25 +13,48 @@ Docker Desktop retrieves the extension image according to the user’s system ar ### Build and push for multiple architectures -If you created an extension from the `docker extension init` command, the `Makefile` at the root of the directory includes a target with name `push-extension`. +If you created an extension from the `docker extension init` command, the +`Makefile` at the root of the directory includes a target with name +`push-extension`. -You can do `make push-extension` to build your extension against both `linux/amd64` and `linux/arm64` platforms, and push them to DockerHub. For example: +You can do `make push-extension` to build your extension against both +`linux/amd64` and `linux/arm64` platforms, and push them to DockerHub. -`docker buildx build --platform=linux/amd64,linux/arm64 -t .` - -Alternatively, if you started from an empty directory, use the command below to build your extension for multiple architectures: - -``` -docker buildx build \ - --push \ - --platform=linux/amd64,linux/arm64 \ - --tag=my-extension:0.0.1 . +For example: +```console +$ make push-extension ``` -The information above serves as a guide to help you get started. It’s up to you to define the CI/CD process to build and push the extension. +Alternatively, if you started from an empty directory, use the command below +to build your extension for multiple architectures: -![hub-multi-arch-extension](images/hub-multi-arch-extension.png) +```console +$ docker buildx build --push --platform=linux/amd64,linux/arm64 --tag=username/my-extension:0.0.1 . +``` + +You can then check the image manifest to see if the image is available for both +architectures using the [`docker buildx imagetools` command](../../../engine/reference/commandline/buildx_imagetools.md): + +```console +$ docker buildx imagetools inspect username/my-extension:0.0.1 +Name: docker.io/username/my-extension:0.0.1 +MediaType: application/vnd.docker.distribution.manifest.list.v2+json +Digest: sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 + +Manifests: + Name: docker.io/username/my-extension:0.0.1@sha256:71d7ecf3cd12d9a99e73ef448bf63ae12751fe3a436a007cb0969f0dc4184c8c + MediaType: application/vnd.docker.distribution.manifest.v2+json + Platform: linux/amd64 + + Name: docker.io/username/my-extension:0.0.1@sha256:5ba4ceea65579fdd1181dfa103cc437d8e19d87239683cf5040e633211387ccf + MediaType: application/vnd.docker.distribution.manifest.v2+json + Platform: linux/arm64 +``` + +> **Note** +> +> For more information, see [Multi-platform images](../../../build/building/multi-platform.md) page. ### Adding multi-arch binaries diff --git a/desktop/index.md b/desktop/index.md index 6493030389..81fb692476 100644 --- a/desktop/index.md +++ b/desktop/index.md @@ -45,7 +45,7 @@ It provides a simple interface that enables you to manage your containers, appli - [Docker Engine](../engine/index.md) - Docker CLI client -- [Docker Buildx](../build/buildx/index.md) +- [Docker Buildx](../build/index.md) - [Docker Compose](../compose/index.md) - [Docker Content Trust](../engine/security/trust/index.md) - [Kubernetes](https://github.com/kubernetes/kubernetes/) diff --git a/desktop/install/debian.md b/desktop/install/debian.md index d3bd5a8e5a..33b5abea17 100644 --- a/desktop/install/debian.md +++ b/desktop/install/debian.md @@ -49,7 +49,7 @@ Recommended approach to install Docker Desktop on Debian: 1. Set up [Docker's package repository](../../engine/install/debian.md#set-up-the-repository). -2. Download latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.11.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64). +2. Download latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.12.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64). 3. Install the package with apt as follows: diff --git a/desktop/install/fedora.md b/desktop/install/fedora.md index c287ac8b64..8f1d8e867c 100644 --- a/desktop/install/fedora.md +++ b/desktop/install/fedora.md @@ -29,7 +29,7 @@ To install Docker Desktop on Fedora: 1. Set up [Docker's package repository](../../engine/install/fedora.md#set-up-the-repository). -2. Download latest [RPM package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.11.0-x86_64.rpm?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64). +2. Download latest [RPM package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.12.0-x86_64.rpm?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64). 3. Install the package with dnf as follows: diff --git a/desktop/install/ubuntu.md b/desktop/install/ubuntu.md index 22f100c120..a13051e631 100644 --- a/desktop/install/ubuntu.md +++ b/desktop/install/ubuntu.md @@ -48,7 +48,7 @@ Recommended approach to install Docker Desktop on Ubuntu: 1. Set up [Docker's package repository](../../engine/install/ubuntu.md#set-up-the-repository). -2. Download latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.11.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64). +2. Download latest [DEB package](https://desktop.docker.com/linux/main/amd64/docker-desktop-4.12.0-amd64.deb?utm_source=docker&utm_medium=webreferral&utm_campaign=docs-driven-download-linux-amd64). 3. Install the package with apt as follows: diff --git a/desktop/multi-arch.md b/desktop/multi-arch.md deleted file mode 100644 index be27e8b587..0000000000 --- a/desktop/multi-arch.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -description: Multi-CPU Architecture Support -keywords: mac, windows, Multi-CPU architecture support -redirect_from: -- /docker-for-mac/multi-arch/ -- /mackit/multi-arch/ -title: Leverage multi-CPU architecture support ---- - -Docker images can support multiple architectures, which means that a single -image may contain variants for different architectures, and sometimes for different -operating systems, such as Windows. - -When running an image with multi-architecture support, `docker` automatically -selects the image variant that matches your OS and architecture. - -Most of the Docker Official Images on Docker Hub provide a [variety of architectures](https://github.com/docker-library/official-images#architectures-other-than-amd64){: target="_blank" rel="noopener" class="_" }. -For example, the `busybox` image supports `amd64`, `arm32v5`, `arm32v6`, -`arm32v7`, `arm64v8`, `i386`, `ppc64le`, and `s390x`. When running this image -on an `x86_64` / `amd64` machine, the `amd64` variant is pulled and run. - -## Multi-arch support on Docker Desktop - -**Docker Desktop** provides `binfmt_misc` multi-architecture support, -which means you can run containers for different Linux architectures -such as `arm`, `mips`, `ppc64le`, and even `s390x`. - -This does not require any special configuration in the container itself as it uses -[qemu-static](https://wiki.qemu.org/Main_Page){: target="_blank" rel="noopener" class="_" } -from the **Docker for Mac VM**. Because of this, you can run an ARM container, -like the `arm32v7` or `ppc64le` variants of the busybox image. - -## Build multi-arch images with Buildx - -Docker is now making it easier than ever to develop containers on, and for Arm -servers and devices. Using the standard Docker tooling and processes, you can -start to build, push, pull, and run images seamlessly on different compute -architectures. In most cases, you don't have to make any changes to Dockerfiles -or source code to start building for Arm. - -Docker introduces a new CLI command called `buildx`. You can use the `buildx` -command on Docker Desktop for Mac and Windows to build multi-arch images, link -them together with a manifest file, and push them all to a registry using a -single command. With the included emulation, you can transparently build more -than just native images. Buildx accomplishes this by adding new builder -instances based on BuildKit, and leveraging Docker Desktop's technology stack -to run non-native binaries. - -For more information about the Buildx CLI command, see [Buildx](../build/buildx/index.md) -and the [`docker buildx` command line reference](../engine/reference/commandline/buildx.md). - -### Build and run multi-architecture images - -Run the `docker buildx ls` command to list the existing builders. This displays -the default builder, which is our old builder. - -```console -$ docker buildx ls - -NAME/NODE DRIVER/ENDPOINT STATUS PLATFORMS -default * docker - default default running linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 -``` - -Create a new builder which gives access to the new multi-architecture features. - -```console -$ docker buildx create --name mybuilder - -mybuilder -``` - -Alternatively, run `docker buildx create --name mybuilder --use` to create a new -builder and switch to it using a single command. - -Switch to the new builder and inspect it. - -```console -$ docker buildx use mybuilder - -$ docker buildx inspect --bootstrap - -[+] Building 2.5s (1/1) FINISHED - => [internal] booting buildkit 2.5s - => => pulling image moby/buildkit:master 1.3s - => => creating container buildx_buildkit_mybuilder0 1.2s -Name: mybuilder -Driver: docker-container - -Nodes: -Name: mybuilder0 -Endpoint: unix:///var/run/docker.sock -Status: running - -Platforms: linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 -``` - -Test the workflow to ensure you can build, push, and run multi-architecture -images. Create a simple example Dockerfile, build a couple of image variants, -and push them to Docker Hub. - -The following example uses a single `Dockerfile` to build an Ubuntu image with cURL -installed for multiple architectures. - -Create a `Dockerfile` with the following: - -```dockerfile -FROM ubuntu:20.04 -RUN apt-get update && apt-get install -y curl -``` - -Build the Dockerfile with buildx, passing the list of architectures to build for: - -```console -$ docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t username/demo:latest --push . - -[+] Building 6.9s (19/19) FINISHED -... - => => pushing layers 2.7s - => => pushing manifest for docker.io/username/demo:latest 2.2 -``` - -Where, `username` is a valid Docker username. - -> **Notes:** -> -> - The `--platform` flag informs buildx to generate Linux images for AMD 64-bit, -> Arm 64-bit, and Armv7 architectures. -> - The `--push` flag generates a multi-arch manifest and pushes all the images -> to Docker Hub. - -Inspect the image using `docker buildx imagetools`. - -```console -$ docker buildx imagetools inspect username/demo:latest - -Name: docker.io/username/demo:latest -MediaType: application/vnd.docker.distribution.manifest.list.v2+json -Digest: sha256:2a2769e4a50db6ac4fa39cf7fb300fa26680aba6ae30f241bb3b6225858eab76 - -Manifests: - Name: docker.io/username/demo:latest@sha256:8f77afbf7c1268aab1ee7f6ce169bb0d96b86f585587d259583a10d5cd56edca - MediaType: application/vnd.docker.distribution.manifest.v2+json - Platform: linux/amd64 - - Name: docker.io/username/demo:latest@sha256:2b77acdfea5dc5baa489ffab2a0b4a387666d1d526490e31845eb64e3e73ed20 - MediaType: application/vnd.docker.distribution.manifest.v2+json - Platform: linux/arm64 - - Name: docker.io/username/demo:latest@sha256:723c22f366ae44e419d12706453a544ae92711ae52f510e226f6467d8228d191 - MediaType: application/vnd.docker.distribution.manifest.v2+json - Platform: linux/arm/v7 -``` - -The image is now available on Docker Hub with the tag `username/demo:latest`. You -can use this image to run a container on Intel laptops, Amazon EC2 Graviton instances, -Raspberry Pis, and on other architectures. Docker pulls the correct image for the -current architecture, so Raspberry Pis run the 32-bit Arm version and EC2 Graviton -instances run 64-bit Arm. The SHA tags identify a fully qualified image variant. -You can also run images targeted for a different architecture on Docker Desktop. - -You can run the images using the SHA tag, and verify the architecture. For -example, when you run the following on a macOS: - - ```console -$ docker run --rm docker.io/username/demo:latest@sha256:2b77acdfea5dc5baa489ffab2a0b4a387666d1d526490e31845eb64e3e73ed20 uname -m -aarch64 -``` - -```console -$ docker run --rm docker.io/username/demo:latest@sha256:723c22f366ae44e419d12706453a544ae92711ae52f510e226f6467d8228d191 uname -m -armv7l -``` - -In the above example, `uname -m` returns `aarch64` and `armv7l` as expected, -even when running the commands on a native macOS or Windows developer machine. diff --git a/desktop/previous-versions/2.x-mac.md b/desktop/previous-versions/2.x-mac.md index a04e468abe..23c25d831c 100644 --- a/desktop/previous-versions/2.x-mac.md +++ b/desktop/previous-versions/2.x-mac.md @@ -435,7 +435,7 @@ Note that you must sign in and create a Docker ID in order to download Docker De Docker Desktop Community 2.1.0.0 contains the following experimental features. * Docker App: Docker App is a CLI plugin that helps configure, share, and install applications. For more information, see [Working with Docker App](/app/working-with-app/). -* Docker Buildx: Docker Buildx is a CLI plugin for extended build capabilities with BuildKit. For more information, see [Buildx component](../../build/buildx/index.md). +* Docker Buildx: Docker Buildx is a CLI plugin for extended build capabilities with BuildKit. For more information, see the [Build page](../../build/index.md). ### Bug fixes and minor changes diff --git a/desktop/previous-versions/2.x-windows.md b/desktop/previous-versions/2.x-windows.md index 4e84aa87c2..c3d296e922 100644 --- a/desktop/previous-versions/2.x-windows.md +++ b/desktop/previous-versions/2.x-windows.md @@ -557,7 +557,7 @@ Note that you must sign in and create a Docker ID in order to download Docker De Docker Desktop Community 2.1.0.0 contains the following experimental features: * Docker App: Docker App is a CLI plugin that helps configure, share, and install applications. For more information, see [Working with Docker App](/app/working-with-app/). -* Docker Buildx: Docker Buildx is a CLI plugin for extended build capabilities with BuildKit. For more information, see [Buildx component](../../build/buildx/index.md). +* Docker Buildx: Docker Buildx is a CLI plugin for extended build capabilities with BuildKit. For more information, see the [Build page](../../build/index.md). ### Bug fixes and minor changes diff --git a/desktop/release-notes.md b/desktop/release-notes.md index c64062577a..9e7066d041 100644 --- a/desktop/release-notes.md +++ b/desktop/release-notes.md @@ -62,7 +62,7 @@ For frequently asked questions about Docker Desktop releases, see [FAQs](faqs/ge - Compose V2 is now enabled after factory reset. - Compose V2 is now enabled by default on new installations of Docker Desktop. -- Precedence order of environment variables in Compose is more consistent, and clearly [documented](https://docs.docker.com/compose/envvars-precedence/). +- Precedence order of environment variables in Compose is more consistent, and clearly [documented](../compose/envvars-precedence.md). - Upgraded kernel to 5.10.124. - Improved overall performance issues caused by calculating disk size. Related to [docker/for-win#9401](https://github.com/docker/for-win/issues/9401). - Docker Desktop now prevents users on ARM macs without Rosetta installed from switching back to Compose V1, which has only intel binaries. diff --git a/develop/dev-best-practices.md b/develop/dev-best-practices.md index d9945e158e..c01283006a 100644 --- a/develop/dev-best-practices.md +++ b/develop/dev-best-practices.md @@ -20,7 +20,7 @@ keep image size small: starting with a generic `ubuntu` image and installing `openjdk` as part of the Dockerfile. -- [Use multistage builds](develop-images/multistage-build.md). For +- [Use multistage builds](../build/building/multi-stage.md). For instance, you can use the `maven` image to build your Java application, then reset to the `tomcat` image and copy the Java artifacts into the correct location to deploy your app, all in the same Dockerfile. This means that your diff --git a/develop/develop-images/dockerfile_best-practices.md b/develop/develop-images/dockerfile_best-practices.md index 7f90775c7b..569d6f9ba1 100644 --- a/develop/develop-images/dockerfile_best-practices.md +++ b/develop/develop-images/dockerfile_best-practices.md @@ -252,9 +252,9 @@ similar to `.gitignore` files. For information on creating one, see the ### Use multi-stage builds -[Multi-stage builds](multistage-build.md) allow you to drastically reduce the -size of your final image, without struggling to reduce the number of intermediate -layers and files. +[Multi-stage builds](../../build/building/multi-stage.md) allow you to +drastically reduce the size of your final image, without struggling to reduce +the number of intermediate layers and files. Because an image is built during the final stage of the build process, you can minimize image layers by [leveraging build cache](#leverage-build-cache). @@ -334,10 +334,10 @@ were added to reduce this limitation: - Only the instructions `RUN`, `COPY`, `ADD` create layers. Other instructions create temporary intermediate images, and do not increase the size of the build. -- Where possible, use [multi-stage builds](multistage-build.md), and only copy - the artifacts you need into the final image. This allows you to include tools - and debug information in your intermediate build stages without increasing the - size of the final image. +- Where possible, use [multi-stage builds](../../build/building/multi-stage.md), + and only copy the artifacts you need into the final image. This allows you to + include tools and debug information in your intermediate build stages without + increasing the size of the final image. ### Sort multi-line arguments diff --git a/develop/index.md b/develop/index.md index bdde70f6d4..6e7c4c5f93 100644 --- a/develop/index.md +++ b/develop/index.md @@ -17,7 +17,7 @@ these resources to understand some of the most common patterns for getting the most benefits from Docker. - Learn how to [build an image](../engine/reference/builder/){: target="_blank" rel="noopener" class="_"} using a Dockerfile -- Use [multi-stage builds](develop-images/multistage-build.md){: target="_blank" rel="noopener" class="_"} to keep your images lean +- Use [multi-stage builds](../build/building/multi-stage.md) to keep your images lean - Manage application data using [volumes](../storage/volumes.md) and [bind mounts](../storage/bind-mounts.md){: target="_blank" rel="noopener" class="_"} - [Scale your app with Kubernetes](../get-started/kube-deploy.md){: target="_blank" rel="noopener" class="_"} - [Scale your app as a Swarm service](../get-started/swarm-deploy.md){: target="_blank" rel="noopener" class="_"} diff --git a/develop/scan-images/index.md b/develop/scan-images/index.md index e3d96b4332..d44cd5bef4 100644 --- a/develop/scan-images/index.md +++ b/develop/scan-images/index.md @@ -91,7 +91,7 @@ You can use multiple `FROM` statements in your Dockerfile, and you can use a dif This method of creating a tiny image does not only significantly reduce complexity, but also the change of implementing vulnerable artifacts in your image. Therefore, instead of images that are built on images, that again are built on other images, multi-stage builds allow you to 'cherry pick' your artifacts without inheriting the vulnerabilities from the base images on which they rely on. -For detailed information on how to configure multi-stage builds, see [multi-stage builds](../develop-images/multistage-build.md). +For detailed information on how to configure multi-stage builds, see [multi-stage builds](../../build/building/multi-stage.md). ### Rebuild images diff --git a/docker-hub/members.md b/docker-hub/members.md index 019b654a8f..585c637d8d 100644 --- a/docker-hub/members.md +++ b/docker-hub/members.md @@ -114,4 +114,22 @@ To remove a member from a specific team: 1. Navigate to **Organizations** in [Docker Hub](https://hub.docker.com){: target="_blank" rel="noopener" class="_"}, and select your organization. 2. Click on the **Teams** tab and select the team from the list. 3. Click the **X** next to the user’s name to remove them from the team. -4. When prompted, click **Remove** to confirm. \ No newline at end of file +4. When prompted, click **Remove** to confirm. + +## Export members + +Export members is a feature available to organizations with a Docker Business subscription. Organization owners can export a CSV file containing the organization's members. +The CSV file contains the following fields: + + * **Name**: The user's name. + * **Username**: The user's Docker ID. + * **Email**: The user's email address. + * **Type**: The type of user. For example, **Invitee** for users who have not accepted the organization's invite, or **User** for users who are members of the organization. + * **Permissions**: The user's organization permissions. For example, **Member** or **Owner**. + * **Teams**: The teams where the user is a member. A team is not listed for invitees. + * **Date Joined**: The time and date when the user was invited to the organization. + +To export a CSV file of the organization's members: + +1. Navigate to **Organizations** in [Docker Hub](https://hub.docker.com){: target="_blank" rel="noopener" class="_"}, and select your organization. +2. In the **Members** tab, select **Export members** to download the CSV file. \ No newline at end of file diff --git a/docker-hub/registry-access-management.md b/docker-hub/registry-access-management.md index bce4eb1f5d..f7f98232d4 100644 --- a/docker-hub/registry-access-management.md +++ b/docker-hub/registry-access-management.md @@ -4,7 +4,9 @@ keywords: registry, access, managment title: Registry Access Management --- -Registry Access Management is a feature available to organizations with a Docker Business subscription. With Registry Access Management, organization owners can ensure that their developers using Docker Desktop can only access registries that have been allow-listed via the Registry Access Management dashboard on Docker Hub to reflect support for other registries: AWS ECR, GitHub Container Registry, Google Container Registry, Quay, and others. +Registry Access Management (RAM) is a feature available to organizations with a Docker Business subscription. When RAM is enabled, organization owners can ensure that their developers using Docker Desktop can only access registries that have been allow-listed via the Registry Access Management dashboard on Docker Hub to reflect support for other registries: AWS ECR, GitHub Container Registry, Google Container Registry, Quay, a local private registry, and others. + +For example, you can use RAM if you manage engineering teams that use Docker Desktop for local development and want to ensure that the images they are pulling are licensed and reputable before using them. ## Requirements: diff --git a/docker-hub/release-notes.md b/docker-hub/release-notes.md index 0be2e16762..29a9ae8693 100644 --- a/docker-hub/release-notes.md +++ b/docker-hub/release-notes.md @@ -11,11 +11,18 @@ known issues for each Docker Hub release. Take a look at the [Docker Public Roadmap](https://github.com/docker/roadmap/projects/1){: target="_blank" rel="noopener" class="_"} to see what's coming next. -## 2022-09-19 + +## 2022-09-21 ### Enhancement In Docker Hub, you can now download a [registry.json](../docker-hub/configure-sign-in.md) file for your organization or copy the commands to create a registry.json file for your organization. +## 2022-09-19 +### Enhancement + +You can now [export a CSV file of members](../docker-hub/members.md/#export-members) from organizations that you own. + + ## 2022-07-22 ### Enhancement diff --git a/get-started/04_sharing_app.md b/get-started/04_sharing_app.md index bc189de7ec..289841cd6c 100644 --- a/get-started/04_sharing_app.md +++ b/get-started/04_sharing_app.md @@ -58,6 +58,7 @@ If you look at the image below an example **Docker command** can be seen. This c ```console $ docker tag getting-started YOUR-USER-NAME/getting-started ``` + Learn more about [docker tag](../engine/reference/commandline/tag.md). 4. Now try your push command again. If you're copying the value from Docker Hub, you can drop the `tagname` portion, as we didn't add a tag to the image name. If you don't specify a tag, Docker diff --git a/language/golang/build-images.md b/language/golang/build-images.md index 5d2a7f4a9f..58a11f7f6b 100644 --- a/language/golang/build-images.md +++ b/language/golang/build-images.md @@ -480,7 +480,7 @@ that we have used to deploy our Go application is very barebones and is meant for lean deployments of static binaries. For more information on multi-stage builds, please feel free to check out -[other parts](../../develop/develop-images/multistage-build.md) of the Docker +[other parts](../../build/building/multi-stage.md) of the Docker documentation. This is, however, not essential for our progress here, so we'll leave it at that. diff --git a/single-sign-on/images/sso-architecture.png b/single-sign-on/images/sso-architecture.png new file mode 100644 index 0000000000..cbef9c793c Binary files /dev/null and b/single-sign-on/images/sso-architecture.png differ diff --git a/single-sign-on/index.md b/single-sign-on/index.md index 0eb52cdd07..be5133e0b1 100644 --- a/single-sign-on/index.md +++ b/single-sign-on/index.md @@ -18,6 +18,14 @@ To enable SSO in Docker Hub, you need the following information from your identi We currently support enabling SSO on a single organization. However, we do not support single logout. If you have any users in your organization with a different domain (including social domains), they will be added to the organization as guests. Guests will continue to authenticate through Docker with their Docker login credentials (Docker ID and password). + +## Single Sign-on architecture flow + +The following diagram shows how Single Sign-on (SSO) operates and is managed in Docker Hub and Docker Desktop. In addition, it provides information on how to authenticate between your IdPs. + +[![SSO architecture](images/sso-architecture.png)](images/sso-architecture.png){: target="_blank" rel="noopener" class="_"} + + ## Prerequisites * You must first notify your company about the new SSO login procedures diff --git a/storage/storagedriver/index.md b/storage/storagedriver/index.md index caae29b0c1..8715427ef8 100644 --- a/storage/storagedriver/index.md +++ b/storage/storagedriver/index.md @@ -62,7 +62,7 @@ _adding_, and _removing_ files will result in a new layer. In the example above, the `$HOME/.cache` directory is removed, but will still be available in the previous layer and add up to the image's total size. Refer to the [Best practices for writing Dockerfiles](../../develop/develop-images/dockerfile_best-practices.md) -and [use multi-stage builds](../../develop/develop-images/multistage-build.md) +and [use multi-stage builds](../../build/building/multi-stage.md) sections to learn how to optimize your Dockerfiles for efficient images. The layers are stacked on top of each other. When you create a new container,