Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Include information about Windows usage and Python/DB versions in README #45

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Include information about Windows usage and Python/DB versions in README #45

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
71f14b5
Clarify need to specify appropriate versions in quick start guide
anorthall Dec 10, 2023
f2975c0
Change 'installation' to 'checkout'
anorthall Dec 10, 2023
5ca72aa
Rewrite quick start and add Windows help
anorthall Dec 11, 2023
1c98963
Merge branch 'main' into main
anorthall Dec 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 39 additions & 14 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,17 @@ 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. If
you are using Windows, see the [notes below](#usage-on-windows) before continuing.

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 checkout.
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.
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed this because I tested the error and it is extremely specific and could not be confused - not necessary to have here.

### Running tests

You can now either download the latest image used on the CI servers with the dependencies pre-installed:

Expand All @@ -26,14 +30,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:

Expand All @@ -47,21 +51,43 @@ And if you're mad you can run all the tests for all databases in parallel:

`docker-compose up`

#### Database versions
### Setting versions

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`

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.
Or use the following command to run the tests immediately:

## Different Python versions
`PYTHON_VERSION=3.12 POSTGRES_VERSION=15 docker-compose run --rm postgres`

The `PYTHON_VERSION` environment variable customizes which version of Python you are running the tests against. e.g:
## Usage on Windows

`PYTHON_VERSION=3.8 docker-compose run --rm sqlite`
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:

You can also pull the pre-built image in the same way:
* `PWD` set to the path of the root of this repository [^1]
* `DOCKER_DEFAULT_PLATFORM=linux/amd64` [^2]

`PYTHON_VERSION=3.8 docker-compose pull sqlite`
For example:

## Oracle
```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
Expand Down Expand Up @@ -102,7 +128,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
Expand Down