From: Stephen Finucane Date: Mon, 29 Aug 2016 23:35:39 +0000 (+0100) Subject: docs: Make Docker the recommended install method X-Git-Tag: v2.0.0-rc1~276 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0d75ce35494f1d27daf58950d57bb6ee866518f1;p=thirdparty%2Fpatchwork.git docs: Make Docker the recommended install method Docker is faster, lighter and "hipper" than Vagrant. Promote this method over the Vagrant approach. Signed-off-by: Stephen Finucane Reviewed-by: Daniel Axtens --- diff --git a/README.md b/README.md index 996d5064..62e9c4f4 100644 --- a/README.md +++ b/README.md @@ -20,55 +20,29 @@ subsystems of the Linux kernel. Although Patchwork has been developed with the kernel workflow in mind, the aim is to be flexible enough to suit the majority of community projects. -# Development Installation using Vagrant +# Development Installation -1. Install [**Vagrant**][ref-vagrant] -2. Clone this repo: +[Docker][ref-docker] is the recommended installation methods for a Patchwork +development environment. To install Patchwork: - $ git clone git://github.com/getpatchwork/patchwork.git +1. Install [**Docker**][ref-docker] and [**docker-compose**][ref-compose]. +2. Clone the Patchwork repo: -3. Run `vagrant up`: + $ git clone https://github.com/getpatchwork/patchwork.git - $ cd patchwork - $ vagrant up - -# Development Installation using Docker - -1. Install Docker and docker-compose. -2. Clone this repo, as with vagrant. 3. Build the images. This will download over 200MB from the internet: $ docker-compose build -4. Run as follows: - - * Regular server: - - $ docker-compose up - - This will be visible on http://localhost:8000/. - - * Shell: - - $ docker-compose run --rm web --shell - - * Quick test (not including selenium UI interaction tests): - - $ docker-compose run --rm web --quick-test - - * Full tests, including selenium, run headlessly: - - $ docker-compose run --rm web --test - - * Tox tests can be run with `--quick-tox` and `--tox`. - - * To reset the database before beginning, add `--reset` to the command line after `web` and before any other arguments. +4. Run `docker-compose up`: - * If you want to run non-headless tests, you'll need something like this ugly hack: + $ docker-compose up - $ docker run -it --rm -v (pwd):/home/patchwork/patchwork/ --link patchwork_db_1:db -p 8000:8000 -v /tmp/.X11-unix:/tmp/.X11-unix -e PW_TEST_DB_HOST=db -e DISPLAY patchwork_web bash +The Patchwork instance will now be deployed at `http://localhost:8000/`. -With both vagrant and docker, any edits to the project files made locally are immediately visible to the VM/container, and so should be picked up by the Django auto-reloader. +For more information, including helpful command line options and alternative +installation methods, refer to the [development installation +guide][docs-development]. # Talks and Presentations @@ -92,7 +66,9 @@ For bug reports, patch submissions or other questions, please use the [badge-waffle-ref]: https://waffle.io/getpatchwork/patchwork [badge-waffle-img]: https://badge.waffle.io/getpatchwork/patchwork.svg?label=ready&title=Ready [docs]: https://patchwork.readthedocs.org/en/latest/ +[docs-development]: https://patchwork.readthedocs.org/en/latest/development/ [pdf-fosdem]: https://speakerdeck.com/stephenfin/a-new-patchwork-bringing-ci-patch-tracking-and-more-to-the-mailing-list [pdf-plumbers]: https://www.linuxplumbersconf.org/2011/ocw/system/presentations/255/original/patchwork.pdf [pw-ml]: https://ozlabs.org/mailman/listinfo/patchwork -[ref-vagrant]: https://www.vagrantup.com/docs/getting-started/ +[ref-compose]: https://docs.docker.com/compose/install/ +[ref-docker]: https://docs.docker.com/engine/installation/linux/ diff --git a/docs/development.md b/docs/development.md index 593eddfc..4fe3bef5 100644 --- a/docs/development.md +++ b/docs/development.md @@ -9,21 +9,81 @@ To begin, you should clone Patchwork: $ git clone git://github.com/getpatchwork/patchwork.git +## Docker-Based Installation + +Patchwork provides a Docker-based environment for quick configuration of a +development environment. This is the preferred installation method. To +configure Patchwork using Docker: + +1. Install [**Docker**][ref-docker] and [**docker-compose**][ref-compose]. +2. Build the images. This will download over 200MB from the internet: + + $ docker-compose build + +3. Run `docker-compose up`: + + $ docker-compose up + + This will be visible at http://localhost:8000/. + +To run a shell within this environment, run: + + $ docker-compose run --rm web --shell + +To run unit tests, excluding Selenium UI interaction tests, using only the +package versions installed during container initialization, run: + + $ docker-compose run --rm web --quick-test + +To run the same against all supported versions of Django (via tox), run: + + $ docker-compose run --rm web --quick-tox + +To run all tests, including Selenium UI interaction tests, using only the +package versions installed container initialization, run: + + $ docker-compose run --rm web --test + +To run the same against all supported versions of Django (via tox), run: + + $ docker-compose run --rm web --tox + +To run all tests, including Selenium UI interaction tests in non-headless mode, +run: + + $ docker run -it --rm -v (pwd):/home/patchwork/patchwork/ \ + --link patchwork_db_1:db -p 8000:8000 \ + -v /tmp/.X11-unix:/tmp/.X11-unix \ + -e PW_TEST_DB_HOST=db -e DISPLAY patchwork_web bash + +To reset the database before any of these commands, add `--reset` to the +command line after `web` and before any other arguments. + +Any local edits to the project files made locally are immediately visible to +the Docker container, and so should be picked up by the Django auto-reloader. + +For more information on Docker itself, please refer to the [Docker][ref-docker] +and [docker-compose][ref-compose] documentation. + ## Vagrant-Based Installation -Patchwork provides a Vagrantfile that can be used to quickly configure -Patchwork in a development environment. Like any Vagrant VM, you can start this -using the `vagrant up` command: +Patchwork provides a Vagrant-based environment as an alternative to Docker. +Like Docker, Vagrant can be used to quickly configure Patchwork in a +development environment. To configure Patchwork using Vagrant: + +1. Install [**Vagrant**][ref-vagrant] +2. Run `vagrant up` from the project directory: - $ cd patchwork # the path to the repo you cloned above - $ vagrant up + $ cd patchwork + $ vagrant up Once stacked, follow the on-screen instructions. For more information on -Vagrant itself, please refer to the [Vagrant documentation](ref-vagrant). +Vagrant itself, please refer to the [Vagrant documentation][ref-vagrant]. ## Manual Installation -Manual installation can be used where Vagrant is not possible, or not desired. +Manual installation can be used where use of Docker or Vagrant is not possible or +desired. ### Install Required Packages @@ -260,5 +320,7 @@ using the provided `dev` settings file. [ref-py34-pip]: http://legacy.python.org/dev/peps/pep-0453/ [ref-sqlite-utf8]: https://www.sqlite.org/faq.html#q18 [ref-tox]: https://tox.readthedocs.org/en/latest/ +[ref-compose]: https://docs.docker.com/compose/install/ +[ref-docker]: https://docs.docker.com/engine/installation/linux/ [ref-vagrant]: https://www.vagrantup.com/docs/getting-started/ [ref-venv]: https://virtualenv.readthedocs.org/en/latest/