{"id":15180506,"url":"https://github.com/django/django-box","last_synced_at":"2025-10-01T21:31:03.406Z","repository":{"id":65977713,"uuid":"65818218","full_name":"django/django-box","owner":"django","description":"VM to run the Django test suite. ARCHIVED Please use https://github.com/django/django-docker-box","archived":true,"fork":false,"pushed_at":"2018-11-10T19:53:16.000Z","size":217,"stargazers_count":67,"open_issues_count":8,"forks_count":23,"subscribers_count":23,"default_branch":"master","last_synced_at":"2024-09-28T16:21:26.451Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"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":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-08-16T12:26:29.000Z","updated_at":"2024-08-02T02:20:31.000Z","dependencies_parsed_at":"2023-02-19T18:45:48.809Z","dependency_job_id":null,"html_url":"https://github.com/django/django-box","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/django%2Fdjango-box","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/django%2Fdjango-box/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/django%2Fdjango-box/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/django%2Fdjango-box/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/django","download_url":"https://codeload.github.com/django/django-box/tar.gz/refs/heads/master","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-27T16:21:25.774Z","updated_at":"2025-10-01T21:31:03.096Z","avatar_url":"https://github.com/django.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"django-box: A virtual machine for running the Django core test suite\n====================================================================\n\nForked from djangocore-box (https://github.com/jphalip/djangocore-box)\n\n**Django Version Support**: 2.1\n\n**Release**: https://app.vagrantup.com/djangoproject/boxes/django-box-2.1\n\nThe django-box is a virtual machine (VM), based on Ubuntu 16.04, containing all\nthe programs and libraries required for running the Django core test suite in\nmultiple different environments.\n\nEvery supported version of Python is pre-installed, along with all supported\ndatabase backends, except for Oracle. Third party libraries like Memcached,\nSphinx, and Pillow are also provided.\n\nThis is particularly useful to anybody interested in contributing to Django\ncore without having to go through the trouble of installing and configuring all\nthe software required to run the tests in all these environments.\n\nPreparation\n-----------\n\n### Software installation\n\nFirst of all, you need to install the latest versions of\n[Vagrant](https://www.vagrantup.com/downloads.html) (at version 2.0.1 as of\nnow) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads) (currently at\nversion 5.2.4) on your host machine.\n\nIf you use Linux, you'll need to ensure proper support for NFS installed so the\nVagrant shared folders feature works. On Debian/ubuntu systems this can be\nachieved with:\n\n    $ sudo apt-get install nfs-kernel-server\n\nOn Fedora/CentOS systems you'll need to execute something like:\n\n    $ sudo dnf install nfs-utils \u0026\u0026 sudo systemctl enable nfs-server\n\nIf you use a version of VirtualBox that isn't 5.2.4 you may run into problems\ncreating the NFS mount. You can either\n\n* Upgrade to VirtualBox 5.2.4\n* Or you can try to install the [vagrant-vbguest](https://github.com/dotless-de/vagrant-vbguest)\n  plugin, which will attempt to install your local version of GuestAdditions\n  into the VM:\n\n      vagrant plugin install vagrant-share\n      vagrant plugin install vagrant-vbguest\n\nBooting the VM\n--------------\n\n_Legend:_ `(host)` is for commands to run on the host machine, and `(vm)` is\nfor commands to run inside the VM.\n\nSetup the initial directory layout:\n\n    (host) $ cd projects\n    (host) $ git clone git@github.com:django/django.git\n    (host) $ git clone git@github.com:django/django-box.git\n\nIt's important that django is cloned to a directory called `django` directly\nbeside the `django-box` directory. This is because the virtual machine will\nmount `../django/`.\n\nThen, either:\n\n* If you have not already downloaded the box file separately, then run the\n  following commands to boot the machine.\n\n        (host) $ cd django-box\n        (host) $ vagrant up\n\n  This will automatically download the VM, which is about _1.2GB_ in size (be\n  warned if you have a low bandwitdh Internet connection) and then boot it up.\n  The download will only occur the first time you run `vagrant up`, as the image\n  is saved.\n\n* Or, if you have already downloaded the box file separately, then run the\n  following command in order to import the box into vagrant and boot up the VM:\n\n        (host) $ vagrant box add path/to/django-box-2.1.box --name djangoproject/django-box-2.1\n        (host) $ cd django-box\n        (host) $ vagrant up\n\n  `vagrant box add` will copy the box file to `~/.vagrant.d/boxes`, so you may\n  delete the file you've dowloaded if you'd like to save some space on your\n  hard drive.\n\n  You can download the box file directly from (make sure you update the version\n  component):\n  https://app.vagrantup.com/djangoproject/boxes/django-box-2.1/versions/1.0.0/providers/\n\n  You can check what the latest released version is here:\n  https://app.vagrantup.com/djangoproject/boxes/django-box-2.1/\n\nAs the VM boots up, it will prompt you to enter your host machine's\nadministrator password (the same that you use for logging into your host\nmachine). This is required so that Vagrant can setup the NFS shared folders.\n\nOnce the VM is up and running, type the following command to SSH into the VM\n(still from inside the `django-box/` folder):\n\n    (host) $ vagrant ssh\n\nOnce inside the VM, you can run the tests by typing any of the pre-defined\naliases. For example:\n\n    (vm) $ runtests36-mysql\n    (vm) $ runtests35-spatialite gis_tests\n    (vm) $ runtests35-postgres admin_widgets --selenium chrome\n\nSupported commands\n------------------\n\n```\nruntests-isort    runtests35-sqlite3        runtests36-sqlite3\nruntests-flake8   runtests35-spatialite     runtests36-spatialite\nruntests-docs     runtests35-mysql          runtests36-mysql\n                  runtests35-mysql_gis      runtests36-mysql_gis\n                  runtests35-postgres       runtests36-postgres\n                  runtests35-postgis        runtests36-postgis\n```\n\nSome of these names have changed in version 2.1 of django-box. Now they\nmirror the naming convention used in our Jenkins CI setup. i.e.\n`runtests3x-sqlite3-gis` is now `runtests3x-spatialite`,\n`runtest3x-postgres-gis` is now `runtests3x-postgis` and\n`runtest3x-mysql-gis` is now `runtests3x-mysql_gis`.\n\nExamples\n--------\n\nThe commands above that target databases all accept arguments and flags\nconsistent with the unit-tests documentation: https://docs.djangoproject.com/en/dev/internals/contributing/writing-code/unit-tests/\nWhat this means is that you can still run these tests with `--keepdb` to improve\ntesting performance, and target specific test modules.\n\n```bash\n# Run test modules related to expressions\nruntests35-postgres --keepdb -v 2 queries expressions lookup aggregation annotations\n\n# Run GIS tests\nruntests35-postgis gis_tests\n\n# Run selenium tests against chrome driver (no firefox available yet)\nruntests36-sqlite3 admin_widgets --selenium chrome --parallel 1\n```\n\n\nNotes about the VM configuration\n--------------------------------\n\nInside the VM, the `/django` folder is shared with the host and points to the\ngit clone that was created in the steps above. This way you can edit Django's\ncode using your favorite editor from your host machine and run the tests from\ninside the VM. The repository clone for the django-box itself is also in a\nshared folder at `/vagrant`.\n\nThe test settings are available in `/home/vagrant/djangodata/test_*.py`. These\nfiles are put onto the `PYTHONPATH` when running the tests.\n\nChrome is pre-installed so that Django's selenium tests can be run in headless\nmode with a virtual display (id `:99`). For example, you may run a specific test\nlike so:\n\n    (vm) $ runtests36-sqlite3 admin_widgets --selenium chrome --parallel 1\n\nThe test suite will sometimes hang when running selenium tests in parallel mode.\n\nTroubleshooting\n---------------\n\n### Strange errors when running tests\n\nThe `tox.ini` configuration file shipped with the Django source code directs\ntox to create the virtual environments it uses for every test matrix\nconfiguration below a `.tox` directory it creates on the Django source code top\ndirectory.\n\ndjango-box reuses Django's tox configuration, but executes tox inside the VM,\nso that `.tox/` tree gets persisted between test runs and shared between a tox\ncopy you could use on the host and the django-box tox.\n\nSo it might happen than when faced with a mismatch between the version of Python\nused to create a virtual environment and the version currently in use to run\nthe tests (e.g. Python micro version gets upgraded from 3.6.3 to 3.6.4 and this\nupgrade reaches your Linux host and/or the repositories used by the django-box\nVM), weird errors happen.\n\nYou can solve this by removing the virtualenv tree, e.g.:\n\n    (host) $ rm -rf \u003cDjango souce code top dir\u003e/.tox/py36-mysql\n    (vm) $ rm -rf /django/.tox/py36-mysql\n\nor more drastically, removing the `.tox` directory:\n\n    (host) $ rm -rf \u003cDjango souce code top dir\u003e/.tox\n    (vm) $ rm -rf /django/.tox\n\nThis way the next time you run the tests, tox will rebuild the virtual\nenvironment anew with the correct version of Python.\n\nBuilding the documentation\n--------------------------\n\nTo build the documentation, change to the docs directory and call a make task:\n\n\n    (vm) $ cd /django/docs\n    (vm) $ make html\n\nYou can then view the docs in your browser on the host:\n\n    `(host) $ open django/docs/_build/html/index.html`\n\nVagrant command tips\n--------------------\n\n- To exit the VM and return to your host machine, simple type:\n\n    `(vm) $ exit`\n\n- To shutdown the VM, type:\n\n    `(host) $ vagrant halt`\n\n- To suspend the VM (i.e. freeze the VM's state), type:\n\n    `(host) $ vagrant suspend`\n\n- Once shutdown or suspended, a VM can be restarted with:\n\n    `(host) $ vagrant up`\n\n- To destroy the VM, simply type:\n\n    `(host) $ vagrant destroy`\n\n- To check if the VM is currently running, type:\n\n    `(host) $ vagrant status`\n\n- To re-run the provisioning after the VM has been started (if you have built\n  the VM from scratch):\n\n    `(host) $ vagrant provision`\n\n- More information is available in the [Vagrant documentation](https://www.vagrantup.com/docs/).\n\nBuilding a new version\n----------------------\n\nTo upgrade or alter the original box, you'll need to recreate it. You'll need to\nhave Ansible 2.1 or greater installed, and django \u003e= 2.1 in a folder beside the\ndjango-box project as described above. You should also have\nthe [vagrant-vbguest](https://github.com/dotless-de/vagrant-vbguest) plugin\ninstalled to ensure the correct GuestAdditions are configured within the image.\n\nMake any required changes to the Ansible roles, and then create the box with:\n\n    (host) $ VAGRANT_VAGRANTFILE=Vagrantfile-build vagrant up\n\nThe automatic build process will take about 20 minutes. If the new build should\nbe saved, then you can package the output:\n\n    (host) $ VAGRANT_VAGRANTFILE=Vagrantfile-build vagrant package \\\n            --output django-box-2.1.box\n\n    (host) $ vagrant box add django-box-2.1.box --name djangoproject/django-box-2.1 # optional - for testing\n\nNote that compiling a new version should only be required when releasing a new\nbuild to app.vagrantup.com.\n\nTo upload the new image, logon to the `djangoproject` account on vagrantup\nhere: https://app.vagrantup.com/djangoproject.\n\n- Click through to the box you're updating\n- Create a new version, bumping the release version, and adding release notes\n- Create a new virtualbox provider for the new version\n- Upload the .box file generated from the packaging command above\n\nCredits\n-------\n\ndjango-box was originally authored by [Julien Phalip](https://twitter.com/julienphalip)\nand [other contributors](AUTHORS) as djangocore-box.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjango%2Fdjango-box","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjango%2Fdjango-box","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjango%2Fdjango-box/lists"}