From 125c03ab6813e661d2e6398b6767efcc8ee1cb93 Mon Sep 17 00:00:00 2001 From: Jimmy Zelinskie Date: Mon, 23 Jan 2017 15:44:53 -0500 Subject: [PATCH] README: update mac instructions also some misc cleanup --- README.md | 62 +++++++++++++++++++++++++++---------------------------- 1 file changed, 31 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index d8d0b4136..96eea5c0b 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,6 @@ High-level features include: 2. [Concepts](#concepts) 3. [Software](#software) - ## Getting Started ### macOS @@ -82,36 +81,37 @@ macOS developers will need: [xcode]: https://developer.apple.com/downloads [brew]: https://github.com/Homebrew/brew -``` +```sh # Download the code git clone git@github.com:coreos-inc/quay.git && cd quay # Install the system dependencies -brew install libevent libmagic postgresql gpgme pyenv pyenv-virtualenv docker docker-machine node +brew install libevent libmagic postgresql gpgme pyenv pyenv-virtualenv pyenv-pip-rehash docker docker-machine node -# create a default virtualmachine for docker +# Create a default virtualmachine for docker docker-machine create -d virtualbox default -# setup brew dependencies -# note you may want to add these to your bashrc or zshrc file +# Add these to ~/.bashrc or ~/.zshrc eval "$(pyenv virtualenv-init -)" eval "$(pyenv init -)" eval $(/usr/local/bin/docker-machine env default) # Some installs don't have /usr/include, required for finding SASL header files +# This command might fail because of the rootfs is read-only. Refer to the following: # http://apple.stackexchange.com/questions/196224/unix-ln-s-command-not-permitted-in-osx-el-capitan-beta3 -# note this command might fail because of new OSx write protections here above is a link that explains -# how to fix that if [ ! -e /usr/include ]; then sudo ln -s `xcrun --show-sdk-path`/usr/include /usr/include; fi # Install the Python dependencies -pyenv install 2.7.11 -pyenv virtualenv 2.7.11 quay +pyenv install 2.7.12 +pyenv virtualenv 2.7.12 quay pyenv activate quay +pyenv local quay # Some packages may fail to build with clang (which now defaults to C11). -CFLAGS='-std=c99' pip install -r requirements.txt +# If you're getting errors trying running again with CFLAGS='std=c99'. +pip install -r requirements.txt pip install -r requirements-dev.txt +pip install -r requirements-test.txt # Setup a local config git clone git@github.com:coreos-inc/quay-config.git ../quay-config @@ -124,18 +124,16 @@ npm install npm link typescript ``` -#### Useful docs +#### Third Party Docs -* [docker](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) +* [docker](https://beta.docker.com/docs/mac/getting-started) +* [docker-machine](https://docs.docker.com/machine/install-machine) * [pyenv](https://github.com/yyuu/pyenv) * [pyenv-virtualenv](https://github.com/yyuu/pyenv-virtualenv) - - ### Linux -TODO +Do you use Linux? Send us a PR! ## Development @@ -156,7 +154,6 @@ with "Finishes", the trigger will also click Finish on the story. Reference: PivotalTracker blog - [A Guide to GitHub’s Service Hook for Tracker](https://www.pivotaltracker.com/blog/guide-githubs-service-hook-tracker/) - ## Running and Testing ### Test Data @@ -169,7 +166,7 @@ The username and password of the admin test account is `devtable` and `password` Running the web server locally requires [goreman](https://github.com/mattn/goreman): -``` +```sh go get github.com/mattn/goreman ``` @@ -190,7 +187,7 @@ To build and run a development container, pass one argument to [local-docker.sh] ### Adding a Python Dependency -``` +```sh # Create a new virtualenv and activate it pyenv virtualenv 2.7.11 quay-deps pyenv activate quay-deps @@ -203,20 +200,23 @@ pip install -r requirements-nover.txt # Freeze the versions of all of the dependencies pip freeze > requirements.txt + +# Delete the virtualenv +pyenv uninstall quay-deps ``` ### Running the Build System TODO -``` +```sh # Run an instance of redis docker run -d -p 6379:6379 quay.io/quay/redis ``` ### To run individual tests -``` +```sh # To run a specific suite TEST=true python -m test.test_api_usage -f @@ -225,7 +225,7 @@ TEST=true python -m test.test_api_usage -f SuiteName ``` #### Pytest -``` +```sh # To run all tests TEST=true PYTHONPATH="." py.test --verbose @@ -246,14 +246,14 @@ TEST=true PYTHONPATH="." py.test --cov="." --cov-report=html --cov-report=term-m # Don't capture stdout (-s) TEST=true PYTHONPATH="." py.test --verbose -s - ``` #### Tox + To create a virtualenv to run the tests. It allows to test the code on multiple env like python2.x and python3.x or different library versions -``` +```sh # Test all tox env: tox @@ -267,7 +267,7 @@ tox -e py27-api ### Running migrations -``` +```sh # To create a new migration with this description. # Note there might be some errors about unique id being to long # That's okay as long as the migration file is created @@ -291,21 +291,22 @@ python initdb.py ### Running tests for migrations Use AWS/RDS to create a test image. -To create a new database from a snapshot to test against see +To create a new database from a snapshot to test against see [this](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_RestoreFromSnapshot.html). -Then point the migrations to the new instance using +Then point the migrations to the new instance using quay-config/local/config.yaml Remember to run this from the root of the quay directory and to set your python environment first. -``` +```sh PYTHONPATH=. alembic upgrade head ``` ### How to run a build with tests for a push or merge -``` + +```sh # Inside the quay directory. export QUAY_TAG=quay.io/quay/quay:localtest docker build -t $QUAY_TAG --build-arg RUN_TESTS=true . @@ -322,7 +323,6 @@ docker build -t $QUAY_TAG --build-arg RUN_TESTS=true . Edit chart on Google Docs at [Architecture at a Glance](https://docs.google.com/a/coreos.com/drawings/d/1J-YZs7aun1lLy-1wFwIZcBma5IJmZQ8WfgtEftHCKJ0/edit?usp=sharing). - ### Terminology #### Organizations