add JSON-LD plugin steps for CKAN

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/[email protected]#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 %}
+    <script type="application/ld+json">
+
+    </script>
+  {% 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 `<script type="application/ld+json">` section inside
+  the page source (which is the embedded JSON-LD, that is required by ODIS).
+  
+### Docker Troubleshooting
+
+#### Check Logs
+
+- you can check logs through the commandline, passing the name of the container,
+  such as:
+  ```
+  docker logs ckan-docker-git-master-ckan-1
+  ``` 
+- alternatively you can use Portainer to check the logs of a container, just 
+  click on the little file icon beside the container name, such as:
+  
+  ![logs](./images/logs.png)
+  
+#### Restart container
+
+- you can restart a container through the commandline, passing the name of the 
+  container, such as:
+  ```
+  docker restart ckan-docker-git-master-ckan-1
+  ``` 
+- alternatively you can use Portainer to restart container, just 
+  select the container on the left, and then click the `Restart` button above, 
+  such as:
+  
+  ![restart](./images/restart.png)
+  
+#### Remove all containers
+
+Sometimes you might want to start over, so you can execute the following to 
+delete all Docker containers and cache.
+
+```{caution}
+This will remove all existing containers, even those that are running.
+```
+
+- remove all containers:
+  ```
+  sudo docker rm -f $(sudo docker ps -a -q)
+  ``` 
+- remove cache:
+  ```
+  docker system prune -a
+  ```
+
 ## Option 2: Install CKAN & dependencies manually
 
 ### Install PostgreSQL