README: CoreOS standard README format (#1550)
This change also moves the macOS local setup instructions into the README.
This commit is contained in:
Jimmy Zelinskie
GitHub
parent
5298452fa7
commit
672a6e9913
2 changed files with 124 additions and 83 deletions
184
README.md
184
README.md
|
|
@ -1,69 +1,89 @@
|
|||
# Quay - container image registry
|
||||
# quay
|
||||
|
||||
`master` branch build status: 
|
||||
|
||||
|
||||
Quay is a container image registry with managements APIs, a Docker registry API, a container build system.
|
||||
The application is implemented as a set of API endpoints written in python and an Angular.js frontend.
|
||||
**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.
|
||||
|
||||
## Setup Development Environment
|
||||
|
||||
|
||||
If you are doing local development on your workstation against the code base follow these instructions.
|
||||
Quay is project to build, store, and distribute container images.
|
||||
|
||||
### Docker
|
||||
High-level features include:
|
||||
|
||||
Quay and its parts can run inside of docker containers.
|
||||
This method requires no installation of any python packages on your host machine.
|
||||
The `local-docker.sh` script is provided to prepare and run parts of quay.
|
||||
First, start redis:
|
||||
- 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
|
||||
|
||||
```
|
||||
docker run -d -p 6379:6379 redis
|
||||
```
|
||||
# Download the code
|
||||
git clone git@github.com:coreos-inc/quay.git && cd quay
|
||||
|
||||
And clone the configuration repo:
|
||||
# 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
|
||||
```
|
||||
|
||||
To build and run a docker container, pass one argument to local-docker.sh:
|
||||
|
||||
- `dev`: run quay on port 5000
|
||||
- `buildman`: run the buildmanager
|
||||
- `notifications`: run the notification worker
|
||||
- `test`: run the unit tests
|
||||
- `initdb`: clear and initialize the test database
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
./local-docker.sh dev
|
||||
````
|
||||
|
||||
will start quay in a docker container.
|
||||
Now quay will be running on: http://127.0.0.1:5000
|
||||
The username is `devtable` and the password is `password`.
|
||||
|
||||
### OS X
|
||||
|
||||
```
|
||||
git clone git@github.com:coreos-inc/quay.git
|
||||
cd quay
|
||||
./contrib/osx/local-setup.sh
|
||||
```
|
||||
|
||||
Now run the server; it will use sqlite as the SQL server.
|
||||
|
||||
```
|
||||
./local-run.sh
|
||||
```
|
||||
|
||||
Now quay will be running on: http://127.0.0.1:5000
|
||||
The username is `devtable` and the password is `password`.
|
||||
#### clang errors
|
||||
|
||||
Some packages may fail to build with clang (which now defaults to C11).
|
||||
|
||||
They can be installed with C99 with:
|
||||
|
||||
```
|
||||
|
|
@ -72,24 +92,68 @@ CFLAGS='-std=c99' pip install --no-cache --no-binary :all: cffi
|
|||
CFLAGS='-std=c99' pip install --no-cache --no-binary :all: cryptography
|
||||
```
|
||||
|
||||
## Update Requirements
|
||||
### Linux
|
||||
|
||||
1. Create a new virtualenv
|
||||
2. Activate new virtualenv
|
||||
3. Install unversioned dependencies
|
||||
4. Run tests
|
||||
5. Freeze requirements
|
||||
6. Deactivate virtualenv
|
||||
7. Remove virtualenv
|
||||
TODO
|
||||
|
||||
Example (commands may differ dependending on virtualenv tools):
|
||||
## Running and Testing
|
||||
|
||||
### Test Data
|
||||
|
||||
A SQLite database full of test data is committed to this git repository.
|
||||
This database is generated by executing `python initdb.py`.
|
||||
The username and password of the admin 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
|
||||
pyenv deactivate quay-deps
|
||||
pyenv uninstall quay-deps
|
||||
```
|
||||
|
||||
### 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
|
||||
|
|
|
|||
|
|
@ -1,23 +0,0 @@
|
|||
#!/bin/bash
|
||||
|
||||
# Put us at the root of the quay repo no matter what
|
||||
pushd $(dirname "${0}") > /dev/null
|
||||
basedir=$(pwd -L)
|
||||
cd "${basedir}"/../../
|
||||
|
||||
# Install Docker and C libraries on which Python libraries are dependent
|
||||
brew update
|
||||
brew upgrade
|
||||
brew install boot2docker docker libevent libmagic postgresql gpgme
|
||||
|
||||
# Some OSX installs don't have /usr/include, which is required for finding SASL headers for our LDAP library
|
||||
if [ ! -e /usr/include ]; then
|
||||
sudo ln -s `xcrun --show-sdk-path`/usr/include /usr/include
|
||||
fi
|
||||
|
||||
# Install Python dependencies
|
||||
sudo pip install -r requirements.txt
|
||||
|
||||
# Put the local testing config in place
|
||||
git clone git@github.com:coreos-inc/quay-config.git ../quay-config
|
||||
ln -s ../../quay-config/local conf/stack
|
||||
Reference in a new issue