Installation

Kuma uses Docker for local development and integration testing, and we are transitioning to Docker containers for deployment as well.

Docker setup

  1. 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 sudo visit using docker as non-root user.

  2. 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.

  3. Ensure you are in the existing or newly cloned kuma working copy:

    cd kuma

  4. Initialize and customize .env:

    cp .env-dist.dev .env
vim .env  # Or your favorite editor

    Linux users should set the UID parameter in .env (i.e. change #UID=1000 to UID=1000) to avoid file permission issues when mixing docker-compose and docker commands. 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.

  5. Pull the Docker images and build the containers:

    docker-compose pull
docker-compose build

    (The build command is effectively a no-op at this point because the pull command just downloaded pre-built docker images.)

  6. 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 createsuperuser:

docker-compose exec web ./manage.py createsuperuser

This will prompt you for a username, email address (a fake address like admin@example.com 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:

docker-compose stop

If you have made changes to the .env or /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.