@@ -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/
@@ -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/
Docker is faster, lighter and "hipper" than Vagrant. Promote this method over the Vagrant approach. Signed-off-by: Stephen Finucane <stephenfinucane@hotmail.com> --- 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(-)