CKAN in GitHub Codespaces

✏️ If you have any feedback or suggestion about this feature let us know creating a Discussion!

GitHub Codespaces provide an online development environment for repositories hosted on GitHub. You can get a fully functioning and customizable CKAN instance in minutes without having to install anything locally, and even submit code changes as pull requests from them.

This might interest you if you:

1. Want to try out CKAN, but want full control rather than the limited functionality of sites like https://demo.ckan.org
2. Want to contribute a change but don't want to do a full docker based or source install.
3. Want to quickly test a specific configuration or setup without installing it locally
4. Are just comfortable with Cloud-Based development!

⚠️ Important ⚠️
GitHub Codespaces have a free tier, currently 120 core-hours per month (i.e. 60h on the default 2-core VM, 30h on a 4-core VM) and 15Gb of storage, but after that you will be charged for usage. Check the documentation for more details. Check your current usage in the Billing page of your profile to avoid unexpected charges.

Setting up a GitHub Codespace

1. Codespaces are created on your own copy of the ckan repository. You need to fork the ckan/ckan repository. If you want to test a specific CKAN release make sure to uncheck the "Copy the master branch only" field (Learn more about forking in the GitHub documentation)
2. Codespaces are created from specific branches. Select the branch that you want to create your codespace in:

• To run a specific released version, choose the relevant release branch,eg for CKAN 2.10 -> dev-v2.10, for CKAN 2.9 -> dev-v2.9, etc
• To run the latest development branch, select the default master branch

3. Once in the correct branch, click the green "Code" button, and select the "Codespaces" tab. You should see another green button to create the codespace.

4. A new tab will open, and you'll see a small terminal showing setup commands. Most of these involve building the underlying Docker images, the one that CKAN will run of as well as the other services required (PostgreSQL, Solr, etc). If you are going to create codespaces often from the same branch you can use Prebuilds to speed up their creation but be careful as this will increase your storage usage.

5. After a few minutes you'll be redirecting to the codespace interface. Be patient! We are almost done but not there yet. The editor needs to be configured and some CKAN initialization tasks need to be performed (you can check them in the .devcontainer/setup.sh file, which of course you can edit later to suit your needs). If you are not seeing a browser tab with the CKAN homepage to the right or a terminal below that says "Running CKAN on http://localhost:5000", wait a bit. Eventually you should see the following:

Note: Firefox users might see a "Firefox Can't Open This Page" message in the Simple Browser tab instead. This is due to protections against embedding. Just open the page in a new tab using the icon in top right corner and refresh the inline browser, and the page should load fine.

What can you do in the Codespace

What you are seeing is an instance of the Visual Studio Code for the Web editor. You can browse and edit all files in the CKAN repository using the tree panel to your left. Changes that you make to the source files with the editor, as well as changes to the site itself (e.g. creating organizations or datasets) will be persisted until you delete the codespace.

Explore

It's your own CKAN demo site! You can log in using the ckan_admin sysadmin user (password test1234), which will give you full control of the UI. Try creating an Organization, adding some datasets, uploading data, etc

• User Guide
• Sysadmin Guide

Customize

The site has been configured using the default settings that you get in a brand new CKAN instance but you can change any configuration in the ckan.ini file. The development server will refresh automatically as soon as you save your changes to reflect the new configuration.

• Configuration options reference
• Authorization overview

Additionally, you can install as many extensions as you want. Check the extension README for any particular instructions but they all basically follow the same pattern:

1. Open a new terminal in the bottom panel
2. Clone the extension

   git clone https://github.com/ckan/ckanext-dcat.git
   

3. Install the extension

   cd ckanext-dcat
   python setup.py develop --user
   

4. Install extra requirements (if any)

   pip install -r requirements.txt
   

5. Add the plugin(s) to the ckan.plugins configuration option in the ckan.ini file and save the file to refresh the server.

Develop

You can browse the files in the CKAN source code using the tree panel on the left, open one of them and edit it. Once you save your changes, the development server will be restarted automatically.

You can commit your changes to the branch where you started the codespace in using the "Source Control" icon in the left toolbar.

• Getting started with Visual Studio Code
• CKAN Architecture Overview

Database

You can run queries against the PostgreSQL database using the "SQLTools" plugin, the database icon in the left toolbar.

• SQLTools documentation

Tests

To run the automated tests simply add a new terminal to the console below and run the pytest command:

pytest --ckan-ini=test-core.ini ckan ckanext

Or to run a specific test:

pytest --ckan-ini=test-core.ini ckan/tests/logic/action/test_create.py::TestMemberCreate::test_group_member_creation

I need more!

• If you are finding the codespace too slow you can change the machine type to add more cores to the VM, but note that this will count towards your free allowed quota.
• If you don't like the editor, you can run the same codespace using your local Visual Studio Code or JetBrains IDE instances.
• Alternatively you can use a Docker Compose setup or do a tried and tested Source Install in your local computer.