From 078e40e53b747df4e8252cb057554e3693f19e72 Mon Sep 17 00:00:00 2001 From: Jeff McKenna Date: Fri, 17 Jan 2025 16:18:08 -0400 Subject: [PATCH] add JSON-LD plugin steps for CKAN --- book/tooling/ckan.md | 205 +++++++++++++++++++++++++- book/tooling/images/ckan-connect1.png | Bin 0 -> 111767 bytes book/tooling/images/ckan-connect2.png | Bin 0 -> 13443 bytes book/tooling/images/dcat-install1.png | Bin 0 -> 24210 bytes book/tooling/images/dcat-install2.png | Bin 0 -> 17499 bytes book/tooling/images/logs.png | Bin 0 -> 111878 bytes book/tooling/images/restart.png | Bin 0 -> 100633 bytes 7 files changed, 204 insertions(+), 1 deletion(-) create mode 100644 book/tooling/images/ckan-connect1.png create mode 100644 book/tooling/images/ckan-connect2.png create mode 100644 book/tooling/images/dcat-install1.png create mode 100644 book/tooling/images/dcat-install2.png create mode 100644 book/tooling/images/logs.png create mode 100644 book/tooling/images/restart.png diff --git a/book/tooling/ckan.md b/book/tooling/ckan.md index 6897e918d..ff902056d 100644 --- a/book/tooling/ckan.md +++ b/book/tooling/ckan.md @@ -158,7 +158,7 @@ We will follow the steps [Install Docker Engine on Ubuntu](https://docs.docker.c - build the Docker images ``` - docker compose build + docker compose -f docker-compose.yml build ``` you should see a response that states `Service ckan: Built` @@ -245,6 +245,209 @@ for WSL. ![portainer install4](./images/portainer-install4.png) +### Install DCAT extension for JSON-LD Support + +We will follow the Docker compose [README](https://github.com/ckan/ckan-docker/blob/master/README.md) for CKAN. + +#### Edit the Dockerfile to install the ckanext-dcat extension + +- assuming you are still at the `odis@` prompt, but if not: + - goto Start menu, choose "WSL" + - CMD window should open with an `odis@` prompt +- execute `cd ckan-docker-git-master` +- now use `vi` to add in the required section for the ckanext-dcat plugin into + the `Dockerfile` : + ``` + #use vi to open the Dockerfile + vi ckan/Dockerfile + #to make your changes, first press your "i" key (for INSERT mode), and + #then edit the desired lines + #then save with the command + :wq + ``` + - around line#6, paste the following into the `Dockerfile`: + ``` + ### prevent permissions errors when installing ckanext-dcat extension + USER root + + ### DCAT ### + RUN pip3 install -e 'git+https://github.com/ckan/ckanext-dcat.git@v2.1.0#egg=ckanext-dcat' && \ + pip3 install -r https://raw.githubusercontent.com/ckan/ckanext-dcat/v2.1.0/requirements.txt + ``` + - save the file + +#### Edit the .env file to load the Extensions + +Inside the `ckan-docker-git-master` directory, use `vi` to edit the `.env` file +to add the `dcat` and `structured_data` plugins, as follows: + +- open the .env file: + + ``` + vi .env + ``` +- around line#69, change the `CKAN__PLUGINS` line to add the 2 extensions, such as: + + ``` + CKAN__PLUGINS="image_view text_view datatables_view datastore datapusher envvars dcat structured_data" + ``` + +- save the file + +#### Rebuild the containers + +- build the Docker images + ``` + docker compose -f docker-compose.yml build + ``` + you should see a line mentioning the `RUN pip3 install -e` command that + we defined in the Dockerfile. + + ![dcat install1](./images/dcat-install1.png) + +- start the Docker containers + ``` + docker compose up -d + ``` + +#### Check the status + +We can use the CKAN API to check if the new plugins were loaded succefully. + +- using the [Firefox](https://www.mozilla.org/en-CA/firefox/new/) browser (which + displays the JSON results nicely), goto: https://localhost:8443/api/action/status_show + +- you should see a list of extensions that include both `dcat` and + `structured_data`, such as: + + ![build install2](./images/dcat-install2.png) + +#### Connect to the CKAN container through commandline + +You may need to connect to the CKAN container through the commandline, which +can be done through the following steps: + +- you will need to get the exact name of the CKAN container, which is easiest +to see through Portainer. + + ![ckan connect1](./images/ckan-connect1.png) + + You can see above that the container name is `ckan-docker-git-master-ckan-1`. + +- assuming you are still at the `odis@` prompt, but if not: + - goto Start menu, choose "WSL" + - CMD window should open with an `odis@` prompt +- execute the following, to connect to the CKAN container (replace "ckan-docker-git-master-ckan-1" with your container name) : + ``` + docker exec -it ckan-docker-git-master-ckan-1 /bin/bash -c "export TERM=xterm; exec bash" + ``` + + Your prompt should change to something like `ckan@af2e2e3ac57f`. If you then + execute `pwd` you can see that you are in the `/srv/app/` directory, on the CKAN + container. + + ![ckan connect2](./images/ckan-connect2.png) + +#### Install VI on the CKAN container + +If you get a `command not found` error when trying to open a file with `vi` +on the ckan container, you will have to first connect as root, and then install +`vim`, as follows: + +- execute the following, to connect to the CKAN container as root (replace "ckan-docker-git-master-ckan-1" with your container name) : + ``` + docker exec -u root -it ckan-docker-git-master-ckan-1 /bin/bash + ``` + +- now update your local packages: + ``` + apt-get update + ``` + +- finally install `vim`: + ``` + apt-get install vim + ``` + +Then retry your `vi `command. + +#### Modify the CKAN template + +Once connected to the CKAN container (see previous step), you can edit +the `read_base.html` Jinja2 template files, to add a JSON-LD block, +as follows: + +- now use `vi` to edit the `read_base.html` file: + ``` + vi src/ckan/ckan/templates/package/read_base.html + ``` +- in the `{% block head_extras -%}` section, around line#13, paste + the following: + ``` + {% block structured_data %} + + {% endblock %} + ``` + +- save the file, and `exit` the container + +- back on your host machine, restart the CKAN container + ``` + docker restart ckan-docker-git-master-ckan-1 + ``` + +- if you have added a Dataset, now if you right-click on the dataset's + main page (that url would be something like https://localhost:8443/dataset/point-test ) + you should see a `