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 2 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
39 changes: 24 additions & 15 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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.

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
```

anorthall marked this conversation as resolved.
Show resolved Hide resolved
anorthall marked this conversation as resolved.
Show resolved Hide resolved
### Running tests

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

Expand All @@ -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:

Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down