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.
|
**Note**: The `master` branch may be in an *unstable or even broken state* during development.
|
||||||
The application is implemented as a set of API endpoints written in python and an Angular.js frontend.
|
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.
|
- Docker Registry Protocol [v1], [v2.1]
|
||||||
This method requires no installation of any python packages on your host machine.
|
- [AppC Image Discovery]
|
||||||
The `local-docker.sh` script is provided to prepare and run parts of quay.
|
- Authentication provided by [LDAP], [Keystone], [Dex], [Google], [GitHub]
|
||||||
First, start redis:
|
- 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
|
git clone git@github.com:coreos-inc/quay-config.git ../quay-config
|
||||||
ln -s ../../quay-config/local conf/stack
|
ln -s ../../quay-config/local conf/stack
|
||||||
```
|
```
|
||||||
|
|
||||||
To build and run a docker container, pass one argument to local-docker.sh:
|
#### clang errors
|
||||||
|
|
||||||
- `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`.
|
|
||||||
|
|
||||||
Some packages may fail to build with clang (which now defaults to C11).
|
Some packages may fail to build with clang (which now defaults to C11).
|
||||||
|
|
||||||
They can be installed with C99 with:
|
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
|
CFLAGS='-std=c99' pip install --no-cache --no-binary :all: cryptography
|
||||||
```
|
```
|
||||||
|
|
||||||
## Update Requirements
|
### Linux
|
||||||
|
|
||||||
1. Create a new virtualenv
|
TODO
|
||||||
2. Activate new virtualenv
|
|
||||||
3. Install unversioned dependencies
|
|
||||||
4. Run tests
|
|
||||||
5. Freeze requirements
|
|
||||||
6. Deactivate virtualenv
|
|
||||||
7. Remove virtualenv
|
|
||||||
|
|
||||||
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 virtualenv 2.7.11 quay-deps
|
||||||
pyenv activate quay-deps
|
pyenv activate quay-deps
|
||||||
|
|
||||||
|
# Install unversioned dependencies with your changes
|
||||||
pip install -r requirements-nover.txt
|
pip install -r requirements-nover.txt
|
||||||
|
|
||||||
|
# Run the unit test suite
|
||||||
./local-test.sh
|
./local-test.sh
|
||||||
|
|
||||||
|
# Freeze the versions of all of the dependencies
|
||||||
pip freeze > requirements.txt
|
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