1
2# Building the registry source
3
4## Use-case
5
6This is useful if you intend to actively work on the registry.
7
8### Alternatives
9
10Most people should use the [official Registry docker image](https://hub.docker.com/r/library/registry/).
11
12People looking for advanced operational use cases might consider rolling their own image with a custom Dockerfile inheriting `FROM registry:2`.
13
14OS X users who want to run natively can do so following [the instructions here](https://github.com/docker/docker.github.io/blob/master/registry/recipes/osx-setup-guide.md).
15
16### Gotchas
17
18You are expected to know your way around with go & git.
19
20If 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.
21
22## Build the development environment
23
24The first prerequisite of properly building distribution targets is to have a Go
25development environment setup. Please follow [How to Write Go Code](https://golang.org/doc/code.html)
26for proper setup. If done correctly, you should have a GOROOT and GOPATH set in the
27environment.
28
29If a Go development environment is setup, one can use `go get` to install the
30`registry` command from the current latest:
31
32    go get github.com/docker/distribution/cmd/registry
33
34The above will install the source repository into the `GOPATH`.
35
36Now create the directory for the registry data (this might require you to set permissions properly)
37
38    mkdir -p /var/lib/registry
39
40... or alternatively `export REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere` if you want to store data into another location.
41
42The `registry`
43binary can then be run with the following:
44
45    $ $GOPATH/bin/registry --version
46    $GOPATH/bin/registry github.com/docker/distribution v2.0.0-alpha.1+unknown
47
48> __NOTE:__ While you do not need to use `go get` to checkout the distribution
49> project, for these build instructions to work, the project must be checked
50> out in the correct location in the `GOPATH`. This should almost always be
51> `$GOPATH/src/github.com/docker/distribution`.
52
53The registry can be run with the default config using the following
54incantation:
55
56    $ $GOPATH/bin/registry serve $GOPATH/src/github.com/docker/distribution/cmd/registry/config-example.yml
57    INFO[0000] endpoint local-5003 disabled, skipping        app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
58    INFO[0000] endpoint local-8083 disabled, skipping        app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
59    INFO[0000] listening on :5000                            app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
60    INFO[0000] debug server listening localhost:5001
61
62If it is working, one should see the above log messages.
63
64### Repeatable Builds
65
66For the full development experience, one should `cd` into
67`$GOPATH/src/github.com/docker/distribution`. From there, the regular `go`
68commands, such as `go test`, should work per package (please see
69[Developing](#developing) if they don't work).
70
71A `Makefile` has been provided as a convenience to support repeatable builds.
72Please install the following into `GOPATH` for it to work:
73
74    go get github.com/golang/lint/golint
75
76Once these commands are available in the `GOPATH`, run `make` to get a full
77build:
78
79    $ make
80    + clean
81    + fmt
82    + vet
83    + lint
84    + build
85    github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar
86    github.com/sirupsen/logrus
87    github.com/docker/libtrust
88    ...
89    github.com/yvasiyarov/gorelic
90    github.com/docker/distribution/registry/handlers
91    github.com/docker/distribution/cmd/registry
92    + test
93    ...
94    ok    github.com/docker/distribution/digest 7.875s
95    ok    github.com/docker/distribution/manifest 0.028s
96    ok    github.com/docker/distribution/notifications  17.322s
97    ?     github.com/docker/distribution/registry [no test files]
98    ok    github.com/docker/distribution/registry/api/v2  0.101s
99    ?     github.com/docker/distribution/registry/auth  [no test files]
100    ok    github.com/docker/distribution/registry/auth/silly  0.011s
101    ...
102    + /Users/sday/go/src/github.com/docker/distribution/bin/registry
103    + /Users/sday/go/src/github.com/docker/distribution/bin/registry-api-descriptor-template
104    + binaries
105
106The above provides a repeatable build using the contents of the vendor
107directory. This includes formatting, vetting, linting, building,
108testing and generating tagged binaries. We can verify this worked by running
109the registry binary generated in the "./bin" directory:
110
111    $ ./bin/registry --version
112    ./bin/registry github.com/docker/distribution v2.0.0-alpha.2-80-g16d8b2c.m
113
114### Optional build tags
115
116Optional [build tags](http://golang.org/pkg/go/build/) can be provided using
117the environment variable `DOCKER_BUILDTAGS`.
118