Installation¶
Kuma uses Docker for local development and integration testing, and we are transitioning to Docker containers for deployment as well.
Docker setup¶
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.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:
cd kuma
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
toUID=1000
) to avoid file permission issues when mixingdocker-compose
anddocker
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.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 thepull
command 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 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.