github.com/mika/distribution@v2.2.2-0.20160108133430-a75790e3d8e0+incompatible/docs/building.md (about)

     1  <!--[metadata]>
     2  +++
     3  title = "Build instructions"
     4  description = "Explains how to build & hack on the registry"
     5  keywords = ["registry, on-prem, images, tags, repository, distribution, build, recipe, advanced"]
     6  +++
     7  <![end-metadata]-->
     8  
     9  # Building the registry source
    10  
    11  ## Use-case
    12  
    13  This is useful if you intend to actively work on the registry.
    14  
    15  ### Alternatives
    16  
    17  Most people should use the [official Registry docker image](https://hub.docker.com/r/library/registry/).
    18  
    19  People looking for advanced operational use cases might consider rolling their own image with a custom Dockerfile inheriting `FROM registry:2`.
    20  
    21  OS X users who want to run natively can do so following [the instructions here](osx-setup-guide.md).
    22  
    23  ### Gotchas
    24  
    25  You are expected to know your way around with go & git.
    26  
    27  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.
    28  
    29  ## Build the development environment
    30  
    31  The first prerequisite of properly building distribution targets is to have a Go
    32  development environment setup. Please follow [How to Write Go Code](https://golang.org/doc/code.html)
    33  for proper setup. If done correctly, you should have a GOROOT and GOPATH set in the
    34  environment.
    35  
    36  If a Go development environment is setup, one can use `go get` to install the
    37  `registry` command from the current latest:
    38  
    39      go get github.com/docker/distribution/cmd/registry
    40  
    41  The above will install the source repository into the `GOPATH`.
    42  
    43  Now create the directory for the registry data (this might require you to set permissions properly)
    44  
    45      mkdir -p /var/lib/registry
    46  
    47  ... or alternatively `export REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere` if you want to store data into another location.
    48  
    49  The `registry`
    50  binary can then be run with the following:
    51  
    52      $ $GOPATH/bin/registry --version
    53      $GOPATH/bin/registry github.com/docker/distribution v2.0.0-alpha.1+unknown
    54  
    55  > __NOTE:__ While you do not need to use `go get` to checkout the distribution
    56  > project, for these build instructions to work, the project must be checked
    57  > out in the correct location in the `GOPATH`. This should almost always be
    58  > `$GOPATH/src/github.com/docker/distribution`.
    59  
    60  The registry can be run with the default config using the following
    61  incantation:
    62  
    63      $ $GOPATH/bin/registry $GOPATH/src/github.com/docker/distribution/cmd/registry/config-example.yml
    64      INFO[0000] endpoint local-5003 disabled, skipping        app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
    65      INFO[0000] endpoint local-8083 disabled, skipping        app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
    66      INFO[0000] listening on :5000                            app.id=34bbec38-a91a-494a-9a3f-b72f9010081f version=v2.0.0-alpha.1+unknown
    67      INFO[0000] debug server listening localhost:5001
    68  
    69  If it is working, one should see the above log messages.
    70  
    71  ### Repeatable Builds
    72  
    73  For the full development experience, one should `cd` into
    74  `$GOPATH/src/github.com/docker/distribution`. From there, the regular `go`
    75  commands, such as `go test`, should work per package (please see
    76  [Developing](#developing) if they don't work).
    77  
    78  A `Makefile` has been provided as a convenience to support repeatable builds.
    79  Please install the following into `GOPATH` for it to work:
    80  
    81      go get github.com/tools/godep github.com/golang/lint/golint
    82  
    83  **TODO(stevvooe):** Add a `make setup` command to Makefile to run this. Have to think about how to interact with Godeps properly.
    84  
    85  Once these commands are available in the `GOPATH`, run `make` to get a full
    86  build:
    87  
    88      $ GOPATH=`godep path`:$GOPATH make
    89      + clean
    90      + fmt
    91      + vet
    92      + lint
    93      + build
    94      github.com/docker/docker/vendor/src/code.google.com/p/go/src/pkg/archive/tar
    95      github.com/Sirupsen/logrus
    96      github.com/docker/libtrust
    97      ...
    98      github.com/yvasiyarov/gorelic
    99      github.com/docker/distribution/registry/handlers
   100      github.com/docker/distribution/cmd/registry
   101      + test
   102      ...
   103      ok    github.com/docker/distribution/digest 7.875s
   104      ok    github.com/docker/distribution/manifest 0.028s
   105      ok    github.com/docker/distribution/notifications  17.322s
   106      ?     github.com/docker/distribution/registry [no test files]
   107      ok    github.com/docker/distribution/registry/api/v2  0.101s
   108      ?     github.com/docker/distribution/registry/auth  [no test files]
   109      ok    github.com/docker/distribution/registry/auth/silly  0.011s
   110      ...
   111      + /Users/sday/go/src/github.com/docker/distribution/bin/registry
   112      + /Users/sday/go/src/github.com/docker/distribution/bin/registry-api-descriptor-template
   113      + binaries
   114  
   115  The above provides a repeatable build using the contents of the vendored
   116  Godeps directory. This includes formatting, vetting, linting, building,
   117  testing and generating tagged binaries. We can verify this worked by running
   118  the registry binary generated in the "./bin" directory:
   119  
   120      $ ./bin/registry -version
   121      ./bin/registry github.com/docker/distribution v2.0.0-alpha.2-80-g16d8b2c.m
   122  
   123  ### Developing
   124  
   125  The above approaches are helpful for small experimentation. If more complex
   126  tasks are at hand, it is recommended to employ the full power of `godep`.
   127  
   128  The Makefile is designed to have its `GOPATH` defined externally. This allows
   129  one to experiment with various development environment setups. This is
   130  primarily useful when testing upstream bugfixes, by modifying local code. This
   131  can be demonstrated using `godep` to migrate the `GOPATH` to use the specified
   132  dependencies. The `GOPATH` can be migrated to the current package versions
   133  declared in `Godeps` with the following command:
   134  
   135      godep restore
   136  
   137  > **WARNING:** This command will checkout versions of the code specified in
   138  > Godeps/Godeps.json, modifying the contents of `GOPATH`. If this is
   139  > undesired, it is recommended to create a workspace devoted to work on the
   140  > _Distribution_ project.
   141  
   142  With a successful run of the above command, one can now use `make` without
   143  specifying the `GOPATH`:
   144  
   145      make
   146  
   147  If that is successful, standard `go` commands, such as `go test` should work,
   148  per package, without issue.
   149  
   150  ### Optional build tags
   151  
   152  Optional [build tags](http://golang.org/pkg/go/build/) can be provided using
   153  the environment variable `DOCKER_BUILDTAGS`.
   154  
   155  To enable the [Ceph RADOS storage driver](storage-drivers/rados.md)
   156  (librados-dev and librbd-dev will be required to build the bindings):
   157  
   158      export DOCKER_BUILDTAGS='include_rados'