Develop
Training

InstallFest NRP Invenio

Cíle školení:

  • Nainstalovat si invenio
  • Vytvořit nový model
  • Seznámit se s cmdline nástroji
  • Seznámit se s UI konfigurací

Nebudeme dnes řešit:

  • Napojení na AAI
  • Harvestování do/z repozitáře
  • Konfiguraci pro produkční nasazení

Úvod

Prezentace

Prerekvizity

Invenio pro svůj běh potřebuje posix systém (linux, macos) a několik závislostí. Je potřeba mít nainstalované závislosti z Invenio RDM requirements (opens in a new tab).

Je potřeba mít nainstalován balíčkovací manager uv pro Python, podle návodu v https://github.com/astral-sh/uv (opens in a new tab).

Pro MacOS, pokud používáte homebrew, je nutné si vytvořit soubor ~/.envrc.local:

# dynamic libraries (such as cairo)
export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib

Instalace

Instalaci zajišťuje skript nrp-installer.sh, který stáhnete z githubu a spustíte s názvem repozitáře, který chcete vytvořit. rdm-12 je aktuální větev podporované verze Invenio. Na konci Q3 se očekává vydání Invenio RDM 13, všechny oborové repozitáře by pak měly začínat s touto verzí.

mkdir -p demo
cd demo
 
curl -sSL https://raw.githubusercontent.com/oarepo/nrp-devtools/rdm-12/nrp-installer.sh >nrp-installer.sh
 
bash nrp-installer.sh my-repo
🎤 Human readable name of the repository
   Demo repository
🎤 Description of the repository
    (Finish with 'Alt+Enter' or 'Esc then Enter')
> My Demo Repository
 
🎤 List of languages to use in the repository,
2 letter code separated by either comma or space
   cs de

...

Your repository is now initialized. 

To test it out, start the repository in development mode
via ./nrp develop and head to https://127.0.0.1:5000/
to check that everything has been installed correctly.

Then add metadata models via ./nrp model create <model_name>,
edit the model and compile it via ./nrp model compile <model_name>.

To generate a default UI for the model, run ./nrp ui detail <model_name>.

První kompilace a spuštění

cd my-repo
 
./nrp develop
 
Development server is running

1 or server     - restart python server
2 or ui         - restart webpack server
0 or stop       - stop the server (Ctrl-C also works)

Kontrola

Otevřete prohlížeč a zadejte adresu https://127.0.0.1:5000/. Měli byste vidět hlavní stránku repozitáře.

Import počátečních slovníků a dat

Nechte server běžet a v novém terminálu spusťte:

 
# cd ...my-repo
 
source .venv/bin/activate
invenio oarepo fixtures load ./fixtures --verbose

V prohlížeči klikněte na Communities a ujistěte se, že je tam komunita Generic Community.

Vytvoření uživatele

Pojďme vytvořit uživatele, který bude vlastníkem komunity Generic Community. Následující příkaz bude chtít zadání hesla nového uživatele, je třeba zadat alespoň 6 znaků.

invenio users create -a -c "spravce@e-infra.cz" --profile '{"full_name": "Velký Správce"}'
 
invenio access allow administration-access user spravce@e-infra.cz
 
invenio access allow administration-moderation user spravce@e-infra.cz
invenio oarepo communities members add generic "spravce@e-infra.cz" owner

A následně vytvořte uživatele clen@e-infra.cz a nastavte mu roli "member" ve stejné komunitě.

Kontrola

Přihlaste se do repozitáře jako správce. Měli byste vidět v menu položku Communities a v nich možnost vytvářet nové komunity. Jako člen tlačítko pro vytvoření komunity neuvidíte.

Konfigurace UI - Branding

Nyní je možné přizpůsobit základní UI repozitáře formou nastavení loga, výměny textů a barevnosti.

Detailnější dokumentace je k dispozici pod sekci Branding

Nastavení loga

  • Stáhneme si nové logo z training-assets (opens in a new tab) do adresáře ui/static/images.

  • Nastavíme naše nové logo do konfigurace Invenia, tj. na konec souboru invenio.cfg (viz Logo Change) (do nastavení se davá relativní cesta vůči adresáři /ui/static):

THEME_LOGO="images/my-logo.svg"
  • Aby se změny projevily, je třeba restartovat development server stiskem 1.

Změna barevnosti

Změna barvy záhlaví

V ui/branding/semantic-ui/less/globals/site.variables se nachazí definice proměnných ovlivňujících celkový vzhled repozitáře. Pro změnu pozadí navigační lišty nastavíme nějaký hezký gradient, který si můžete vygenerovat zde (opens in a new tab), např.:

@navbar_background_image: linear-gradient(12deg, blue, blue 15%, #ffcc00);

Změníme primární barvu brandu (používanou pro všechny primární prvky, např. tlačítka):

@primaryColor: blue;

Změna barvy zápatí

Můžeme změnit i nastavení konkrétní UI komponenty, např. u komponenty page_footer:

ui/branding/semantic-ui/less/default/views/page_footer.variables

při nastavení se odkazujeme na jinou proměnnou s definicí barvy (@pink - proměnné začínají znakem @):

@pageFooterBackgroundColor: @pink;

Podrobnější dokumentaci naleznete pod sekcí Colors

Přidání modelu

V jednom NRP repozitáři je možno mít více typů záznamů, každý typ s jinou množinou metadat. Příkladem je kombinovaný repozitář, kde jsou záznamy o datasetech, publikacích a projektech - každý typ záznamu má jinou strukturu metadat.

Definice typu záznamu se nazývá model. Model se skládá z názvu, popisu, struktury metadat a systémových informací, které jsou použity k vygenerování kódu Invenio repozitáře. Struktura metadat je definována v notaci odvozené od JSON schématu a může obsahovat validační pravidla, popisy a další informace.

Pozor: před vytvářením modelu je nutno zastavit repozitář, protože modelový kód se generuje do zdrojových souborů a ty nemohou být změněny za běhu.

Vytvoření modelu

./nrp model create datasets

Tento příkaz vytvoří nový model s názvem datasets a vygeneruje k němu i prázdné uživatelské rozhraní.

Poznámka: Až bude připraven CCMM (Czech Core Metadata Model), tento krok bude zahrnovat i rozhodnutí, jestli model bude odvozen od CCMM nebo bude kompletně vlastní.

Vygenerovaná struktura modelu je uložena v adresáři ./models v souborech datasets.yaml a datasets-metadata.yaml. YAML formát je zvolen pro jednoduchost editace, čitelnost a možnost přidávat poznámky / komentáře.

 Kompilace modelu

Jádro invenia neumí pracovat s takto definovaným modelem. Je třeba jej zkompilovat do python zdrojového kódu, který bude obsahovat třídy a metody pro práci s modelem.

./nrp model compile datasets

Databázová migrace

Invenio používá postgresql databázi. Pro nový model je třeba vytvořit několik databázových tabulek, které budou obsahovat data záznamů. Tento krok se nazývá databázová migrace.

Invenio pro databázové migrace používá nástroj alembic. Pro vytvoření migrace je třeba spustit následující příkaz:

./nrp alembic

Tento příkaz provede několik kroků:

  1. invenio alembic upgrade heads - zaktualizuje databázi podle aktuálních alembic skriptů
  2. invenio alembic revision - porovná zdrojový kód s aktuálním databázovým schematem a vygeneruje nový alembic skript
  3. Alembic nástroj není dokonalý a vygenerovaný skript není funkční - ./nrp alembic se jej pokusí opravit
  4. invenio alembic upgrade heads - aplikuje změny do databáze

Pokud by krok 4 neprošel, je třeba zkontrolovat vygenerovaný alembic skript a opravit jej ručně a následně zavolat invenio alembic upgrade heads.

Zavedení nového indexu

Invenio používá Opensearch pro vyhledávání. Pro nový model je třeba vytvořit nový index, který bude obsahovat data záznamů tohoto modelu.

source .venv/bin/activate
invenio oarepo index init
invenio oarepo cf init

Kontrola

Spustíme opět server

./nrp develop

V průběhu spouštění bude detekováno, že se změnilo prostředí pythonu a bude provedena aktualizace instalovaných knihoven a nová kompilace uživatelského rozhraní. Po dokončení se server spustí a můžeme se podívat na nový model.

Po kliknutí na vyhledávání už nebude zobrazena informace o chybě, ale dostaneme stránku s 0 výsledky.

Nahrání záznamu z příkazové řádky

Pro nahrání záznamu do repozitáře můžeme použít příkazovou řádku. Nejprve si nainstalujme příkaz nrp-cmd v novém okně terminálu:

python3.12 -m venv nrp-cmd-venv
source nrp-cmd-venv/bin/activate
pip install nrp-cmd

Příkazová řádka nrp-cmd umožňuje vytvářet, číst, upravovat a mazat záznamy a soubory. Zaregistrujeme repozitář:

Pro uživatele MacOS následující příkaz vyžaduje systémovou knihovnu libmagic, nainstalujete ji příkazem:

brew install libmagic
nrp-cmd add repository https://127.0.0.1:5000 --no-verify-tls myrepo

Nyní můžeme nahrát záznam do repozitáře:

nrp-cmd create record '{"title": "My first dataset"}' --community generic --set myrec
 
nrp-cmd get record @myrec -v
 
nrp-cmd update record @myrec '{"title": "My first dataset - updated"}'
 
nrp-cmd get record @myrec -v
 
nrp-cmd upload file @myrec invenio.cfg
 
nrp-cmd list files @myrec

Poznámka: Ve výstupu příkazu nrp-cmd get record @myrec -v je pole self_html, které může být použito pro zobrazení záznamu v prohlížeči.

Úprava modelu

Vypněte invenio server.

Pojďme přidat do modelu pole keywords. Nejprve upravíme soubor datasets-metadata.yaml a přidáme nové pole:

  keywords[]:
    type: keyword

Následně zkompilujeme model:

./nrp model compile datasets

Alembic migrace není potřeba, protože pole uvnitř metadat jsou uložena jako JSON a nemění se struktura databázové tabulky. Co se ale změní, je struktura indexu, který je třeba znovu vytvořit:

source .venv/bin/activate 
 
invenio index destroy --yes-i-know
invenio index init
invenio oarepo cf init
invenio communities custom-fields init
invenio oarepo index reindex
invenio oarepo index reindex

Poznámka: na tuto sekvenci příkazů bude vytvořen alias ./nrp reindex.

Vytvoření UI pro detail záznamu

Následující příkaz vytvoří šablonu UI pro detail záznamu:

./nrp ui detail datasets

Příkaz vytvoří soubor v ui/datasets/templates/semantic-ui/datasets/DetailMetadata.jinja.

Kontrola

Spusťte server ./nrp develop --skip-checks a otevřete stránku s detailem záznamu (odkaz je na nrp-cmd read record -v @myrec).

Pokud přidáte jazyk v editaci, uvidíte, že se špatně zobrazuje. Oprava (v další verzi generátoru se bude takto generovat):

  <ITableField d={d.languages} level={level}>
    {% for lang in array(d.languages) %}
      <IVocabularyItem item={lang} />
    {% endfor %}
  </ITableField>

Úprava UI - přidání klíčových slov do deposit formuláře

Do formuláře {model_name}/semantic-ui/js/{model_name}/forms/FormFieldsContainer.jsx

přidejte na začátek následující import:

    import {StringArrayField} from "@js/oarepo_ui/forms"

a na místo, kde se má vstup zobrazit, přidejte:

   <StringArrayField
          fieldPath="metadata.keywords"
          addButtonLabel={i18next.t("Add keyword")}
          {...getFieldData({ fieldPath: "metadata.keywords" })}
    />

Úprava UI - zobrazení klíčových slov ve výsledcích vyhledávání

Do souboru {model_name}/semantic-ui/js/{model_name}/search/ResultsListItem.jsx přidejte:

* Vytažení hodnoty z výsledku vyhledávání je možné pomocí lodash funkce _get. Tato funkce bere tři argumenty: objekt, cestu k hodnotě a výchozí hodnotu, která se použije, pokud cesta neexistuje.

const keywords = _get(result, "metadata.keywords", []);

* Zobrazte klíčová slova v odpovídající lokaci

// <Item.Meta>
//   <Grid columns={1}>
//      <Grid.Column>
//      ...
      
            <Grid.Row className="ui separated">
            <span
                aria-label={i18next.t("Keywords")}
                title={i18next.t("Keywords")}
            >
                {_join(
                keywords.map((keyword) => keyword),
                ", "
                )}
            </span>
            </Grid.Row>
        )}
ComponentsWorkflows