Documentation enhancements
Making metadata: - more consistent - more specific (fixed copy pasting) - refine coverage Insecure information cleanup Removing no longer used files: - mkdocs is gone - the registry diagram is not used, and is a bit silly :) Minor fixes Fixing links Recipes: - harmonized code sections style to the rest of the docs - harmonized recipe "style" - listing new recipes Enhance deploying Signed-off-by: Olivier Gambier <olivier@docker.com>
This commit is contained in:
Olivier Gambier
parent
1927c6c0f2
commit
5df53c0681
21 changed files with 214 additions and 236 deletions
130
docs/building.md
130
docs/building.md
|
|
@ -1,10 +1,32 @@
|
|||
<!--[metadata]>
|
||||
+++
|
||||
draft = "true"
|
||||
title = "Build instructions"
|
||||
description = "Explains how to build & hack on the registry"
|
||||
keywords = ["registry, on-prem, images, tags, repository, distribution, build, recipe, advanced"]
|
||||
+++
|
||||
<![end-metadata]-->
|
||||
|
||||
# Build the development environment
|
||||
# Building the registry source
|
||||
|
||||
## Use-case
|
||||
|
||||
This is useful if you intend to actively work on the registry.
|
||||
|
||||
### Alternatives
|
||||
|
||||
Most people should use the [official Registry docker image](https://hub.docker.com/r/library/registry/).
|
||||
|
||||
People looking for advanced operational use cases might consider rolling their own image with a custom Dockerfile inheriting `FROM registry:2`.
|
||||
|
||||
OSX users who want to run natively can do so following [the instructions here](osx-setup-guide.md).
|
||||
|
||||
### Gotchas
|
||||
|
||||
You are expected to know your way with go & git.
|
||||
|
||||
If you are a casual user with no development experience, and no preliminary knowledge of go, building from source is probably not a good solution for you.
|
||||
|
||||
## Build the development environment
|
||||
|
||||
The first prerequisite of properly building distribution targets is to have a Go
|
||||
development environment setup. Please follow [How to Write Go Code](https://golang.org/doc/code.html)
|
||||
|
|
@ -12,29 +34,23 @@ for proper setup. If done correctly, you should have a GOROOT and GOPATH set in
|
|||
environment.
|
||||
|
||||
If a Go development environment is setup, one can use `go get` to install the
|
||||
`registry` command from the current latest:
|
||||
`registry` source code from the current latest:
|
||||
|
||||
```sh
|
||||
go get github.com/docker/distribution/cmd/registry
|
||||
```
|
||||
go get github.com/docker/distribution/cmd/registry
|
||||
|
||||
The above will install the source repository into the `GOPATH`.
|
||||
|
||||
Now create the directory for the registry data (this might require you to set permissions properly)
|
||||
|
||||
```sh
|
||||
mkdir -p /var/lib/registry
|
||||
```
|
||||
mkdir -p /var/lib/registry
|
||||
|
||||
... or alternatively `export REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere` if you want to store data into another location.
|
||||
|
||||
The `registry`
|
||||
binary can then be run with the following:
|
||||
|
||||
```
|
||||
$ $GOPATH/bin/registry -version
|
||||
$GOPATH/bin/registry github.com/docker/distribution v2.0.0-alpha.1+unknown
|
||||
```
|
||||
$ $GOPATH/bin/registry -version
|
||||
$GOPATH/bin/registry github.com/docker/distribution v2.0.0-alpha.1+unknown
|
||||
|
||||
> __NOTE:__ While you do not need to use `go get` to checkout the distribution
|
||||
> project, for these build instructions to work, the project must be checked
|
||||
|
|
@ -44,13 +60,11 @@ $GOPATH/bin/registry github.com/docker/distribution v2.0.0-alpha.1+unknown
|
|||
The registry can be run with the default config using the following
|
||||
incantation:
|
||||
|
||||
```
|
||||
$ $GOPATH/bin/registry $GOPATH/src/github.com/docker/distribution/cmd/registry/config-dev.yml
|
||||
INFO[0000] endpoint local-5003 disabled, skipping app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
|
||||
INFO[0000] endpoint local-8083 disabled, skipping app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
|
||||
INFO[0000] listening on :5000 app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
|
||||
INFO[0000] debug server listening localhost:5001
|
||||
```
|
||||
$ $GOPATH/bin/registry $GOPATH/src/github.com/docker/distribution/cmd/registry/config-example.yml
|
||||
INFO[0000] endpoint local-5003 disabled, skipping app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
|
||||
INFO[0000] endpoint local-8083 disabled, skipping app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
|
||||
INFO[0000] listening on :5000 app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
|
||||
INFO[0000] debug server listening localhost:5001
|
||||
|
||||
If it is working, one should see the above log messages.
|
||||
|
||||
|
|
@ -64,53 +78,47 @@ commands, such as `go test`, should work per package (please see
|
|||
A `Makefile` has been provided as a convenience to support repeatable builds.
|
||||
Please install the following into `GOPATH` for it to work:
|
||||
|
||||
```
|
||||
go get github.com/tools/godep github.com/golang/lint/golint
|
||||
```
|
||||
go get github.com/tools/godep github.com/golang/lint/golint
|
||||
|
||||
**TODO(stevvooe):** Add a `make setup` command to Makefile to run this. Have to think about how to interact with Godeps properly.
|
||||
|
||||
Once these commands are available in the `GOPATH`, run `make` to get a full
|
||||
build:
|
||||
|
||||
```
|
||||
$ GOPATH=`godep path`:$GOPATH make
|
||||
+ clean
|
||||
+ fmt
|
||||
+ vet
|
||||
+ lint
|
||||
+ build
|
||||
github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar
|
||||
github.com/Sirupsen/logrus
|
||||
github.com/docker/libtrust
|
||||
...
|
||||
github.com/yvasiyarov/gorelic
|
||||
github.com/docker/distribution/registry/handlers
|
||||
github.com/docker/distribution/cmd/registry
|
||||
+ test
|
||||
...
|
||||
ok github.com/docker/distribution/digest 7.875s
|
||||
ok github.com/docker/distribution/manifest 0.028s
|
||||
ok github.com/docker/distribution/notifications 17.322s
|
||||
? github.com/docker/distribution/registry [no test files]
|
||||
ok github.com/docker/distribution/registry/api/v2 0.101s
|
||||
? github.com/docker/distribution/registry/auth [no test files]
|
||||
ok github.com/docker/distribution/registry/auth/silly 0.011s
|
||||
...
|
||||
+ /Users/sday/go/src/github.com/docker/distribution/bin/registry
|
||||
+ /Users/sday/go/src/github.com/docker/distribution/bin/registry-api-descriptor-template
|
||||
+ binaries
|
||||
```
|
||||
$ GOPATH=`godep path`:$GOPATH make
|
||||
+ clean
|
||||
+ fmt
|
||||
+ vet
|
||||
+ lint
|
||||
+ build
|
||||
github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar
|
||||
github.com/Sirupsen/logrus
|
||||
github.com/docker/libtrust
|
||||
...
|
||||
github.com/yvasiyarov/gorelic
|
||||
github.com/docker/distribution/registry/handlers
|
||||
github.com/docker/distribution/cmd/registry
|
||||
+ test
|
||||
...
|
||||
ok github.com/docker/distribution/digest 7.875s
|
||||
ok github.com/docker/distribution/manifest 0.028s
|
||||
ok github.com/docker/distribution/notifications 17.322s
|
||||
? github.com/docker/distribution/registry [no test files]
|
||||
ok github.com/docker/distribution/registry/api/v2 0.101s
|
||||
? github.com/docker/distribution/registry/auth [no test files]
|
||||
ok github.com/docker/distribution/registry/auth/silly 0.011s
|
||||
...
|
||||
+ /Users/sday/go/src/github.com/docker/distribution/bin/registry
|
||||
+ /Users/sday/go/src/github.com/docker/distribution/bin/registry-api-descriptor-template
|
||||
+ binaries
|
||||
|
||||
The above provides a repeatable build using the contents of the vendored
|
||||
Godeps directory. This includes formatting, vetting, linting, building,
|
||||
testing and generating tagged binaries. We can verify this worked by running
|
||||
the registry binary generated in the "./bin" directory:
|
||||
|
||||
```sh
|
||||
$ ./bin/registry -version
|
||||
./bin/registry github.com/docker/distribution v2.0.0-alpha.2-80-g16d8b2c.m
|
||||
```
|
||||
$ ./bin/registry -version
|
||||
./bin/registry github.com/docker/distribution v2.0.0-alpha.2-80-g16d8b2c.m
|
||||
|
||||
### Developing
|
||||
|
||||
|
|
@ -124,9 +132,7 @@ can be demonstrated using `godep` to migrate the `GOPATH` to use the specified
|
|||
dependencies. The `GOPATH` can be migrated to the current package versions
|
||||
declared in `Godeps` with the following command:
|
||||
|
||||
```sh
|
||||
godep restore
|
||||
```
|
||||
godep restore
|
||||
|
||||
> **WARNING:** This command will checkout versions of the code specified in
|
||||
> Godeps/Godeps.json, modifying the contents of `GOPATH`. If this is
|
||||
|
|
@ -136,9 +142,7 @@ godep restore
|
|||
With a successful run of the above command, one can now use `make` without
|
||||
specifying the `GOPATH`:
|
||||
|
||||
```sh
|
||||
$ make
|
||||
```
|
||||
make
|
||||
|
||||
If that is successful, standard `go` commands, such as `go test` should work,
|
||||
per package, without issue.
|
||||
|
|
@ -151,6 +155,4 @@ the environment variable `DOCKER_BUILDTAGS`.
|
|||
To enable the [Ceph RADOS storage driver](storage-drivers/rados.md)
|
||||
(librados-dev and librbd-dev will be required to build the bindings):
|
||||
|
||||
```sh
|
||||
export DOCKER_BUILDTAGS='include_rados'
|
||||
```
|
||||
export DOCKER_BUILDTAGS='include_rados'
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue