{"id":14972578,"url":"https://github.com/django/django-docker-box","last_synced_at":"2025-10-01T21:30:58.690Z","repository":{"id":41273287,"uuid":"188831859","full_name":"django/django-docker-box","owner":"django","description":"Run the Django test suite across all supported databases and python versions","archived":false,"fork":true,"pushed_at":"2025-01-07T16:01:16.000Z","size":169,"stargazers_count":120,"open_issues_count":5,"forks_count":38,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-01-07T17:19:01.981Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"orf/django-docker-box","license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/django.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-05-27T11:38:15.000Z","updated_at":"2025-01-07T16:01:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/django/django-docker-box","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/django%2Fdjango-docker-box","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/django%2Fdjango-docker-box/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/django%2Fdjango-docker-box/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/django%2Fdjango-docker-box/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/django","download_url":"https://codeload.github.com/django/django-docker-box/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":234902725,"owners_count":18904521,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T13:47:09.381Z","updated_at":"2025-10-01T21:30:58.684Z","avatar_url":"https://github.com/django.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Django Toolbox\n\nTooling and test execution support for [Django][0] :unicorn:\n\n:heart: Support Django development by [donating][1] to the Django Software Foundation.\n\n\n## Highlights\n\n- :test\\_tube: Test supported core database backends — MariaDB, MySQL, Oracle, PostgreSQL, SQLite\n- :earth\\_africa: Test supported core geospatial backends — MariaDB, MySQL, Oracle, PostGIS, SpatiaLite\n- :globe\\_with\\_meridians: Test user interfaces in different browsers using Selenium — Chrome, Edge, Firefox\n- :snake: Test using different Python interpreters — CPython, PyPy\n- :broom: Execute linting and formatting tools on the Django repository\n- :books: Build the project documentation using Sphinx and run spelling and link checkers\n\n\n## Quickstart\n\n1. Make sure that you have Docker installed.\n\n2. Clone this repository as well as the Django repository, e.g.\n\n   ```console\n   $ mkdir ~/Sources\n   $ cd ~/Sources\n   $ git clone https://github.com/django/django.git\n   $ git clone https://github.com/django/django-docker-box.git\n   $ cd django-docker-box\n   ```\n\n\u003e [!IMPORTANT]\n\u003e As long as the two repositories are adjacent the Django source repository will be discovered.\n\u003e A different path can be specified by setting the `DJANGO_PATH` environment variable.\n\n3. Build the image:\n\n   ```console\n   $ docker compose build sqlite\n   ```\n\n4. Run the tests:\n\n   ```console\n   $ docker compose run --rm sqlite\n   ```\n\n\n## Running Tests\n\nAll of the test commands detailed below can be passed additional arguments that\nare provided to the `runtests.py` entrypoint. You can see a list of these\narguments by running the following command:\n\n```console\n$ docker compose run --rm sqlite --help\n```\n\n### Standard Tests\n\nTo run the standard set of tests you can use the following commands:\n\n```console\n$ docker compose run --rm mariadb\n$ docker compose run --rm mysql\n$ docker compose run --rm oracle\n$ docker compose run --rm postgresql\n$ docker compose run --rm sqlite\n```\n\nEach of the above commands will run the test suite for a different supported\ndatabase.\n\nMore information about [running the unit tests][7] for Django can be found in\nthe documentation.\n\n\n### Geospatial Tests\n\nTo run tests on geospatial features you can use the following commands:\n\n```console\n$ docker compose run --rm mariadb-gis\n$ docker compose run --rm mysql-gis\n$ docker compose run --rm oracle-gis\n$ docker compose run --rm postgresql-gis\n$ docker compose run --rm sqlite-gis\n```\n\nEach of the above commands will run the test suite for a different supported\ngeospatial database.\n\n\u003e [!TIP]\n\u003e To only run the subset of tests for geospatial features, pass `gis_tests` as\n\u003e an argument to specify that only that folder of tests should be collected,\n\u003e e.g.\n\u003e\n\u003e ```console\n\u003e $ docker compose run --rm sqlite-gis gis_tests\n\u003e ```\n\nMore information about [running the GeoDjango tests][9] for Django can be found\nin the documentation.\n\n\n### User Interface Tests\n\nTo run tests on user interfaces you can use the following commands:\n\n```console\n$ docker compose run --rm chrome\n$ docker compose run --rm edge\n$ docker compose run --rm firefox\n```\n\nEach of the above commands will run the subset of user interface tests for a\ndifferent supported web browser. The tests are executed using Selenium.\n\nTo capture screenshots of certain test cases used for comparison to avoid\nregressions, the `--screenshots` flag can be passed.\n\nMore information about [running the Selenium tests][8] for Django can be found\nin the documentation.\n\n\n## Running Tools\n\n\n### Linting \u0026 Formatting\n\nDjango uses the following linting and formatting tools: `black`, `flake8`,\n`isort`, and `eslint`. To ensure that the correct versions are used, Django\nalso supports using `pre-commit` which is the mechanism provided here:\n\n```console\n$ docker compose run --rm pre-commit\n```\n\nYou can run individual tools by passing them as an argument:\n\n```console\n$ docker compose run --rm pre-commit black\n$ docker compose run --rm pre-commit blacken-docs\n$ docker compose run --rm pre-commit isort\n$ docker compose run --rm pre-commit flake8\n$ docker compose run --rm pre-commit eslint  # XXX: Currently not working.\n```\n\nMore information about Django's [coding style][5] can be found in the\ndocumentation.\n\n### Building Documentation\n\nDocumentation for Django is built using Sphinx. Run the following to see the\navailable commands:\n\n```console\n$ docker compose run --rm sphinx\n```\n\nYou may find the following builders particularly useful when working on\ndocumentation improvements:\n\n```console\n$ docker compose run --rm sphinx dirhtml\n$ docker compose run --rm sphinx spelling\n$ docker compose run --rm sphinx linkcheck\n```\n\nThe `BUILDDIR` environment variable has been set to generate output into the\n`./output/docs` path under this repository instead of the usual location in the\nDjango source repository. You can alter this environment variable to generate\nto a different path if required.\n\nMore information about [writing documentation][6] for Django can be found in\nthe documentation.\n\n\n### Other\n\nTo enter a shell within the container, run:\n\n```console\n$ docker compose run --rm --entrypoint=bash sqlite\n```\n\n## Configuration\n\nThe build of the container image can be customized by setting the following\nenvironment variables:\n\n| Environment Variable    | Default Value | Description                                          |\n| ----------------------- | ------------- | ---------------------------------------------------- |\n| `DJANGO_PATH`           | `../django`   | Path to the Django repostory on your local machine   |\n| `PYTHON_IMPLEMENTATION` | `python`      | Implementation of Python to use — `python` or `pypy` |\n| `PYTHON_VERSION`        | `3.12`        | Version of Python container image to use             |\n\nThe versions of various backend services can be switched by setting these environment variables:\n\n| Environment Variable    | Default Value | Description                                          |\n| ----------------------- | ------------- | ---------------------------------------------------- |\n| `MARIADB_VERSION`       | `10.6`        | Version of MariaDB container image to use            |\n| `MYSQL_VERSION`         | `8.0`         | Version of MySQL container image to use              |\n| `ORACLE_VERSION`        | `23.5.0.0`    | Version of Oracle container image to use             |\n| `POSTGRESQL_VERSION`    | `14`          | Version of PostgreSQL container image to use         |\n| `POSTGIS_VERSION`       | `3.1`         | Version of PostGIS extension to use                  |\n\n\n### Python Versions\n\nThe `PYTHON_VERSION` environment variable controls which version of Python you\nare running the tests against, e.g.\n\n```console\n$ PYTHON_VERSION=3.12 docker compose run --rm sqlite\n```\n\nIn addition, it's possible to select a different implementation of Python, i.e.\nPyPy instead of CPython, by setting the `PYTHON_IMPLEMENTATION` environment\nvariable, e.g.\n\n```console\n$ PYTHON_IMPLEMENTATION=pypy docker compose run --rm sqlite\n```\n\nBe warned, however, that support for PyPy is not as complete and there are more\nrestrictions with respect to the range of versions available.\n\n### Database Versions\n\nMost database container images are pulled from [Docker Hub][2]. Oracle database\nis pulled from the [Oracle Container Registry][3].\n\nYou can switch the version of the database you test against by changing the\nappropriate environment variable. Available options and their defaults can be\nfound in the [configuration section](#Configuration).\n\n\u003e [!WARNING]\n\u003e Be aware that only a single version of a particular database may be running\n\u003e at one time, so you will need to ensure that you tear down the previously\n\u003e running instance before starting up the new one, e.g.\n\u003e\n\u003e ```console\n\u003e $ docker compose ps --format='{{.Image}}' postgresql-db\n\u003e postgres:13-alpine\n\u003e $ docker compose down postgresql-db\n\u003e [+] Running 1/1\n\u003e  ✔ Container django-docker-box-postgresql-db-1  Removed                    0.2s\n\u003e $ POSTGRESQL_VERSION=17 docker compose up --detach postgresql-db\n\u003e [+] Running 1/1\n\u003e  ✔ Container django-docker-box-postgresql-db-1  Started                    0.3s\n\u003e $ docker compose ps --format='{{.Image}}' postgresql-db\n\u003e postgres:17-alpine\n\u003e ```\n\u003e\n\u003e Alternatively, run the following to tear down the whole stack before bringing\n\u003e up new containers running different versions:\n\u003e\n\u003e ```console\n\u003e $ docker compose down\n\u003e ```\n\n\u003e [!NOTE]\n\u003e\n\u003e Unlike other GIS database backends, for PostgreSQL with PostGIS you will need\n\u003e to specify both versions:\n\u003e\n\u003e ```console\n\u003e $ POSTGRESQL_VERSION=17 POSTGIS_VERSION=3.5 docker compose up --detach postgresql-gis-db\n\u003e ```\n\nTo determine what database versions can be used you can check the release notes\nfor the branch of Django that you have checked out, or alternatively there is\nthe [supported database versions][4] page on Django's Trac Wiki.\n\n\n### Other Versions\n\nFor the Memcached, Redis, and Selenium container images, the latest container\nimage tag is always used.\n\nWhere possible, for backend services, we also use Alpine images where available\nfor smaller image size and sometimes improved performance.\n\n\n## Roadmap\n\nThe following list is a collection of ideas for improvements that could be made\nwith no promises that they'll be delivered:\n\n- Add a monthly scheduled full test matrix execution using GitHub Actions\n- Add support for some third-party databases, e.g. CockroachDB, SQL Server\n- Add support for test coverage execution and report generation\n- Add support for running accessibility tooling and report generation\n- Support report generation during monthly runs and publish to GitHub Pages\n- Publish pre-built container images to the GitHub Container Registry\n- Support testing against different versions of SQLite and SpatiaLite\n- Support running with Podman in addition to Docker\n- Support generating screenshots into `./output/screenshots/`\n\n\n[0]: https://www.djangoproject.com/\n[1]: https://www.djangoproject.com/fundraising/\n[2]: https://hub.docker.com/search?badges=official\u0026badges=open_source\n[3]: https://container-registry.oracle.com/ords/ocr/ba/database/free\n[4]: https://code.djangoproject.com/wiki/SupportedDatabaseVersions\n[5]: https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/coding-style/\n[6]: https://docs.djangoproject.com/en/stable/internals/contributing/writing-documentation/\n[7]: https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/unit-tests/#running-the-unit-tests\n[8]: https://docs.djangoproject.com/en/stable/internals/contributing/writing-code/unit-tests/#running-the-selenium-tests\n[9]: https://docs.djangoproject.com/en/stable/ref/contrib/gis/testing/#geodjango-tests\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjango%2Fdjango-docker-box","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjango%2Fdjango-docker-box","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjango%2Fdjango-docker-box/lists"}