111 lines
4.8 KiB
Markdown
111 lines
4.8 KiB
Markdown
---
|
|
sidebar: auto
|
|
---
|
|
|
|
# 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](https://github.com/okfn/docker-ckan#ckan-images) 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.
|