Kuma uses Docker for local development and integration testing, and we are transitioning to Docker containers for deployment as well.
Current Status of Dockerization:
- Kuma developers are using Docker for daily development and maintenance tasks. Staff developers primarily use Docker for Mac. Other staff members and contributors use Docker's Ubuntu packages.
- The development environment can use a lot of resources. On Docker for Mac, the environment runs well with 6 CPUs and 10 GB of memory dedicated to Docker. It can be run successfully on 2 CPUs and 2 GB of memory.
- The Docker development environment is evolving rapidly, to address issues found during development and to move toward a containerized design. You may need to regularly reset your environment to get the current changes.
- The Docker development environment doesn't fully support a 'production-like' environment. For example, we don't have a documented configuration for running with an SSL connection.
- When the master branch is updated, the
kuma_baseimage is refreshed and published to quay.io. This image contains system packages and third-party libraries.
- Our TravisCI builds include a target that build Docker containers and runs the tests inside.
- Our Jenkins server builds and publishes Docker images, and runs integration tests using Docker.
- We are documenting tips and tricks on the :doc:`Troubleshooting page <troubleshooting>`.
- Feel free to ask for help on IRC at
#mdndevor on discourse.
Install the Docker platform, following Docker's instructions for your operating system, such as Docker for Mac for MacOS, or for your Linux distribution. Linux users will also want to install Docker Compose and follow post-install instructions to confirm that the development user can run Docker commmands.
To confirm that Docker is installed correctly, run:
docker run hello-world
If you find any error using docker commands without
sudovisit using docker as non-root user.
Clone the kuma Git repository, if you haven't already:
git clone --recursive https://github.com/mozilla/kuma.git
Ensure you are in the existing or newly cloned kuma working copy:
Initialize and customize
.env. Linux users should set the
UID=1000) to avoid file permission issues when mixing
cp .env-dist.dev .env vim .env # Or your favorite editor
Pull the Docker images and build the containers:
docker-compose pull docker-compose build
Start the containers in the background:
docker-compose up -d
The following instructions assume that you are running from a folder named
kuma, so that the containers created are named
kuma_worker_1, etc. If you run from another folder, like
containers will be named
mdn_worker_1, etc. Adjust the
command accordingly, or force the
kuma name with:
docker-compose up -d -p kuma
Load the Sample Database
Download and load the sample database:
wget -N https://mdn-downloads.s3-us-west-2.amazonaws.com/mdn_sample_db.sql.gz docker exec -i kuma_web_1 bash -c "zcat | ./manage.py dbshell" < mdn_sample_db.sql.gz
Alternatively, you can use
curl (installed by default on macOS):
curl -O https://mdn-downloads.s3-us-west-2.amazonaws.com/mdn_sample_db.sql.gz docker exec -i kuma_web_1 bash -c "zcat | ./manage.py dbshell" < mdn_sample_db.sql.gz
It takes a few seconds to load, with this expected output:
mysql: [Warning] Using a password on the command line interface can be insecure.
This command can be adjusted to restore from an uncompressed database, or
directly from a
Then run the following command:
docker-compose exec web ./manage.py migrate
This will ensure the sample database is in sync with your version of Kuma.
Localized string databases are included in their source form, and need to be compiled to their binary form:
docker exec -i kuma_web_1 make localecompile
Dozens of lines of warnings will be printed:
Warnings are OK, and will be fixed as translators update the strings on Pontoon. If there is an error, the output will end with the error, such as:
./az/LC_MESSAGES/django.po:263: 'msgid' and 'msgstr' entries do not both end with '\n' msgfmt: found 1 fatal error
These need to be fixed by a Kuma developer. Notify them in the #mdndev IRC channel or open a bug. You can continue with installation, but non-English locales will not be localized.
Generate static assets
Static assets such as CSS and JS are included in source form, and need to be compiled to their final form:
docker exec -i kuma_web_1 make build-static
A few thousand lines will be printed, like:
Visit the Homepage
Open the homepage at http://localhost:8000 . You've installed Kuma!
Prepare for Front-end Development
When doing front-end development on your local machine, you'll probably
want to run
gulp, to rebuild front-end assets as they edited, rather than
make build-static after each change.
First, install Node.js v6, using the install instructions for your OS.
Next, from the root directory of your Kuma repository, install
Now, you can run
gulp (probably from its own shell):
Alternatively, you can install
sudo npm install -g
And then run
gulp more simply:
Create an admin user
Many Kuma settings require access to the Django admin, including configuring social login. It is useful to create an admin account with password access for local development.
If you want to create a new admin account, use
docker exec -it kuma_web_1 ./manage.py createsuperuser
This will prompt you for a username, email address (a fake address like
firstname.lastname@example.org will work), and a password.
If your database has an existing account that you want to use, run the
management command. Replace
YOUR_USERNAME with your username and
YOUR_PASSWORD with your password:
docker-compose run --rm web ./manage.py ihavepower YOUR_USERNAME \ --password YOUR_PASSWORD
With a password-enabled admin account, you can log into Django admin at http://localhost:8000/admin/login/
Enable GitHub Auth (optional)
To enable GitHub authentication, you'll need to register an OAuth application on GitHub, with settings like:
- Application name: MDN Development for (<username>).
- Homepage URL: http://localhost:8000/.
- Application description: My own GitHub app for MDN!
- Authorization callback URL: http://localhost:8000/users/github/login/callback/.
As an admin user, add a django-allauth social app for GitHub:
- Provider: GitHub.
- Name: MDN Development.
- Client id: <your GitHub App Client ID>.
- Secret key: <your GitHub App Client Secret>.
- Sites: Move
example.comfrom "Available sites" to "Chosen sites".
Now you can sign in with GitHub.
To associate your password-only admin account with GitHub:
- Login with your password at http://localhost:8000/admin/login/.
- Go to the Homepage at https://developer.mozilla.org/en-US/.
- Click your username at the top to view your profile.
- Click Edit to edit your profile.
- Under My Profiles, click Use your GitHub account to sign in.
To create a new account with GitHub, use the regular "Sign in" widget at the top of any page.
With social accounts are enabled, you can disable the admin password in the Django shell:
docker exec -it kuma_web_1 ./manage.py shell_plus >>> me = User.objects.get(username='admin_username') >>> me.set_unusable_password() >>> me.save() >>> exit()
Interact with the Docker containers
The current directory is mounted as the
/app folder in the web and worker
kuma_worker_1). Changes made to your local
directory are usually reflected in the running containers. To force the issue,
the container can be restarted:
docker restart kuma_web_1 kuma_worker_1
You can connect to a running container to run commands. For example, you can open an interactive shell in the web container:
docker exec -it kuma_web_1 /bin/bash make bash # Same command, less typing
To view the logs generated by a container:
docker logs kuma_web_1
To continuously view logs from all containers:
docker-compose logs -f
To stop the containers:
For further information, see the Docker documentation, such as the Docker Overview and the documentation for your operating system. You can try Docker's guided tutorials, and apply what you've learned on the Kuma Docker environment.