quay/README.md

# quay

![Docker Repository on Quay](https://quay.io/repository/quay/quay/status?token=7bffbc13-8bb0-4fb4-8a70-684a0cf485d3 "Docker Repository on Quay")

**Note**: The `master` branch may be in an *unstable or even broken state* during development.
Please use [releases] instead of the `master` branch in order to get stable binaries.

![Quay Logo](static/img/quay_preview.png)

Quay is project to build, store, and distribute container images.

High-level features include:

- Docker Registry Protocol [v1], [v2.1]
- [AppC Image Discovery]
- Authentication provided by [LDAP], [Keystone], [Dex], [Google], [GitHub]
- ACLs, team management, and auditability logs
- Geo-replicated storage provided by local filesystems, [S3], [GCS], [Swift], [Ceph]
- Continuous Integration integrated with [GitHub], [Bitbucket], [GitLab], and [git]
- Security Vulnerability Analysis via [Clair]
- [Swagger]-compliant HTTP API

[releases]: https://github.com/coreos-inc/quay/releases
[v1]: https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-1.md
[v2.1]: https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-2.md
[AppC Image Discovery]: https://github.com/appc/spec/blob/master/spec/discovery.md
[LDAP]: https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol
[Keystone]: http://docs.openstack.org/developer/keystone
[Dex]: https://github.com/coreos/dex
[Google]: https://developers.google.com/identity/sign-in/web/sign-in
[GitHub]: https://developer.github.com/v3/oauth
[S3]: https://aws.amazon.com/s3
[GCS]: https://cloud.google.com/storage
[Swift]: http://swift.openstack.org
[Ceph]: http://docs.ceph.com/docs/master/radosgw/config
[GitHub]: https://github.com
[Bitbucket]: https://bitbucket.com
[GitLab]: https://gitlab.com
[git]: https://git-scm.com
[Clair]: https://github.com/coreos/clair
[Swagger]: http://swagger.io

## Getting Started

### macOS

macOS developers will need:

* [command line tools] or [xcode]
* [brew]
* [Docker For Mac] or [Docker Machine]
* [pyenv] with [pyenv-virtualenv]

[command line tools]: https://developer.apple.com/downloads
[xcode]: https://developer.apple.com/downloads
[brew]: https://github.com/Homebrew/brew
[Docker For Mac]: https://beta.docker.com/docs/mac/getting-started://beta.docker.com/docs/mac/getting-started
[Docker Machine]: https://docs.docker.com/machine/install-machine://docs.docker.com/machine/install-machine
[pyenv]: https://github.com/yyuu/pyenv
[pyenv-virtualenv]: https://github.com/yyuu/pyenv-virtualenv

```
# Download the code
git clone git@github.com:coreos-inc/quay.git && cd quay

# Install the system dependencies
brew install libevent libmagic postgresql gpgme

# Some installs don't have /usr/include, required for finding SASL header files
if [ ! -e /usr/include ]; then sudo ln -s `xcrun --show-sdk-path`/usr/include /usr/include; fi

# Install the Python dependencies
pyenv virtualenv 2.7.11 quay
pyenv activate quay
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Setup a local config
git clone git@github.com:coreos-inc/quay-config.git ../quay-config
ln -s ../../quay-config/local conf/stack
```

#### clang errors

Some packages may fail to build with clang (which now defaults to C11).

They can be installed with C99 with:

```
CFLAGS='-std=c99' pip install --no-cache --no-binary :all: gevent
CFLAGS='-std=c99' pip install --no-cache --no-binary :all: cffi
CFLAGS='-std=c99' pip install --no-cache --no-binary :all: cryptography
```

### Linux

TODO

## Running and Testing

### Test Data

A SQLite database full of test data is committed to this git repository at `test/data/test.db`.
This database is generated by executing `python initdb.py`.
The username and password of the admin test account is `devtable` and `password`, respectively.

### Local Scripts

* `local-run` runs the web server for testing
* `local-test` runs the unit test suite

### Development inside Docker

To build and run a development container, pass one argument to local-docker.sh:

- `buildman`: run the buildmanager
- `dev`: run web server on port 5000
- `initdb`: clear and initialize the test database
- `notifications`: run the notification worker
- `test`: run the unit test suite

### Adding a Python Dependency

```
# Create a new virtualenv and activate it
pyenv virtualenv 2.7.11 quay-deps
pyenv activate quay-deps

# Install unversioned dependencies with your changes
pip install -r requirements-nover.txt

# Run the unit test suite
./local-test.sh

# Freeze the versions of all of the dependencies
pip freeze > requirements.txt
```

### Running the Build System

TODO

```
# Run an instance of redis
docker run -d -p 6379:6379 quay.io/quay/redis
```

## Documentation

* [Quay Enterprise Documentation](https://tectonic.com/quay-enterprise/docs/latest)
* [Quay.io Documentation](https://docs.quay.io)

### Architecture at a Glance

TODO

### Terminology

TODO