FAQ

This page provides answers to some frequently asked questions.

How to create an extension template in my local machine

You can use the paster command in the same way as a source install. To create an extension execute the following command:

docker-compose -f docker-compose.dev.yml exec ckan-dev /bin/bash -c "paster --plugin=ckan create -t ckanext ckanext-myext -o /srv/app/src_extensions"

This will create an extension template inside the container's folder /srv/app/src_extensions which is mapped to your local src/ folder.

Now you can navigate to your local folder src/ and see the extension created by the previous command and open the project in your favorite IDE.

How to separate that extension in a new git repository so I can have the independence to install it in other instances

Crucial thing is to understand that extensions get their repositories on GitHub (or elsewhere). You can first create a repository for extension and later clone in src/ or do opposite as following:

• Create the Extension, for example: ckanext-myext.

docker-compose -f docker-compose.dev.yml exec ckan-dev /bin/bash -c "paster --plugin=ckan create -t ckanext ckanext-myext -o /srv/app/src_extensions"

• Init your new git repository into the extension folder src/ckanext-myext

cd src/ckanext-myext
git init

• Configure remote/origin

git remote add origin <remote_repository_url>

• Add your files and push the first commit

git add .
git commit -m 'Initial Commit'
git push

Note: The src/ folder is gitignored in okfn/docker-ckan repository, so initializing new git repositories inside is ok.

How to quickly refresh the changes in my extension into the dockerized environment so I can have quick feedback of my changes

This docker-compose setup for dev environment is already configured so that it sets debug=True inside configuration file and auto reloads on python and templates related changes. You do not have to reload when making changes to HTML, javascript or configuration files - you just need to refresh the page in the browser.

See the CKAN images section of the repository documentation for more detail

How to run tests for my extension in the dockerized environment so I can have a quick test-development cycle

We write and store unit tests inside the ckanext/myext/tests directory. To run unit tests you need to be running the ckan-dev service of this docker-compose setup.

• Once running, in another terminal window run the test command:

docker-compose -f docker-compose.dev.yml exec ckan-dev nosetests --ckan-dev --nologcapture --reset-db -s -v --with-pylons=/srv/app/src_extensions/ckanext-myext/test.ini /srv/app/src_extensions/ckanext-myext/

You can also pass nosetest arguments to debug

--ipdb --ipdb-failure

Note: Right now all tests will be run, it is not possible to choose a specific file or test.

How to debug my methods in the dockerized environment so I can have a better understanding of whats going on with my logic

To run a container and be able to add a breakpoint with pdb, run the ckan-dev container with the --service-ports option:

docker-compose -f docker-compose.dev.yml run --service-ports ckan-dev

This will start a new container, displaying the standard output in your terminal. If you add a breakpoint in a source file in the src folder (import pdb; pdb.set_trace()) you will be able to inspect it in this terminal next time the code is executed.

How to debug core CKAN code

Currently, this docker-compose setup doesn't allow us to debug core CKAN code since it lives inside the container. However, we can do some hacks so the container uses a local clone of the CKAN core hosted in our machine. To do it:

• Create a new folder called ckan_src in this docker-ckan folder at the same level of the src/
• Clone ckan and checkout the version you want to debug/edit

git https://github.com/ckan/ckan/ ckan_src
cd ckan_src
git checkout ckan-2.8.3

• Edit docker-compose.dev.yml and add an entry to ckan-dev's and ckan-worker-dev's volumes. This will allow the docker container to access the CKAN code hosted in our machine.

   - ./ckan_src:/srv/app/ckan_src

• Create a script in ckan/docker-entrypoint.d/z_install_ckan.sh to install CKAN inside the container from the cloned repository (instead of the one installed in the Dockerfile)

#!/bin/bash
echo "*********************************************"
echo "overriding with ckan installation with ckan_src"
pip install -e /srv/app/ckan_src
echo "*********************************************"

That's it. This will install CKAN inside the container in development mode, from the shared folder. Now you can open the ckan_src/ folder from your favorite IDE and start working on CKAN.