Metadata-Version: 2.4
Name: ckanext-marinerg
Version: 0.7.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.5.0
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` | Checks each field against the model, and supplies the form's choices |
| `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, their allowed values and labels, and their constraints come from the
[`marinerg-schema`](https://git.ichec.ie/marinerg-i/marinerg-schema) package. To
change one, change it there and release it. Then move the exact pin in
`pyproject.toml` and run `uv lock`. The pin is exact because the CKAN image
installs from `pyproject.toml`, not the lock.

## Develop

```sh
uv sync --group dev
uv run tox
```

`uv run tox` runs the format check, lint, type check and tests, as CI does. The
tests include the check that the form still takes its rules from the model.

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

Open the [newest pipeline for `main`](https://git.ichec.ie/marinerg-i/ckanext-marinerg/-/pipelines/main/latest)
and press the play button on release patch, minor or major. The release
pipeline publishes the package to PyPI and the CKAN image to DockerHub. It scans
the image first, and a high or critical vulnerability with a fix stops the
release. Then it tags the commit. 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).
