Kuma uses Docker for local development and integration testing, and we are transitioning to Docker containers for deployment as well.
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 https://github.com/mdn/kuma.git
If you think you might be submitting pull requests, consider forking the repository first, and then cloning your fork of it.
Ensure you are in the existing or newly cloned kuma working copy:
Initialize and customize
cp .env-dist.dev .env vim .env # Or your favorite editor
Linux users should set the
UID=1000) to avoid file permission issues when mixing
dockercommands. MacOS users do not need to change any of the defaults to get started. Note that there are settings in this file that can be useful when debugging, however.
Pull the Docker images and build the containers:
docker-compose pull docker-compose build
buildcommand is effectively a no-op at this point because the
pullcommand just downloaded pre-built docker images.)
Start the containers in the background:
docker-compose up -d
Visit the homepage¶
Open the homepage at http://localhost.org:8000 . You’ve installed Kuma!
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-compose exec web ./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.org:8000/admin/login
Interact with the Docker containers¶
The current directory is mounted as the
/app folder in the web and worker
containers. Changes made to your local
directory are usually reflected in the running containers. To force the issue,
the containers for specified services can be restarted:
docker-compose restart web worker
You can connect to a running container to run commands. For example, you can open an interactive shell in the web container:
docker-compose exec web /bin/bash make bash # Same command, less typing
To view the logs generated by a container:
docker-compose logs web
To continuously view logs from all containers:
docker-compose logs -f
To stop the containers:
If you have made changes to the
/etc/hosts file, it’s a good idea to run:
docker-compose stop docker-compose up
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.