From patchwork Mon Aug 29 23:35:39 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 663881 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [103.22.144.68]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3sNShZ1ZB8z9rxv for ; Tue, 30 Aug 2016 09:36:14 +1000 (AEST) Received: from ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 3sNShZ0bbCzDrjL for ; Tue, 30 Aug 2016 09:36:14 +1000 (AEST) X-Original-To: patchwork@lists.ozlabs.org Delivered-To: patchwork@lists.ozlabs.org Received: from BLU004-OMC3S25.hotmail.com (blu004-omc3s25.hotmail.com [65.55.116.100]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 3sNShK2QNdzDrh4 for ; Tue, 30 Aug 2016 09:36:01 +1000 (AEST) Received: from BLU436-SMTP90 ([65.55.116.74]) by BLU004-OMC3S25.hotmail.com over TLS secured channel with Microsoft SMTPSVC(7.5.7601.23008); Mon, 29 Aug 2016 16:35:57 -0700 X-TMN: [y5LYn33nICMyqeqX13iuoJVKqwM7WikL] X-Originating-Email: [stephenfinucane@hotmail.com] Message-ID: From: Stephen Finucane To: patchwork@lists.ozlabs.org Subject: [PATCH v2 2/4] docs: Make Docker the recommended install method Date: Tue, 30 Aug 2016 00:35:39 +0100 X-Mailer: git-send-email 2.7.4 In-Reply-To: <1472513741-9366-1-git-send-email-stephenfinucane@hotmail.com> References: <1472513741-9366-1-git-send-email-stephenfinucane@hotmail.com> X-OriginalArrivalTime: 29 Aug 2016 23:35:55.0027 (UTC) FILETIME=[16325E30:01D2024E] MIME-Version: 1.0 X-BeenThere: patchwork@lists.ozlabs.org X-Mailman-Version: 2.1.22 Precedence: list List-Id: Patchwork development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: patchwork-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Patchwork" Docker is faster, lighter and "hipper" than Vagrant. Promote this method over the Vagrant approach. Signed-off-by: Stephen Finucane Reviewed-by: Daniel Axtens --- v2: - Update to include '--tox' and '--quick-tox' options - Refer to command line references in README --- README.md | 54 +++++++++++--------------------------- docs/development.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 83 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 996d506..62e9c4f 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 593eddf..d1267c6 100644 --- a/docs/development.md +++ b/docs/development.md @@ -9,21 +9,80 @@ 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 provided by the container, 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 run headlessly, using only the package +versions provided by the container, 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 in non-headless tests: + + $ 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 +319,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/