You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+57-57Lines changed: 57 additions & 57 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,44 +3,45 @@ go-docker-builder
3
3
4
4
`go-docker-builder` library is a wrapper over docker client SDK that provides a set of packages that help to manage the most common docker use cases such as build or push images.
5
5
6
-
It also manages docker registry autentication, prepares docker build context to be used by docker client SDK and supports docker build context either from local path or git repository.
6
+
It also manages docker registry authentication, prepares docker build context to be used by docker client SDK and supports docker build context either from the local path or git repository.
Docker build context is a set of files required to build a docker image. `go-docker-builder` library supports two kind of sources to create the Docker build context: `path` and `git`
148
+
The Docker build context is a set of files required to create a docker image. `go-docker-builder` library supports two kinds of sources to create the Docker build context: `path` and `git`
148
149
149
150
##### Path
150
-
When files are located on local host, Docker build context must be created as `path`, and it is only required to define the local folder where files are located.
151
+
When files are located on your localhost, the Docker build context must be created as `path`, and it is only required to define the local folder where files are located.
151
152
152
-
A `PathBuildContext` instance represents a Docker build context as path.
153
+
A `PathBuildContext` instance represents a Docker build context as the path.
153
154
```go
154
155
// PathBuildContext creates a build context from path
155
156
typePathBuildContextstruct {
@@ -159,7 +160,7 @@ type PathBuildContext struct {
159
160
```
160
161
161
162
##### Git
162
-
When files are located on a git repository, Docker build context must be created as `git`.
163
+
When files are located on a git repository, the Docker build context must be created as `git`.
163
164
164
165
A `GitBuildContext` instance represents a Docker build context as git.
165
166
```go
@@ -176,18 +177,18 @@ type GitBuildContext struct {
176
177
}
177
178
```
178
179
179
-
To define a `git` Docker build context, the only required attribute is `Repository`, although it accepts other configurations such as the `Reference` name (branch, commit or tag), `Auth` which is used to be authenticated over git server or `Path` which let you to define as Docker build context base a subfolder inside the repository.
180
+
To define a `git` Docker build context, the only required attribute is `Repository`, although it accepts other configurations such as the `Reference` name (branch, commit or tag), `Auth` which is used to be authenticated over the git server or `Path` which let you define as Docker build context base a subfolder inside the repository.
180
181
181
182
`go-docker-builder` uses [go-git](https://github.com/go-git/go-git) library to manage `git` Docker build context.
182
183
183
184
#### Context filesystem
184
185
Context filesystem has been created as an intermediate filesystem between the source files and Docker build context.
185
186
186
-
Context filesystem, is build on top of [afero](https://github.com/spf13/afero) filesystem. It supports to **tar** the entire filesystem and also to **join** multiple filesystems.
187
+
Context filesystem is built on top of an [afero](https://github.com/spf13/afero) filesystem. It supports **taring** the entire filesystem and also **joining** multiple filesystems.
187
188
188
189
### Push
189
190
Package `push` purpose is to push Docker images to a Docker registry.
190
-
To perform a push action, must be created a `DockerPushBuildCmd` instance.
191
+
To perform a push action you must create a `DockerPushBuildCmd` instance.
191
192
192
193
```go
193
194
// DockerPushCmd is used to push images to docker registry
@@ -211,7 +212,7 @@ type DockerPushCmd struct {
211
212
212
213
Below there is a recipe to build docker images using `go-docker-builder`:
Package`copy` can be understand such a `push` use case variation. Its purpose is to push images either from local host or from a Docker registry to another Docker registry. It can be also used to copy images from one Docker registry namespace to another namespace.
254
-
To perform a copy action, must be created a `DockerImageCopyCmd` instance.
254
+
The`copy`package can be understood as such a `push` use case variation. Its purpose is to push images either from your localhost or from a Docker registry to another Docker registry. It can be also used to copy images from one Docker registry namespace to another namespace.
255
+
To perform a copy action you must create a `DockerImageCopyCmd` instance.
255
256
256
257
```go
257
258
// DockerCopyImageCmd is used to copy images to docker registry. Copy image is understood as tag an existing image and push it to a docker registry
@@ -279,27 +280,27 @@ type DockerImageCopyCmd struct {
279
280
}
280
281
```
281
282
282
-
Some cases where copy can be used are:
283
-
-Copy one image from [dockerhub](https://hub.docker.com/) to a private Docker registry
284
-
-When Docker images used on your staging environments needs to be promoted somewhere else before use them on production environment.
283
+
You can use the `copy` package when:
284
+
-You need to copy one image from [dockerhub](https://hub.docker.com/) to a private Docker registry
285
+
-The Docker images you use on your staging environments need to be promoted somewhere else before using them in the production environment.
285
286
286
287
## Authentication
287
-
`go-docker-builder` library contains a bunch of packages to manage authentication either to docker registry or git server.
288
+
`go-docker-builder` library contains a bunch of packages to manage authentication either to the Docker registry or the git server.
288
289
289
290
### Docker registry
290
-
Package `github.com/apenella/go-docker-builder/pkg/auth/docker` provides a set of functions to create the authentication items required by Docker registry. Docker registy may require authentication either for `push` or `pull` operations.
291
+
Package `github.com/apenella/go-docker-builder/pkg/auth/docker` provides a set of functions to create the authentication items required by the Docker registry. The Docker registry may require authentication either for `push` or `pull` operations.
291
292
292
-
Packages [build](#build), [push](#push) or [copy](#copy) already uses that package on its authentication methods, and is not necessary to use it directly.
293
+
Packages [build](#build), [push](#push) or [copy](#copy) already use that package on its authentication methods, and is not necessary to use it directly.
293
294
294
295
### Git server
295
-
Git server authentication is needed when Docker build context is located on a git repository and the git server requires it authorize you for cloning any repository.
296
+
Git server authentication is needed when the Docker build context is located on a git repository and the git server requires it to authorize you for cloning any repository.
296
297
297
298
`go-docker-builder` supports several git authentication methods such as `basic auth`, `ssh-key` or `ssh-agent`.
298
299
299
-
All this authentication methods generates an `AuthMethod` (github.com/go-git/go-git/v5/plumbing/transport).
300
+
All these authorization methods generate an `AuthMethod` (github.com/go-git/go-git/v5/plumbing/transport).
300
301
301
302
#### Basic auth
302
-
`Basic auth` requires a `username` and `password`. It have to be used when comunication is done through `http/s`.
303
+
`Basic auth` requires a `username` and `password`. It must be used when communication is done through `http/s`.
303
304
304
305
```go
305
306
typeBasicAuthstruct {
@@ -309,7 +310,7 @@ type BasicAuth struct {
309
310
```
310
311
311
312
#### SSH key
312
-
You can use an `ssh key` when comunication to git server is done over ssh. It requires your privete key location (`PkFile`). In case your key is being protected by password, you have to set it on `PkPassword` attribute. Finally, when git user is not `git`, you can define it on `GitSSHUser` attribute.
313
+
You can use an `ssh key` when want to connect to the git server over SSH. It requires your private key location (`PkFile`). In case your key is being protected by a password, you have to set it on `PkPassword` attribute. Finally, when the git user is not `git`, you can define it on `GitSSHUser` attribute.
313
314
```go
314
315
typeKeyAuthstruct {
315
316
GitSSHUserstring
@@ -319,7 +320,7 @@ type KeyAuth struct {
319
320
```
320
321
321
322
#### SSH agent
322
-
To authenticate to git server, `ssh-agent` method uses the ssh agent running on you host. When git user is not `git`, you can define it on `GitSSHUser` attribute.
323
+
To authenticate to the git server, `ssh-agent` method uses the SSH agent running on your host. When your SSH user is not `git`, you can define it on `GitSSHUser` attribute.
323
324
```go
324
325
typeSSHAgentAuthstruct {
325
326
GitSSHUserstring
@@ -328,10 +329,10 @@ type SSHAgentAuth struct {
328
329
329
330
## Response
330
331
To control how Docker output is sent to the user, `go-docker-build` provides `response` package.
331
-
By default, [DockerBuildCmd](#build), [DockerPushCmd](#push) and [DockerCopyCmd](#copy) instances use a basic configuration of `response` that prints Docker output to `os.Stdout`. But you could customize docker client SDK response, defining your own`response` instance, and pass it to them.
332
+
By default, [DockerBuildCmd](#build), [DockerPushCmd](#push) and [DockerCopyCmd](#copy) instances use a basic configuration of `response` that prints Docker output to `os.Stdout`. But you could customize the Docker client SDK response, define your `response` instance, and pass it to them.
332
333
333
-
`response` receives `ImageBuildResponse` or `ImagePushResponse` items, unmarshals into an struct and finally prepares a user-frendly output.
334
-
To customize the Docker output coming from response items, it could receive a list of transfromer functions. That function must complain the type `TransformerFunc` defined on `github.com/apenella/go-common-utils/transformer/string`.
334
+
`response` receives `ImageBuildResponse` or `ImagePushResponse` items, unmarshals into a struct and finally prepares a user-friendly output.
335
+
To customize the Docker output coming from response items, it could receive a list of transformer functions. That function must complain the type `TransformerFunc` defined on `github.com/apenella/go-common-utils/transformer/string`.
335
336
336
337
```go
337
338
// TransformerFunc is used to enrich or update messages before to be printed out
On folder [examples](https://github.com/apenella/go-docker-builder/tree/master/examples), you could find some `go-docker-build` examples. Among those examples you could find how to build images using distinct Docker build context, how to authenticate to Docker registry or git server, etc.
363
+
On folder [examples](https://github.com/apenella/go-docker-builder/tree/master/examples), you could find some `go-docker-build` examples. Among those examples, you could find how to build images using distinct Docker build context, how to authenticate to Docker registry or git server, etc.
363
364
364
-
To run any example, the repository is provided with some resources that let you to start an ephemeral environment where examples can run. Each environments run on `docker compose` and starts a Docker registry, a git server and a client container where example runs. That environments are also used to run functional test.
365
-
366
-
Each example is also provide by a `Makefile` which helps you to start the examples or tests.
365
+
To run any example, the repository is provided with some resources that let you start an ephemeral environment where examples can run. Each environment runs on `docker compose` and starts a Docker registry, a git server and a client container where the example runs. Those environments are also used to run the functional test.
366
+
Each example is also provided by a `Makefile` which helps you to start the examples or tests.
367
367
368
368
```shell
369
369
❯ make help
@@ -383,7 +383,7 @@ Each example is also provide by a `Makefile` which helps you to start the exampl
383
383
384
384
## References
385
385
- Docker engine API specifications for building an image: https://docs.docker.com/engine/api/v1.39/#operation/ImageBuild
386
-
-Taring files strategy was inspired by: https://medium.com/@skdomino/taring-untaring-files-in-go-6b07cf56bc07
386
+
-The used taring files strategy is inspired by: https://medium.com/@skdomino/taring-untaring-files-in-go-6b07cf56bc07
387
387
388
388
## License
389
389
`go-docker-builder` is available under [MIT](https://github.com/apenella/go-docker-builder/blob/master/LICENSE) license.
0 commit comments