de-intern-guide/docs/onboarding/ckan-setup.mdx

---
sidebar_position: 4
---

# 📊 CKAN Setup

In this section we'll go over how to install [CKAN](https://ckan.org) v2.11.3 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 (provides you with PostgreSQL, Redis, and SOLR 9)

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

:::info Apple Silicon?

If you're using macOS, you may need to change the postgis image used in `ckan-compose/postgres/Dockerfile`. Change `FROM postgis/postgis:16-3.4-alpine` to FROM `imresamu/postgis:16-3.4-bundle0-bookworm` (based on [this issue](https://github.com/dathere/de-intern-guide/issues/29)).

:::

:::info Permission denied?

If you get a "Permission denied" error, you may need to run `sudo ahoy up` instead of `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.11.3#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
```

Let's 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 should be at least 8 characters such as `password` since we're using this instance for development locally and not exposing it to the Internet).

```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
```