This chapter helps you get an installation of Kitsune up and running.
If you have any problems getting Kitsune running, let us know. See Contact us.
Getting up and running¶
Fork this repository & clone it to your local machine.
git clone https://github.com/mozilla/kitsune.git
Pull base Kitsune Docker images, run
collectstatic, create your database, and install node packages.
make init make build
If you have low bandwidth, you may get a timeout error, see issue#4511 for more information. You can change default pip’s timeout value (which is 60 seconds) by running:
make build PIP_TIMEOUT=300
In above command, we are setting default value of PIP_DEFAULT_TIMEOUT to 5 minutes, change it according to your need.
This will produce a lot of output (mostly warnings at present). When you see the following the server will be ready:
web_1 | Starting development server at http://0.0.0.0:8000/ web_1 | Quit the server with CONTROL-C.
The running instance will be located at http://localhost:8000/ unless you specified otherwise, and the administrative control panel will be at http://localhost:8000/admin/.
Another way you might choose to run the app (step 3 above) is by getting a shell in the container and then manually running the Django dev server from there. This should make frequent restarts of the server a lot faster and easier if you need to do that:
make runshell bin/run-dev.sh
The end result of this method should be the same as using
make run, but will potentially aid in debugging
and act much more like developing without Docker as you may be used to. You should use
make runshell here
make shell as the latter does not bind port 8000 which you need to be able to load the site.
make help to see other helpful commands.
Finally you can run the development server with instance reloading through browser-sync.
The running instance in this case will be located at http://localhost:3000/.
After the above you can do some optional steps if you want to use the admin:
Enable the admin control panel
echo "ENABLE_ADMIN=True" >> .env
Create a superuser
docker-compose exec web ./manage.py createsuperuser
Create a profile for this user
$ ./manage.py shell_plus In : u = User.objects.get(username="superuser") In : Profile(user=u).save()
Log in to the admin panel: http://localhost:8000/admin
Install Sample Data¶
We include some sample data to get you started. You can install it by running this command:
docker-compose exec web ./manage.py generatedata
Get AAQ working¶
Add a product with a slug matching one of the product values in
kitsune/questions/config.py. You can do this through the admin interface at
For instance, with a
... "name": _lazy("Firefox"), "product": "firefox", ...
Create a product in the admin interface with its
Add a topic matching a category from that product config, and associate it with the product you just created. You can do this through the admin interface at
For instance, with a category with a
... "topic": "download-and-install", ...
Create a topic in the admin interface with its
download-and-installand its product set to the product you just created.
Finally add an AAQ locale for that product. You can do this through the admin interface at
Get search working¶
First, make sure you have run the “Install Sample Data” step above, or have entered data yourself through the admin interface.
Enter into the web container
docker-compose exec web bash
Build the indicies
$ ./manage.py esreindex
(You may need to pass the
Precompile the nunjucks templates
$ ./manage.py nunjucks_precompile
Now, exit from web’s bash shell
If after running these commands, search doesn’t seem to be working, make sure you’re not running any ad-blocking extensions in your browser. They may be blocking the analytics.js script which search depends on.
Install linting tools¶
Kitsune uses pre-commit for linting. Install it globally, or in a venv, outside of the docker container with:
$ pip install pre-commit
Then set up its git pre-commit hook:
$ pre-commit install
After this, every time you commit, pre-commit will check your changes for style problems. To run it manually you can use the command:
$ pre-commit run
which will run the checks for only your changes, or if you want to run the lint checks for all files:
$ pre-commit run --all-files
For more details see the pre-commit docs.
Product Details Initialization¶
One of the packages Kitsune uses,
product_details, needs to fetch
JSON files containing historical Firefox version data and write them
within its package directory. To set this up, run this command to do
the initial fetch:
docker-compose exec web ./manage.py update_product_details
We use nunjucks to render Jinja-style templates for front-end use. These templates get updated from time to time and you will need to pre-compile them to ensure that they render correctly:
docker-compose exec web ./manage.py nunjucks_precompile
Using Django Debug Toolbar¶
Django Debug Toolbar provides some very useful information when debugging various things in Django, especially slow running SQL queries.
To enable it, ensure
USE_DEBUG_TOOLBAR are enabled in
If you are using it to debug slow running SQL queries,
you may want to disable the MariaDB query cache.
Do that by adding the following lines under the
services.mariadb.entrypoint key in
- --query-cache-type=0 - --query-cache-size=0
And restart the database:
docker-compose restart mariadb