Metadata-Version: 2.4
Name: ckanext-marinerg
Version: 0.6.0
Summary: CKAN extension for the MARINERG-i data catalogue: marine metadata schema, Zenodo prefill, facility/equipment picker, and DCAT-AP export.
Author-email: Irish Centre for High End Computing <james.grogan@ichec.ie>
License: AGPL-3.0-or-later
Project-URL: Repository, https://git.ichec.ie/marinerg-i/ckanext-marinerg
Project-URL: Homepage, https://git.ichec.ie/marinerg-i/ckanext-marinerg
Keywords: CKAN,Marine Renewable Energy,Data Catalogue,EOSC,DCAT
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Paste
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ckanext-scheming
Requires-Dist: marinerg-schema>=0.1
Requires-Dist: PyYAML
Requires-Dist: requests
Requires-Dist: pydantic>=2.0
Requires-Dist: prometheus-client>=0.20
Dynamic: license-file

# ckanext-marinerg

This is the CKAN extension behind the MARINERG-i data catalogue, where test
facilities describe the datasets from their marine renewable energy test
campaigns. The data stays in Zenodo; the catalogue makes it findable. The
extension adds a marine metadata form, controlled vocabularies, DOI prefill
from Zenodo, facility pickers, a DCAT-AP export for European harvesters, and
Keycloak login.

New to data catalogues? Start with
[How the catalogue works](docs/how-the-catalogue-works.md). It explains the
concepts and lists what is built and what is not.

## Run it locally

You need Docker or Podman.

```sh
cd infra
cp .env.example .env
docker compose -f compose.yml -f compose.local.yml up -d --build
```

CKAN is on http://localhost:5001. Log in as `ckan_admin`, password `ckan_admin`.
On Apple Silicon, set `CKAN_PLATFORM=linux/arm64` in `.env` first.

The local stack mounts this repo into the container, so Python changes take
effect straight away. Restart the `ckan` service to pick up template changes,
and rebuild with `--build` after a dependency change. The Zenodo prefill talks
to a [zenodo-mock](https://git.ichec.ie/platform-engineering/modules/pipelines/zenodo-mock)
on port 8766, so a local run never touches real Zenodo. The facility pickers
expect the access portal on port 8000, and show nothing without it.

## Find your way around

Start at `ckanext/marinerg/plugin.py`, which registers everything with CKAN.

| Path | What it does |
|---|---|
| `schemas/dataset.yaml` | The dataset form: fields, help text and layout |
| `validators.py` | Rejects values outside the controlled vocabularies |
| `profile.py` | Adds our fields to the DCAT-AP export |
| `signposting.py` | Adds FAIR Signposting headers to dataset pages |
| `actions.py` | Zenodo prefill, and the facility and equipment lookups |
| `oidc_*.py` | Keycloak login, and roles from the `ckan_role` claim |
| `registry/` | Vocabulary labels, fetched by `scripts/fetch_*` |
| `templates/`, `assets/` | The theme |

The fields and their allowed values come from the
[`marinerg-schema`](https://git.ichec.ie/marinerg-i/marinerg-schema) package. To
change a vocabulary, change it there and release it, then run
`uv lock --upgrade-package marinerg-schema` here.

## Develop

```sh
uv sync --group dev
uv run pytest
uv run ruff check ckanext tests
uv run ruff format ckanext tests
uv run mypy ckanext
uv run python scripts/check_schema_convergence.py
```

The tests stub CKAN, so they need no CKAN install. Ruff targets Python 3.10,
because that's what CKAN 2.11 runs.

## Theme

The theme is one stylesheet, `assets/css/marinerg-theme.css`, loaded after
CKAN's own. Only style what CKAN doesn't, and match CKAN's markup instead of
overriding it. Set the logo, favicon and site title in CKAN's config at
`/ckan-admin/config`, not in CSS.

We don't use a compiled SCSS theme. CKAN's theme variables can't be overridden
without forking its SCSS, which would break on each CKAN upgrade.

## Configuration

`infra/Dockerfile` bakes these keys into `ckan.ini`, except the token, which
is only set at runtime. The runtime environment variable overrides the baked
value.

| Key | Runtime variable | Purpose |
|---|---|---|
| `marinerg.facility_api_url` | `MARINERG_FACILITY_API_URL` | The access portal's API, for the facility pickers |
| `marinerg.facility_api_token` | `MARINERG_FACILITY_API_TOKEN` | A token to see non-public facilities |
| `marinerg.portal_base_url` | `MARINERG_PORTAL_BASE_URL` | The access portal, for policy links and facility identifiers |
| `marinerg.zenodo_api_url` | | The Zenodo API for prefill |
| `marinerg.zenodo_api_key` | | Optional Zenodo key for prefill |

Unset, the facility pickers and portal links show nothing. The OIDC settings
and the plugin list are read at runtime. See `infra/README.md`.

## Release

Run a pipeline on `main` with `RELEASE_FIELD` set to `patch`, `minor` or
`major`. It tags a release, which publishes the package and the CKAN image.
Then set the new image tag in the
[infra](https://git.ichec.ie/marinerg-i/infra) repo and deploy.

## Licence

AGPL-3.0-or-later. See [`LICENSE`](LICENSE). Copyright © Irish Centre for
High-End Computing (ICHEC).
