Pick an environment¶
There are two development environments, and you need to install at least one of them first.
- The Docker containerized environment is the preferred development environment. The Docker images are already provisioned, so setup is faster. It is a better model for the production environment, and after the planned rehost will be almost exactly the same. It does not yet have all of the features of the Vagrant environment, and it is currently slower for many development tasks.
- The Vagrant-managed VM is the mature but deprecated development environment. It can be tricky to provision. It is often a poor model for the production environment, and can not be used to test infrastructure changes.
Docker and Vagrant can be used at the same time on the same “host machine” (your laptop or desktop computer).
Basic Docker usage¶
Edit files as usual on your host machine; the current directory is mounted
via Docker host mounting at
/app within the
other containers. Useful docker sub-commands:
docker exec -it kuma_web_1 bash # Start an interactive shell docker logs kuma_web_1 # View logs from the web container docker-compose logs -f # Continuously view logs from all containers docker restart kuma_web_1 # Force a container to reload docker-compose stop # Shutdown the containers docker-compose up -d # Start the containers docker-compose rm # Destroy the containers
make shortcuts on the host for frequent commands, such as:
make up # docker-compose up -d make bash # docker exec -it kuma_web_1 bash make shell_plus # docker exec -it kuma_web_1 ./manage.py shell_plus
Run all commands in this doc in the
kuma_web_1 container after
Basic Vagrant usage¶
Edit files as usual on your host machine; the current directory is
mounted via NFS at
/home/vagrant/src within the VM. Updates should be
reflected without any action on your part. Useful vagrant sub-commands:
vagrant ssh # Connect to the VM via ssh vagrant suspend # Sleep the VM, saving state vagrant halt # Shutdown the VM vagrant up # Boot up the VM vagrant destroy # Destroy the VM
Run all commands in this doc on the VM after
When the Docker container environment is started (
make up or similar), all
of the services are also started. The development instance is available at
The Vagrant environment runs everything in a single VM. It runs MySQL,
ElasticSearch, Apache, and other “backend” services whenever the VM is running.
There are additional Kuma-specific services that are configured in
Procfile, and are run with:
The Vagrant development instance is then available at https://developer-local.allizom.org.
Running the tests¶
One way to confirm that everything is working, or to pinpoint what is broken, is to run the test suite.
Run the Django test suite:
For more information, see the test documentation.
Front-end Development and Compiling Sass files¶
Sass files need to be compiled for changes to take effect, but don’t worry, the compilation is done automatically by Django (specifically django-pipeline).
When doing front-end development on your local machine, you’ll probably want to run (most likely in its own shell):
within the root directory of your local Kuma epository. It will watch for
changes to any source files under
./kuma/static and move any changed files
./static, where they will be compiled on-demand (i.e., when requested by
a loading page). If you haven’t already installed Node.js and gulp on
your local machine, see Prepare for Front-end Development.
DEBUG = True in
docker-compose.yml, and in that mode, as
mentioned above, source files are compiled on-demand. If for some reason you
want to run with
DEBUG = False, just remember that source files will no
longer be compiled on-demand. Instead, after every change to one or more source
files, you’ll have to do the following:
docker-compose exec web make collectstatic docker-compose restart web
in order for your changes to be visible.
Apps are migrated using Django’s migration system. To run the migrations:
If your changes include schema modifications, see the Django documentation for the migration workflow.
See CONTRIBUTING.md for details of the coding style on Kuma.
New code is expected to have test coverage. See the Test Suite docs for tips on writing tests.
Front-end dependencies are managed by Bower and checked into the repository. Follow these steps to add or upgrade a dependency:
- On the host, update
- (Docker only) In the container, install
apt-get install -y git).
- (Docker only) In the container, install
npm install -g bower-installer).
- In the VM or container, install the dependency (
- On the host, prepare the dependency to be committed (
git add path/to/dependency).
Front-end dependencies that are not already managed by Bower should begin using this approach the next time they’re upgraded.
Environment variables are used to change the way different components work. There are a few ways to change an environment variables:
Exporting in the shell, such as:
export DEBUG=True; ./manage.py runserver
A one-time override, such as:
DEBUG=True ./manage.py runserver
.envfile in the repository root directory.
One variable you may wish to alter for local development is
which, when set to
True, will enable the Django Debug Toolbar:
Note that enabling the Debug Toolbar can severely impact response time, adding around 4 seconds to page load time.
The Docker environment¶
Running docker-compose will create and run several containers, and each
container’s environment and settings are configured in
The settings are “baked” into the containers created by
To override a container’s settings for development, use a local override file.
For example, the
web service runs in container
kuma_web_1 with the
gunicorn -w 4 --bind 0.0.0.0:8000 --timeout=120 kuma.wsgi:application”.
A useful alternative for debugging is to run a single-threaded process that
loads the Werkzeug debugger on exceptions (see docs for runserver_plus), and
that allows for stepping through the code with a debugger.
To use this alternative, create an override file
version: "2" services: web: command: ./manage.py runserver_plus 0.0.0.0:8000 stdin_open: true tty: true
This is similar to “
docker run -it <image> ./manage.py runserver_plus”,
using all the other configuration items in
Apply the custom setting with:
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
You can then add
pdb breakpoints to the code
import pdb; pdb.set_trace) and connect to the debugger with:
docker attach kuma_web_1
To always include the override compose file, add it to your
A similar method can be used to override environment variables in containers, run additional services, or make other changes. See the docker-compose documentation for more ideas on customizing the Docker environment.
The Vagrant environment¶
It is easiest to configure Vagrant with a
.env file, so that overrides are used
vagrant up is called. A sample
.env could contain:
VAGRANT_MEMORY_SIZE=4096 VAGRANT_CPU_CORES=4 # Comments are OK, for documentation and to disable settings # VAGRANT_ANSIBLE_VERBOSE=true
Configuration variables that are available for Vagrant:
false) Whether or not to use NFS for the synced folder.
The size of the Virtualbox VM memory in MB. Default:
The number of virtual CPU core the Virtualbox VM should have. Default:
The static IP the Virtualbox VM should be assigned to. Default:
Whether the Virtualbox VM should boot with a GUI. Default:
Whether the Ansible provisioner should print verbose output. Default:
Whether to use the
vagrant-cachierplugin to cache system packages between installs. Default:
The database connection is defined by the environment variable
DATABASE_URL, with these defaults:
DATABASE_URL=mysql://kuma:kuma@localhost:3306/kuma # Vagrant DATABASE_URL=mysql://root:kuma@mysql:3306/developer_mozilla_org # Docker
The format is defined by the dj-database-url project:
If you configure a new database, override
DATABASE_URL to connect to it. To
add an empty schema to a freshly created database:
To connect to the database specified in
Kuma will automatically run in debug mode, with the
DEBUG setting turned to
DEBUG=False will put you in production mode and
generate/use minified (compressed) and versioned (hashed) assets. To
emulate production, and test compressed and hashed assets locally:
- Set the environment variable
- Start (
docker-compose up -d) or restart (``docker-compose restart`) your Docker services.
docker-compose exec web make build-static.
- Restart the web process using
docker-compose restart web.
Deis Workflow Demo instances¶
You can deploy a hosted demo instance of Kuma by following these steps:
Create a new branch, you cannot create a demo from the
from the Kuma project root directory, run the following command:
Your demo will be accessible within about 10 minutes at:
Mozilla SRE’s will periodically remove old instances