1 | # @atomist/sdm-pack-docker
|
2 |
|
3 | [![atomist sdm goals](http://badge.atomist.com/T29E48P34/atomist/sdm-pack-docker/275b4284-9942-41c8-9b91-e90957d99188)](https://app.atomist.com/workspace/T29E48P34)
|
4 | [![npm version](https://img.shields.io/npm/v/@atomist/sdm-pack-docker.svg)](https://www.npmjs.com/package/@atomist/sdm-pack-docker)
|
5 |
|
6 | [Atomist][atomist] software delivery machine (SDM) extension Pack for an Atomist SDM to
|
7 | integrate [docker](https://www.docker.io).
|
8 |
|
9 | See the [Atomist documentation][atomist-doc] for more information on
|
10 | what SDMs are and what they can do for you using the Atomist API for
|
11 | software.
|
12 |
|
13 | [atomist-doc]: https://docs.atomist.com/ (Atomist Documentation)
|
14 |
|
15 | ## Usage
|
16 |
|
17 | ### Docker Image Creation
|
18 |
|
19 | TODO
|
20 |
|
21 | ### Dockerfile Parsing and Manipulation
|
22 |
|
23 | This module includes support for parsing Docker files, within the Atomist
|
24 | [tree path](https://github.com/atomist/tree-path) model. This allows us to
|
25 | query instructions in Docker files and update them without otherwise changing
|
26 | file content or formatting.
|
27 |
|
28 | The following example returns the image name:
|
29 |
|
30 | ```typescript
|
31 | const images: string[] = await astUtils.findValues(p, DockerFileParser, "Dockerfile",
|
32 | "//FROM/image/name");
|
33 | ```
|
34 |
|
35 | The following example uses `DockerFileParser` exported by this package, to update
|
36 | an image tag of `argon`, from `node:argon` to `xenon` to produce a file referencing
|
37 | `node:xenon`.
|
38 |
|
39 | ```typescript
|
40 | await astUtils.doWithAllMatches(p, DockerFileParser, "Dockerfile",
|
41 | "//FROM/image/tag",
|
42 | n => n.$value = "xenon");
|
43 | ```
|
44 |
|
45 | This example uses a custom function to find all `RUN` instructions that invoke `rm`:
|
46 |
|
47 | ```typescript
|
48 | const runs = await astUtils.findValues(p, DockerFileParser, "Dockerfile",
|
49 | "//RUN[?removes]",
|
50 | {
|
51 | removes: n => n.$value.includes("rm "),
|
52 | });
|
53 | ```
|
54 |
|
55 | We introduce the `pair` level to handle `LABELs`. For example, consider
|
56 | the following input:
|
57 |
|
58 | ```
|
59 | LABEL "com.example.vendor"="ACME Incorporated"
|
60 |
|
61 | ```
|
62 |
|
63 | The following code queries it:
|
64 |
|
65 | ```typescript
|
66 | const labelKeys = await astUtils.findValues(p, DockerFileParser, "Dockerfile",
|
67 | "//LABEL/pair/key");
|
68 | assert.strictEqual(labelKeys[0], `com.example.vendor`);
|
69 | const labelValues = await astUtils.findValues(p, DockerFileParser, "Dockerfile",
|
70 | "//LABEL/pair/value");
|
71 | assert.strictEqual(labelValues[0], `ACME Incorporated`);
|
72 | const knownKeys = await astUtils.findValues(p, DockerFileParser, "Dockerfile",
|
73 | "//LABEL/pair[/key[@value='com.example.vendor']]/value");
|
74 | assert.strictEqual(knownKeys[0], `ACME Incorporated`);
|
75 | ```
|
76 |
|
77 | Please see `dockerFileParser.test.ts` for further examples.
|
78 |
|
79 | ## Support
|
80 |
|
81 | General support questions should be discussed in the `#support`
|
82 | channel in the [Atomist community Slack workspace][slack].
|
83 |
|
84 | If you find a problem, please create an [issue][].
|
85 |
|
86 | [issue]: https://github.com/atomist/sdm-pack-docker/issues
|
87 |
|
88 | ## Development
|
89 |
|
90 | You will need to install [Node][node] to build and test this project.
|
91 |
|
92 | [node]: https://nodejs.org/ (Node.js)
|
93 |
|
94 | ### Build and test
|
95 |
|
96 | Use the following package scripts to build, test, and perform other
|
97 | development tasks.
|
98 |
|
99 | Command | Reason
|
100 | ------- | ------
|
101 | `npm install` | install project dependencies
|
102 | `npm run build` | compile, test, lint, and generate docs
|
103 | `npm run lint` | run TSLint against the TypeScript
|
104 | `npm run compile` | generate types from GraphQL and compile TypeScript
|
105 | `npm test` | run tests
|
106 | `npm run autotest` | run tests every time a file changes
|
107 | `npm run clean` | remove files generated during build
|
108 |
|
109 | ### Release
|
110 |
|
111 | Releases are handled via the [Atomist SDM][atomist-sdm]. Just press
|
112 | the 'Approve' button in the Atomist dashboard or Slack.
|
113 |
|
114 | [atomist-sdm]: https://github.com/atomist/atomist-sdm (Atomist Software Delivery Machine)
|
115 |
|
116 | ---
|
117 |
|
118 | Created by [Atomist][atomist].
|
119 | Need Help? [Join our Slack workspace][slack].
|
120 |
|
121 | [atomist]: https://atomist.com/ (Atomist - How Teams Deliver Software)
|
122 | [slack]: https://join.atomist.com/ (Atomist Community Slack)
|
123 |
|
124 | [atomist]: https://atomist.com/ (Atomist - Development Automation)
|
125 | [slack]: https://join.atomist.com/ (Atomist Community Slack)
|