---
sidebar_position: 4
---

# 📊 CKAN Setup

In this section we'll go over how to install [CKAN](https://ckan.org) v2.10.6 and get it running on your Ubuntu VM.

## 📝 Written Tutorial

Prerequisites:

- New installation of Ubuntu 22.04 ([virtual machine](/onboarding/ubuntu-vm-setup), VPS, local device, etc.) connected to the Internet.

For these installation notes we'll assume the username in Ubuntu is `rzmk`, so change it to yours when applicable.

## Upgrade packages

```bash
sudo apt update -y && sudo apt upgrade -y
```

:::info Can't paste commands into your VM terminal?

If you're unable to paste text into the VM, you may either:

- Search through the VM settings/configuration to enable copying/pasting text
- SSH into the VM and paste into your local terminal

:::

## Set up SSH (optional)

If you're using a VM then it may be easier when developing to SSH into the VM from a code editor such as VSCode, VSCodium, or Zed.

To enable SSH on the VM install `openssh-server`, and to identify the VM IP address to use when using SSH install `net-tools`:

```bash
sudo apt install openssh-server net-tools -y
```

Run the `ifconfig` command to identify your IP address, then use SSH on your local device and code editor to access the environment:

```bash
ssh rzmk@IPADDRESSHERE
```


## Install Docker

> Notes for this section based on https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-22-04.

```bash
sudo apt update
sudo apt install apt-transport-https ca-certificates curl software-properties-common -y
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
apt-cache policy docker-ce
sudo apt install docker-ce -y
```

Also add your user to the sudo group to run Docker without `sudo`:

```bash
sudo usermod -aG docker ${USER}
su - ${USER}
```

## Install `docker-compose`

We use `docker-compose` to set up and run `ckan-compose`.

```bash
sudo apt install docker-compose -y
```

<!--
## Install Docker Compose

> Notes for this section based on https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-compose-on-ubuntu-22-04.

```bash
mkdir -p ~/.docker/cli-plugins/
curl -SL https://github.com/docker/compose/releases/download/v2.3.3/docker-compose-linux-x86_64 -o ~/.docker/cli-plugins/docker-compose
chmod +x ~/.docker/cli-plugins/docker-compose
docker compose version
```
-->

## Download Ahoy and add to $PATH

We'll be using [ckan-compose](https://github.com/tino097/ckan-compose) to handle the PostgreSQL, Redis, and SOLR setup. One of the prerequisites for using ckan-compose is installing [Ahoy](https://github.com/ahoy-cli/ahoy).

Go to https://github.com/ahoy-cli/ahoy/releases/latest and download the `ahoy-bin-linux-amd64` file and move it to your `$PATH` named as `ahoy`.

```bash
sudo mv ~/Downloads/ahoy-bin-linux-amd64 /usr/local/bin/ahoy
sudo chmod +x /usr/local/bin/ahoy
```

<!--
## Setup Git and Git Credential Manager

[Login to GitHub](https://github.com/login) on the VM and download the latest [Git Credential Manager `.deb` file from here](https://github.com/git-ecosystem/git-credential-manager/releases/latest) then in same folder as `.deb` file run:

```bash
# cd ~/Downloads
sudo dpkg -i <path-to-package>
git-credential-manager configure
git config --global credential.credentialStore "cache"
```
-->

## Set up ckan-compose

```bash
cd ~/
sudo apt install docker-compose -y
git clone https://github.com/tino097/ckan-compose.git
cd ckan-compose
ahoy generate-env
ahoy up
```

You may get asked after `ahoy generate-env` to provide a `PROJECT_NAME`, this can be anything so we'll put `myproject`. You may also use the defaults for `DATASTORE_READONLY_PASSWORD` and `POSTGRES_PASSWORD` for development.

## CKAN steps 1-4 with caveats

```bash
sudo apt-get install python3-dev libpq-dev python3-pip python3-venv git-core redis-server -y
sudo mkdir -p /usr/lib/ckan/default
sudo chown `whoami` /usr/lib/ckan/default
python3 -m venv /usr/lib/ckan/default
. /usr/lib/ckan/default/bin/activate
pip install --upgrade pip
pip install -e 'git+https://github.com/ckan/ckan.git@ckan-2.10.6#egg=ckan[requirements]'
deactivate
. /usr/lib/ckan/default/bin/activate
sudo mkdir -p /etc/ckan/default
sudo chown -R `whoami` /etc/ckan/
ckan generate config /etc/ckan/default/ckan.ini
ln -s /usr/lib/ckan/default/src/ckan/who.ini /etc/ckan/default/who.ini
```

Next you must modify the CKAN config at `/etc/ckan/default/ckan.ini`:

```ini
debug = true
ckan.debug_supress_header = False
```

Also replace the following values to this:

```bash
ckan.devserver.threaded = true
ckan.max_resource_size = 10000
ckan.max_image_size = 5
```

Continue to step 7 while in the virtual environment (replace `rzmk` with your group then username for the `chown` command and your CKAN details for the CKAN sysadmin account generation command). You may be prompted to add a sysadmin username and password (the password may need to be at least 8 characters).

```bash
cd /usr/lib/ckan/default/src/ckan
pip install flask-debugtoolbar==0.14.1
cd /var/lib
sudo mkdir -p ckan/default
sudo chown rzmk.rzmk ckan/default
ckan -c /etc/ckan/default/ckan.ini db init
ckan -c /etc/ckan/default/ckan.ini sysadmin add rzmk email=rzmk@localhost name=rzmk
ckan -c /etc/ckan/default/ckan.ini run
```

Now you should be able to view your locally running CKAN instance at [http://localhost:5000](http://localhost:5000).

## When restarting your server

If you shut down your Ubuntu instance and then start it again, you may want to run the following commands to get the CKAN instance running again:

```bash
/etc/init.d/redis-server stop
cd ckan-compose
ahoy up
```

Then run the following (e.g., after you SSH from your preferred terminal):

```bash
cd /usr/lib/ckan/default/
. ./bin/activate
cd src/ckan
ckan -c /etc/ckan/default/ckan.ini run
```