Skip to content

Commit 06aed4a

Browse files
ngnpopengnpope
committed
Reworked documentation in README.md.
Add much more guidance on using the tools within this repository.
1 parent dd31887 commit 06aed4a

File tree

1 file changed

+273
-44
lines changed

1 file changed

+273
-44
lines changed

‎README.md

+273-44
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,311 @@
1-
# django-docker-box
1+
# Django Toolbox
2+
3+
Tooling and test execution support for [Django][0] :unicorn:
4+
5+
:heart: Support Django development by [donating][1] to the Django Software Foundation.
6+
7+
8+
## Highlights
9+
10+
- :test\_tube: Test supported core database backends — MariaDB, MySQL, Oracle, PostgreSQL, SQLite
11+
- :earth\_africa: Test supported core geospatial backends — MariaDB, MySQL, Oracle, PostGIS, SpatiaLite
12+
- :globe\_with\_meridians: Test user interfaces in different browsers using Selenium — Chrome, Edge, Firefox
13+
- :snake: Test using different Python interpreters — CPython, PyPy
14+
- :broom: Execute linting and formatting tools on the Django repository
15+
- :books: Build the project documentation using Sphinx and run spelling and link checkers
216

3-
Run the django test suite across multiple databases.
417

518
## Quickstart
619

7-
Clone this repository somewhere. Also make sure you have docker and docker-compose installed.
20+
1. Make sure that you have Docker installed.
21+
22+
2. Clone this repository as well as the Django repository, e.g.
23+
24+
```console
25+
$ mkdir ~/Sources
26+
$ cd ~/Sources
27+
$ git clone https://github.com/django/django.git
28+
$ git clone https://github.com/django-docker-box/django-docker-box.git
29+
$ cd django-docker-box
30+
```
31+
32+
> [!IMPORTANT]
33+
> As long as the two repositories are adjacent the Django source repository will be discovered.
34+
> A different path can be specified by setting the `DJANGO_PATH` environment variable.
35+
36+
3. Build the image:
37+
38+
```console
39+
$ docker compose build sqlite
40+
```
41+
42+
4. Run the tests:
43+
44+
```console
45+
$ docker compose run --rm sqlite
46+
```
47+
48+
49+
## Running Tests
50+
51+
All of the test commands detailed below can be passed additional arguments that
52+
are provided to the `runtests.py` entrypoint. You can see a list of these
53+
arguments by running the following command:
54+
55+
```console
56+
$ docker compose run --rm sqlite --help
57+
```
58+
59+
### Standard Tests
60+
61+
To run the standard set of tests you can use the following commands:
62+
63+
```console
64+
$ docker compose run --rm mariadb
65+
$ docker compose run --rm mysql
66+
$ docker compose run --rm oracle
67+
$ docker compose run --rm postgres
68+
$ docker compose run --rm sqlite
69+
```
70+
71+
Each of the above commands will run the test suite for a different supported
72+
database.
73+
74+
More information about [running the unit tests][7] for Django can be found in
75+
the documentation.
76+
77+
78+
### Geospatial Tests
79+
80+
To run tests on geospatial features you can use the following commands:
881

9-
Ensure that the `DJANGO_PATH` variable points to the root of the Django repo:
82+
```console
83+
$ docker compose run --rm mariadb-gis
84+
$ docker compose run --rm mysql-gis
85+
$ docker compose run --rm oracle-gis
86+
$ docker compose run --rm postgres-gis
87+
$ docker compose run --rm sqlite-gis
88+
```
1089

11-
`export DJANGO_PATH=~/projects/django/`
90+
Each of the above commands will run the test suite for a different supported
91+
geospatial database.
1292

13-
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.
93+
> [!TIP]
94+
> To only run the subset of tests for geospatial features, pass `gis_tests` as
95+
> an argument to specify that only that folder of tests should be collected,
96+
> e.g.
97+
>
98+
> ```console
99+
> $ docker compose run --rm sqlite-gis gis_tests
100+
> ```
14101
15-
You can now either download the latest image used on the CI servers with the dependencies pre-installed:
102+
More information about [running the GeoDjango tests][9] for Django can be found
103+
in the documentation.
16104
17-
`docker-compose pull sqlite`
18105
19-
Or build it yourself:
106+
### User Interface Tests
20107
21-
`docker-compose build sqlite`
108+
To run tests on user interfaces you can use the following commands:
22109
23-
Then simply run:
110+
```console
111+
$ docker compose run --rm chrome
112+
$ docker compose run --rm edge
113+
$ docker compose run --rm firefox
114+
```
24115
25-
`docker-compose run --rm sqlite`
116+
Each of the above commands will run the subset of user interface tests for a
117+
different supported web browser. The tests are executed using Selenium.
26118

27-
All arguments are passed to `runtests.py`. Before they are run all specific dependencies are
28-
installed (and cached across runs).
119+
To capture screenshots of certain test cases used for comparison to avoid
120+
regressions, the `--screenshots` flag can be passed.
29121

30-
## Different databases
122+
More information about [running the Selenium tests][8] for Django can be found
123+
in the documentation.
31124

32-
Simply substitute `sqlite` for any supported database:
33125

34-
`docker-compose run --rm postgres [args]`
126+
## Running Tools
35127

36-
`docker-compose run --rm mysql [args]`
37128

38-
`docker-compose run --rm mariadb [args]`
129+
### Linting & Formatting
39130

40-
And if you're mad you can run all the tests for all databases in parallel:
131+
Django uses the following linting and formatting tools: `black`, `flake8`,
132+
`isort`, and `eslint`. To ensure that the correct versions are used, Django
133+
also supports using `pre-commit` which is the mechanism provided here:
41134

42-
`docker-compose up`
135+
```console
136+
$ docker compose run --rm pre-commit
137+
```
43138

44-
#### Database versions
139+
You can run individual tools by passing them as an argument:
45140

46-
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.
141+
```console
142+
$ docker compose run --rm pre-commit black
143+
$ docker compose run --rm pre-commit blacken-docs
144+
$ docker compose run --rm pre-commit isort
145+
$ docker compose run --rm pre-commit flake8
146+
$ docker compose run --rm pre-commit eslint # XXX: Currently not working.
147+
```
47148

48-
## Different Python versions
149+
More information about Django's [coding style][5] can be found in the
150+
documentation.
49151

50-
The `PYTHON_VERSION` environment variable customizes which version of Python you are running the tests against. e.g:
152+
### Building Documentation
51153

52-
`PYTHON_VERSION=3.10 docker-compose run --rm sqlite`
154+
Documentation for Django is built using Sphinx. Run the following to see the
155+
available commands:
53156

54-
You can also pull the pre-built image in the same way:
157+
```console
158+
$ docker compose run --rm sphinx
159+
```
55160

56-
`PYTHON_VERSION=3.10 docker-compose pull sqlite`
161+
You may find the following builders particularly useful when working on
162+
documentation improvements:
57163

58-
## Utilities
164+
```console
165+
$ docker compose run --rm sphinx dirhtml
166+
$ docker compose run --rm sphinx spelling
167+
$ docker compose run --rm sphinx linkcheck
168+
```
59169

60-
To run the docs spellchecker:
170+
The `BUILDDIR` environment variable has been set to generate output into the
171+
`./output/docs` path under this repository instead of the usual location in the
172+
Django source repository. You can alter this environment variable to generate
173+
to a different path if required.
61174

62-
`docker-compose run --rm docs`
175+
More information about [writing documentation][6] for Django can be found in
176+
the documentation.
63177

64-
Or pre-commit:
65178

66-
`docker-compose run --rm pre-commit`
179+
### Other
67180

68-
To enter a bash shell within the container, run:
181+
To enter a shell within the container, run:
69182

70-
`docker-compose run --rm --entrypoint bash [database]`
183+
```console
184+
$ docker compose run --rm --entrypoint=bash sqlite
185+
```
71186

72187
## Configuration
73188

74-
| Environment Variable | Default | Description |
75-
| --- | --- | --- |
76-
| `DJANGO_PATH` | `../django` | The path to the Django codebase on your local machine |
77-
| `PYTHON_IMPLEMENTATION` | `python` | One of `python` or `pypy` |
78-
| `PYTHON_VERSION` | `3.10` | The python version to run tests against |
79-
| `POSTGRESQL_VERSION` | `13` | The version of Postgres to use |
80-
| `MYSQL_VERSION` | `8` | The mysql version to use |
81-
| `MARIADB_VERSION` | `10.5` | The mariadb version to use |
82-
| `ORACLE_VERSION` | `23.5.0.0` | The Oracle version to use |
189+
The build of the container image can be customized by setting the following
190+
environment variables:
191+
192+
| Environment Variable | Default Value | Description |
193+
| ----------------------- | ------------- | ---------------------------------------------------- |
194+
| `DJANGO_PATH` | `../django` | Path to the Django repostory on your local machine |
195+
| `PYTHON_IMPLEMENTATION` | `python` | Implementation of Python to use — `python` or `pypy` |
196+
| `PYTHON_VERSION` | `3.10` | Version of Python container image to use |
197+
198+
The versions of various backend services can be switched by setting these environment variables:
199+
200+
| Environment Variable | Default Value | Description |
201+
| ----------------------- | ------------- | ---------------------------------------------------- |
202+
| `MARIADB_VERSION` | `10.5` | Version of MariaDB container image to use |
203+
| `MYSQL_VERSION` | `8.0` | Version of MySQL container image to use |
204+
| `ORACLE_VERSION` | `23.5.0.0` | Version of Oracle container image to use |
205+
| `POSTGRESQL_VERSION` | `14` | Version of PostgreSQL container image to use |
206+
| `POSTGIS_VERSION` | `3.1` | Version of PostGIS extension to use |
207+
208+
209+
### Python Versions
210+
211+
The `PYTHON_VERSION` environment variable controls which version of Python you
212+
are running the tests against, e.g.
213+
214+
```console
215+
$ PYTHON_VERSION=3.10 docker compose run --rm sqlite
216+
```
217+
218+
In addition, it's possible to select a different implementation of Python, i.e.
219+
PyPy instead of CPython, by setting the `PYTHON_IMPLEMENTATION` environment
220+
variable, e.g.
221+
222+
```console
223+
$ PYTHON_IMPLEMENTATION=pypy docker compose run --rm sqlite
224+
```
225+
226+
Be warned, however, that support for PyPy is not as complete and there are more
227+
restrictions with respect to the range of versions available.
228+
229+
### Database Versions
230+
231+
Most database container images are pulled from [Docker Hub][2]. Oracle database
232+
is pulled from the [Oracle Container Registry][3].
233+
234+
You can switch the version of the database you test against by changing the
235+
appropriate environment variable. Available options and their defaults can be
236+
found in the [configuration section](#Configuration).
237+
238+
> [!WARNING]
239+
> Be aware that only a single version of a particular database may be running
240+
> at one time, so you will need to ensure that you tear down the previously
241+
> running instance before starting up the new one, e.g.
242+
>
243+
> ```console
244+
> $ docker compose ps --format='{{.Image}}' postgresql-db
245+
> postgres:13-alpine
246+
> $ docker compose down postgresql-db
247+
> [+] Running 1/1
248+
> ✔ Container django-docker-box-postgresql-db-1 Removed 0.2s
249+
> $ POSTGRESQL_VERSION=17 docker compose up --detach postgresql-db
250+
> [+] Running 1/1
251+
> ✔ Container django-docker-box-postgresql-db-1 Started 0.3s
252+
> $ docker compose ps --format='{{.Image}}' postgresql-db
253+
> postgres:17-alpine
254+
> ```
255+
>
256+
> Alternatively, run the following to tear down the whole stack before bringing
257+
> up new containers running different versions:
258+
>
259+
> ```console
260+
> $ docker compose down
261+
> ```
262+
263+
> [!NOTE]
264+
>
265+
> Unlike other GIS database backends, for PostgreSQL with PostGIS you will need
266+
> to specify both versions:
267+
>
268+
> ```console
269+
> $ POSTGRESQL_VERSION=17 POSTGIS_VERSION=3.5 docker compose up --detach postgresql-gis-db
270+
> ```
271+
272+
To determine what database versions can be used you can check the release notes
273+
for the branch of Django that you have checked out, or alternatively there is
274+
the [supported database versions][4] page on Django's Trac Wiki.
275+
276+
277+
### Other Versions
278+
279+
For the Memcached, Redis, and Selenium container images, the latest container
280+
image tag is always used.
281+
282+
Where possible, for backend services, we also use Alpine images where available
283+
for smaller image size and sometimes improved performance.
284+
285+
286+
## Roadmap
287+
288+
The following list is a collection of ideas for improvements that could be made
289+
with no promises that they'll be delivered:
290+
291+
- Add a monthly scheduled full test matrix execution using GitHub Actions
292+
- Add support for some third-party databases, e.g. CockroachDB, SQL Server
293+
- Add support for test coverage execution and report generation
294+
- Add support for running accessibility tooling and report generation
295+
- Support report generation during monthly runs and publish to GitHub Pages
296+
- Publish pre-built container images to the GitHub Container Registry
297+
- Support testing against different versions of SQLite and SpatiaLite
298+
- Support running with Podman in addition to Docker
299+
- Support generating screenshots into `./output/screenshots/`
300+
301+
302+
[0]: https://www.djangoproject.com/
303+
[1]: https://www.djangoproject.com/fundraising/
304+
[2]: https://hub.docker.com/search?badges=official&badges=open_source
305+
[3]: https://container-registry.oracle.com/ords/ocr/ba/database/free
306+
[4]: https://code.djangoproject.com/wiki/SupportedDatabaseVersions
307+
[5]: https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/coding-style/
308+
[6]: https://docs.djangoproject.com/en/stable/internals/contributing/writing-documentation/
309+
[7]: https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/unit-tests/#running-the-unit-tests
310+
[8]: https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/unit-tests/#running-the-selenium-tests
311+
[9]: https://docs.djangoproject.com/en/stable/ref/contrib/gis/testing/#geodjango-tests

0 commit comments

Comments
 (0)