From 71f14b54fdc85aade1ffc065fd9a82b4950d6599 Mon Sep 17 00:00:00 2001 From: Andrew Northall Date: Sun, 10 Dec 2023 14:41:25 +0000 Subject: [PATCH 1/3] Clarify need to specify appropriate versions in quick start guide --- README.md | 39 ++++++++++++++++++++++++--------------- 1 file changed, 24 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index e6e4e5e..5b97f15 100644 --- a/README.md +++ b/README.md @@ -10,13 +10,26 @@ database versions, including Oracle. ## Quickstart -Clone this repository somewhere. Also make sure you have docker and docker-compose installed. +Clone this repository and ensure you have docker and docker-compose installed. -Ensure that the `DJANGO_PATH` variable points to the root of the Django repo: +### Environment + +You must set the `DJANGO_PATH` environment variable to the path of your local Django installation. +This can either be added to the `.env` file, or interactively set in your shell, like so: `export DJANGO_PATH=~/projects/django/` -If you see a docker-compose warning about it not being defined followed by an error ensure that is defined in the shell you are using. +You must also check the `.env` file (in the root of this repository) and ensure that the versions +of both Python and and database(s) you wish to test against are properly configured. For example, +Django 5.0 requires Python 3.10 (or later) and PostgreSQL 13 (or later), so if you wish to +test against Django 5.0 with PostgreSQL, an appropriate `.env` file may be: + +```env +PYTHON_VERSION=3.10 +POSTGRES_VERSION=13 +``` + +### Running tests You can now either download the latest image used on the CI servers with the dependencies pre-installed: @@ -26,14 +39,14 @@ Or build it yourself: `docker-compose build sqlite` -Then simply run: +Then run the following command to test against SQLite: `docker-compose run --rm sqlite` All arguments are passed to `runtests.py`. Before they are run all specific dependencies are installed (and cached across runs). -## Different databases +### Different databases Simply substitute `sqlite` for any supported database: @@ -47,19 +60,16 @@ And if you're mad you can run all the tests for all databases in parallel: `docker-compose up` -#### Database versions +### Setting versions -You can customize the version of the database you test against by changing the appropriate `[db]_VERSION` environment variable. See the Configuration section below for the available options and their defaults. +For convenience, you may quickly change between Python and database versions by setting the +appropriate environment variables inline, for example: -## Different Python versions +`PYTHON_VERSION=3.12 POSTGRES_VERSION=15 docker-compose pull postgres` -The `PYTHON_VERSION` environment variable customizes which version of Python you are running the tests against. e.g: +Or run the following command to run the tests immediately: -`PYTHON_VERSION=3.8 docker-compose run --rm sqlite` - -You can also pull the pre-built image in the same way: - -`PYTHON_VERSION=3.8 docker-compose pull sqlite` +`PYTHON_VERSION=3.12 POSTGRES_VERSION=15 docker-compose run --rm postgres` ## Oracle @@ -102,7 +112,6 @@ To enter a bash shell within the container, run: | `MYSQL_VERSION` | `8` | The mysql version to use | | `MARIADB_VERSION` | `10.4` | The mariadb version to use | - ## Why? I prefer using docker over Vagrant and virtualbox, which is what django-box uses. I think this From f2975c04078daabc029a970eeadcc979207e4fd6 Mon Sep 17 00:00:00 2001 From: Andrew Northall Date: Sun, 10 Dec 2023 15:34:01 +0000 Subject: [PATCH 2/3] Change 'installation' to 'checkout' --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5b97f15..bc57375 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Clone this repository and ensure you have docker and docker-compose installed. ### Environment -You must set the `DJANGO_PATH` environment variable to the path of your local Django installation. +You must set the `DJANGO_PATH` environment variable to the path of your local Django checkout. This can either be added to the `.env` file, or interactively set in your shell, like so: `export DJANGO_PATH=~/projects/django/` From 5ca72aa24a694e325fd6be27dd60481d177cf3ff Mon Sep 17 00:00:00 2001 From: Andrew Northall Date: Mon, 11 Dec 2023 11:14:33 +0000 Subject: [PATCH 3/3] Rewrite quick start and add Windows help --- README.md | 46 +++++++++++++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index bc57375..98670d0 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,8 @@ database versions, including Oracle. ## Quickstart -Clone this repository and ensure you have docker and docker-compose installed. +Clone this repository and ensure you have docker and docker-compose installed. If +you are using Windows, see the [notes below](#usage-on-windows) before continuing. ### Environment @@ -19,16 +20,6 @@ This can either be added to the `.env` file, or interactively set in your shell, `export DJANGO_PATH=~/projects/django/` -You must also check the `.env` file (in the root of this repository) and ensure that the versions -of both Python and and database(s) you wish to test against are properly configured. For example, -Django 5.0 requires Python 3.10 (or later) and PostgreSQL 13 (or later), so if you wish to -test against Django 5.0 with PostgreSQL, an appropriate `.env` file may be: - -```env -PYTHON_VERSION=3.10 -POSTGRES_VERSION=13 -``` - ### Running tests You can now either download the latest image used on the CI servers with the dependencies pre-installed: @@ -62,16 +53,41 @@ And if you're mad you can run all the tests for all databases in parallel: ### Setting versions -For convenience, you may quickly change between Python and database versions by setting the -appropriate environment variables inline, for example: +A common source of issues is testing using a version of Python, or a database version, +which is unsupported by your local Django checkout. The default versions set in the +repository `.env` file should always reflect the minimum requirements of the latest +development version of Django, however it is worth checking that these are correct +if you are having trouble. + +For convenience, you may quickly change between different Python and database versions +by setting the appropriate environment variables inline, for example: `PYTHON_VERSION=3.12 POSTGRES_VERSION=15 docker-compose pull postgres` -Or run the following command to run the tests immediately: +Or use the following command to run the tests immediately: `PYTHON_VERSION=3.12 POSTGRES_VERSION=15 docker-compose run --rm postgres` -## Oracle +## Usage on Windows + +Some additional configuration is necessary to enable the use of this utility on Windows. +The following environment variables will need to be added to the `.env` file in the +repository root: + +* `PWD` set to the path of the root of this repository [^1] +* `DOCKER_DEFAULT_PLATFORM=linux/amd64` [^2] + +For example: + +```env +PWD=C:\Users\username\Projects\django-docker-box +DOCKER_DEFAULT_PLATFORM=linux/amd64 +``` + +[^1]: On Linux and macOS, but not of Windows, `PWD` refers to the local directory. +[^2]: `apt-get` does not work on Windows. Setting `DOCKER_DEFAULT_PLATFORM=linux/amd64` enables the dependencies defined in the `Dockerfile` to be installed. + +## Testing against Oracle As usual Oracle is a bit more complex to set up. You need to download the latest `instantclient` **zip file** [from this page](https://www.oracle.com/technetwork/topics/linuxx86-64soft-092277.html) and place it inside the