vbatts/registry
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Breaking out README

Browse source 
Adding new material
Adding in template chomped in error
Cover install/deploy in README
Adding in Stephen's comments
Fixing you tabs!
Updating with commentary from pr
Updating with last minute comments

Signed-off-by: Mary Anthony <mary@docker.com>
This commit is contained in:
Mary Anthony 2015-04-02 08:11:19 -07:00
parent 37f600a498
commit cf9b4ab5e9
25 changed files with 766 additions and 265 deletions
Download patch file Download diff file Expand all files Collapse all files

278
README.md
View file

@ -1,47 +1,37 @@
> **Notice:** *This repository hosts experimental components that are
> currently under heavy and fast-paced development, not-ready for public
> consumption. If you are looking for the stable registry, please head over to
> [docker/docker-registry](https://github.com/docker/docker-registry)
> instead.*
Distribution
============
# Distribution
The Docker toolset to pack, ship, store, and deliver content.
The main product of this repository is the new registry implementation for
storing and distributing docker images. It supersedes the [docker/docker-
This repository's main product is the Docker Registry Service 2.0 implementation
for storing and distributing Docker images. It supersedes the [docker/docker-
registry](https://github.com/docker/docker-registry) project with a new API
design, focused around security and performance.
The _Distribution_ project has the further long term goal of providing a
secure tool chain for distributing content. The specifications, APIs and tools
should be as useful with docker as they are without.
This repository contains the following components:
- **registry (beta):** An implementation of the [Docker Registry HTTP API
V2](doc/spec/api.md) for use with docker 1.5+.
- **libraries (unstable):** A rich set of libraries for interacting with
distribution components. Please see
[godoc](http://godoc.org/github.com/docker/distribution) for details. Note
that the libraries *are not* considered stable.
- **dist (experimental):** An experimental tool to provide distribution
oriented functionality without the docker daemon.
- **specifications**: _Distribution_ related specifications are available in
[doc/spec](doc/spec).
- **documentation:** Documentation is available in [doc](doc/overview.md).
|**Component** |Description |
|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **registry** | An implementation of the [Docker Registry HTTP API V2](docs/spec/api.md) for use with docker 1.5+. |
| **libraries** | A rich set of libraries for interacting with,distribution components. Please see [godoc](http://godoc.org/github.com/docker/distribution) for details. **Note**: These libraries are **unstable**. |
| **dist** | An _experimental_ tool to provide distribution, oriented functionality without the `docker` daemon. |
| **specifications** | _Distribution_ related specifications are available in [docs/spec](docs/spec) |
| **documentation** | Documentation is available in [doc](http://docs.docker.com/distribution). |
### How will this integrate with Docker engine?
### How does this integrate with Docker engine?
This project should provide an implementation to a V2 API for use in the
Docker core project. The API should be embeddable and simplify the process of
securely pulling and pushing content from docker daemons.
This project should provide an implementation to a V2 API for use in the [Docker
core project](https://github.com/docker/docker). The API should be embeddable
and simplify the process of securely pulling and pushing content from `docker`
daemons.
### What are the long term goals of the Distribution project?
Design a professional grade and extensible content distribution system, that
allow users to:
The _Distribution_ project has the further long term goal of providing a
secure tool chain for distributing content. The specifications, APIs and tools
should be as useful with Docker as they are without.
Our goal is to design a professional grade and extensible content distribution
system that allow users to:
* Enjoy an efficient, secured and reliable way to store, manage, package and
exchange content
@ -49,8 +39,7 @@ allow users to:
* Implement their own home made solution through good specs, and solid
extensions mechanism.
Features
--------
## More about Registry 2.0
The new registry implementation provides the following benefits:
@ -62,190 +51,67 @@ The new registry implementation provides the following benefits:
For information on upcoming functionality, please see [ROADMAP.md](ROADMAP.md).
Installation
------------
### Who needs to deploy a registry?
**TODO(stevvooe):** Add the following here:
- docker file
- binary builds for non-docker environment (test installations, etc.)
By default, Docker users pull images from Docker's public registry instance.
[Installing Docker](http://docs.docker.com/installation) gives users this
ability. Users can also push images to a repository on Docker's public registry,
if they have a [Docker Hub](https://hub.docker.com/) account.
Configuration
-------------
For some users and even companies, this default behavior is sufficient. For
others, it is not.
The registry server can be configured with a yaml file. The following is a
simple example that can used for local development:
For example, users with their own software products and may want to maintain an
registry for private, company images. Also, you may wish to deploy your own
image repository for images used to test or in continuous integration. For these
use cases and others, [deploying your own registry instance](docs/deploying.md)
may be the better choice.
```yaml
version: 0.1
loglevel: debug
storage:
filesystem:
rootdirectory: /tmp/registry-dev
http:
addr: localhost:5000
secret: asecretforlocaldevelopment
debug:
addr: localhost:5001
```
## Contribute
The above configures the registry instance to run on port 5000, binding to
"localhost", with the debug server enabled. Registry data will be stored in
"/tmp/registry-dev". Logging will be in "debug" mode, which is the most
verbose.
Please see [CONTRIBUTING.md](CONTRIBUTING.md).
A similar simple configuration is available at [cmd/registry/config.yml],
which is generally useful for local development.
**TODO(stevvooe): Need a "best practice" configuration overview. Perhaps, we
can point to a documentation section.
For full details about configuring a registry server, please see [the
documentation](doc/configuration.md).
### Upgrading
**TODO:** Add a section about upgrading from V1 registry along with link to
migrating in documentation.
Build
-----
If a go development environment is setup, one can use `go get` to install the
`registry` command from the current latest:
```sh
go get github.com/docker/distribution/cmd/registry
```
The above will install the source repository into the `GOPATH`. 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
```
The registry can be run with the default config using the following
incantantation:
```
$ $GOPATH/bin/registry $GOPATH/src/github.com/docker/distribution/cmd/registry/config.yml
INFO[0000] endpoint local-8082 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.
### Repeatable Builds
For the full development experience, one should `cd` into
`$GOPATH/src/github.com/docker/distribution`. From there, the regular `go`
commands, such as `go test`, should work per package (please see
[Developing](#developing) if they don't work).
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
```
**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
+ /Users/sday/go/src/github.com/docker/distribution/bin/dist
+ 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
```
### Developing
The above approaches are helpful for small experimentation. If more complex
tasks are at hand, it is recommended to employ the full power of `godep`.
The Makefile is designed to have its `GOPATH` defined externally. This allows
one to experiment with various development environment setups. This is
primarily useful when testing upstream bugfixes, by modifying local code. This
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
```
> **WARNING:** This command will checkout versions of the code specified in
> Godeps/Godeps.json, modifying the contents of `GOPATH`. If this is
> undesired, it is recommended to create a workspace devoted to work on the
> _Distribution_ project.
With a successful run of the above command, one can now use `make` without
specifying the `GOPATH`:
```sh
$ make
```
If that is successful, standard `go` commands, such as `go test` should work,
per package, without issue.
Support
-------
## Support
If any issues are encountered while using the _Distribution_ project, several
avenues are available for support:
IRC: #docker-distribution on FreeNode
Issue Tracker: github.com/docker/distribution/issues
Google Groups: https://groups.google.com/a/dockerproject.org/forum/#!forum/distribution
Mailing List: docker@dockerproject.org
<table>
<tr>
<th align="left">
IRC
</th>
<td>
#docker-distribution on FreeNode
</td>
</tr>
<tr>
<th align="left">
Issue Tracker
</th>
<td>
github.com/docker/distribution/issues
</td>
</tr>
<tr>
<th align="left">
Google Groups
</th>
<td>
https://groups.google.com/a/dockerproject.org/forum/#!forum/distribution
</td>
</tr>
<tr>
<th align="left">
Mailing List
</th>
<td>
docker@dockerproject.org
</td>
</tr>
</table>
Contribute
----------
Please see [CONTRIBUTING.md](CONTRIBUTING.md).
License
-------
## License
This project is distributed under [Apache License, Version 2.0](LICENSE.md).