6.1. Technická dokumentace

6.1.1. Instalace

Zdrojový kód je kompilován pomocí Apache Maven: mvn clean package -DskipTests

Zkompilovaná aplikace je zabalena v spustitelném .jar souboru.

Závislosti:

  • PostgreSQL

  • Java 11+ (OpenJDK)

Apache

Kromě konfigurace Shibboleth a domovských adresářů (součást instalačního balíčku) je vhodné na úrovni Apache - nikoliv na úrovni webové aplikace - konfigurovat také klient timeout. Tento timeout se projeví odpojením klienta - webové aplikace - ve chvíli kdy server, např. kvůli zvýšené zátěži, není schopný zpracovat požadavek v čase. Na severu požadavek běží i po uplynutí timeoutu.

Timeout je konfigurovatelný v sekundách v souboru httpd.conf, případně ve vhosts sekci, pokud jsou vhosts konfigurovány. Příklad konfigurace: Timeout 900. Defaultní hodnota je 300 sekund.

Elasticsearch 6.8.2

Elasticsearch doporučujeme instalovat standartně přes Správce balíčků (package manager), pokud je toto z nějakého důvodu nevyhovující, přikládáme alternativní postup instalace.

Struktura

Struktura je aktualně nasledující:
drwxrwsr-x 2 inqool        elasticsearch  178 May 10 22:50 config
drwxrwsr-x 4 elasticsearch elasticsearch   34 May 10 22:47 data
drwxrwsr-x 6 inqool        elasticsearch  117 May 10 22:37 elasticsearch-6.8.2
lrwxrwxrwx 1 elasticsearch elasticsearch   20 May 10 22:46 elasticsearch-current -> elasticsearch-6.8.2/
drwxrwsr-x 2 elasticsearch elasticsearch    6 May 10 22:46 run

Jedná se o variantu ve které jsou logy, data a konfigurace odděleně od binarních dat za účelem jednodušších aktualizací a vyšší bezpečnosti. Právo zápisu do binarních dat a konfigurací má pouze uživatel inqool.

Instalace (CentOS 7)

yum install epel-release
yum install java-11-openjdk
cd /opt
wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-6.8.2.tar.gz
tar -xf elasticsearch-6.8.2.tar.gz
elasticsearch-6.8.2/bin/elasticsearch-plugin install analysis-icu
mkdir config data logs run
ln -s elasticsearch-6.8.2 elasticsearch-current
wget https://raw.githubusercontent.com/elastic/elasticsearch/master/distribution/packages/src/common/systemd/elasticsearch.service
edit elasticsearch.service as you need
  Environment=ES_HOME=/usr/share/elasticsearch
  Environment=ES_PATH_CONF=${path.conf}
  Environment=PID_DIR=/var/run/elasticsearch
  WorkingDirectory=/usr/share/elasticsearch

  User=elasticsearch
  Group=elasticsearch

  ExecStart=/opt/elasticsearch/elasticsearch-current/bin/elasticsearch -p ${PID_DIR}/elasticsearch.pid --quiet

cp elasticsearch.service /etc/systemd/system

systemctl daemon-reload

edit /opt/elasticsearch/config/elasticsearch.yml
  path.logs: /opt/elasticsearch/logs
  path.data: /opt/elasticsearch/data/index

edit /opt/elasticsearch/config/jvm.options
-XX:ErrorFile=/opt/elasticsearch/logs/hs_err_pid%p.log
8:-Xloggc:/opt/elasticsearch/logs/gc.log
9-:-
Xlog:gc*,gc+age=trace,safepoint:file=/opt/elasticsearch/logs/gc.log:utctime,pid,tags:filecount=32,filesize=64m

systemctl start elasticsearch
systemctl enable elasticsearch

Formátová identifikace

Pro formátovou identifikaci lze použít nástroje Siegfried nebo Droid. Cesta k binárnímu souboru / spustitelný příkaz je nakonfigurován v application.yml (formatLibrary.identificationToolBinary) Typ nástroje je také konfigurován v application.yml (formatLibrary.identificationToolType), možné hodnoty: SIEGFRIED, DROID

Siegfried https://www.itforarchivists.com/siegfried/

Droid https://www.nationalarchives.gov.uk/information-management/manage-information/preserving-digital-records/droid/

ActiveMQ 5.x (volitelné)

ActviveMQ je použito pro některá synchronizační volání z ESM do ostatních modulů. Zprávy jsou uloženy do persistentní fronty a z ní odbavovány.

Defaultně je použit embedded ActiveMQ broker, v tomto případě není třeba nic instalovat ani konfigurovat. Data fronty jsou uložena v složce data/kahadb v pracovním adresáři aplikace ESM. Pokud je to potřeba je možné tento adresář změnit nastavením konfigurační property aplikace ESM: queue.dir.

Standalone služba

Pro podporu monitoringu fronty a její správu (např. odebrání blokujícíh zpráv) je možné nainstalovat ActiveMQ jako standalone aplikaci. Pro stažení může být použit např. tento odkaz: https://activemq.apache.org/components/classic/download/

Při spuštění v standalone režimu jsou data defaultně uložena v složce data/kahadb v pracovním adresáři aplikace ActiveMQ. V konfiguračním souboru aplikace ESM je v tomto případě nutno nastavit: spring.activemq.broker-url: tcp://localhost:61616 a také spring.activemq.in-memory: false Defaultní port ActiveMq je 61616. Webové rozhraní je defaultně na adrese http://localhost:8161/admin, jméno:heslo je admin:admin .

Administrátorské zásahy do fronty:

  • Je-li aplikace ESM vypnuta lze zprávy z fronty přímo mazat tlačítkem Delete.

  • Je-li aplikace ESM zapnuta mělo by mazání probíhat přesunem zprávy do speciální SKIP fronty tlačítkem Move.

  • Chceme-li zprávu pouze odložit (a odblokovat tím ostatní zprávy) můžeme

    • ji odložit do pro tento účel manuálně založené fronty POSTPONED (na tuto není aplikace napojena, nebude do ní tedy zasahovat)

    • textovou reprezentaci zprávy vykopírovat, následně ji smazat jedním z výše uvedených kroků a následně ji opět ručně založit v příslušné frontě

      • zprávu lze do fronty zařadit v ActiveMQ admin rozhraní, tlačítkem Send To u příslušené fronty na obrazovce přehledu front

      • do pole Message Body se vloží vykopírovaná zpráva, do pole Message Header je nutné zadat pouze Persistent Delivery:ANO, Priority:4

  • Mazání/odkládání zpráv by mělo být pečlivě zváženo, neboť úspěšné zpracování následujících zpráv ve frontě, potažmo konzistence systému, mohou být závislé na zpracování smazaných/odložených zpráv.

Pokud je potřebné jakékoliv z defaultních nastavení standalone verze změnit je tak možné učinit přímo konfigurací ActiveMq, nikoliv konfigurací aplikace ESM.

Při přechodu z jednoho režimu na druhý (Embedded <-> Standalone) je možné při vypnutém systému překopírovat datový obsah a neztratit tak data fronty.

Spuštění aplikace z příkazové řádky

Restartování aplikace spuštěné přímo z příkazové řádky:

  • pomocí ps xw nalézt PID JAVA procesu esm.jar

  • kill <PID>

  • nohup java -jar -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 esm.jar $> esm.log

  • agentlib:jdwp lze vypustit, slouží pro možnost remote debuggingu

  • pracovní adresář je automaticky adresář z nějž je aplikace spuštěna, lze změnit přepínačem -Duser.dir={cesta}

Spuštění aplikace jako služby

  • esm.service - vzorový konfigurační soubor pro systemd službu


[Unit]
Description=ESM
After=syslog.target

[Service]
User=ais
ExecStart=/opt/ais/esm/esm.jar
SuccessExitStatus=143

[Install]
WantedBy=multi-user.target

  • esm.conf - konfigurační soubor systemd služby - vložit do pracovního adresáře aplikace

JAVA_OPTS="-XX:MaxMetaspaceSize=800M -Xmx4096M"

6.1.2. Konfigurace

Systém

Aplikace je konfigurovatelná skrze soubor application.yml který se nachází v pracovním adresáři. Konfigurační hodnoty v tomto souboru překrývají defaultní konfigurační hodnoty v souboru application.yml nacházejícím se ve složce src/main/resources. Po přepsání souboru je pro projevení změn nutné aplikaci restartovat. Při konfigurování atributů cest na souborovém systému lze zadat relativní cestu vzhledem k pracovnímu adresáři.

Cron používaný aplikací musí být ve formátu: second, minute, hour, day of month, month, day(s) of week.

ais:
  path:
    # root složka, níže definované workspaces vychází z ní
    core-workspace: /opt/ais
    # workspace využíváno především pro import dat z modulu Výběr
    esm: dataspace/esm
    # export workspace
    export: dataspace/export
    # ingest workspace - mělo by být rychlé
    ingest: workspace/ingest
    # počet vláken dedikovaných pro ingest
  threadPools:
    ingest: 8

#konfigurace Shiboleth
api:
  security:
    scheme: header
    principalHeader: "X-SSO-Username"

spring:
  data:
    elasticsearch:
      cluster-name: ESM ElasticSearch
      cluster-nodes: localhost:9300
  datasource:
    url: jdbc:postgresql://host:port/ais?currentSchema=peva
    username: changeme
    password: changeme
#konfigurace mail serveru skrz který ESM odesílá emaily
  mail:
    host: 127.0.0.1
    port: 25
    protocol: smtp
    test-connection: false
  activemq:
    in-memory: false
    broker-url: tcp://localhost:61616

server:
  servlet:
    context-path: /esm
    session:
      timeout: 6h
      cookie:
        path: "/esm"
  compression:
    enabled: true
    mime-types: text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json
    min-response-size: 1024

vyber:
  enabled: true
  endpoint: http://host:port/ws/vyber
  host: host
  port: port
  username: changeme
  password: changeme

whois:
  endpoint: https://host/webapps/testing/core/restapi/v1

elza:
  enabled: true
  endpoint: http://host:port/services
  host: host
  port: port
  username: changeme
  password: changeme
  # interval aktualizace přístupových bodů upravených v ELZA (ms)
  registry.fixed-delay: 900000

badatelna:
  endpoint: http://host/badatelna/ws
  ft: http://host/badatelna/cxf/ft
  enabled: true

archivalStorage:
  api: http://host:port/api
  # údaje účtu v Archival storage zakódované v base64
  authorization:
    basic:
      read: base64encode(username:password)
      readWrite: base64encode(username:password)
      admin: base64encode(username:password)
# konfigurace do kdy ESM čeká odpovědi z Archival Storage, popsáno v technické dokumentaci, sekce Integrace
  async:
    retry:
      limit: 30
      interval: 60
  storeVerification:
    retry:
      limit: 5
      interval: 3000
    firstAttemptDelay: 500

ws:
  mail:
    #adresa odesílatele uvedeného v emailu zaslaného z ESM
    from: noreply@ais-ap1tst.is.cuni.cz
    #přístupové údaje k ESM mail službě, použijí externí systémy, nap. Výběr
    security:
      username: changeme
      password: changeme

# interaktivní API dokumentace, značně zpomaluje start systému (minuty)
environment:
  swagger:
    enabled: false

# zdrojové URL pro update formátové knihovny
formatLibrary:
  formatDetailListUrl: https://www.nationalarchives.gov.uk/PRONOM/Format/proFormatListAction.aspx
  formatListUrl: https://www.nationalarchives.gov.uk/PRONOM/Format/proFormatDetailListAction.aspx

export:
  operation:
    watermark:
      opacity: 30%
    metadata-reduction:
      size-limit: 20MB


#doba (ms) úřed opětovným pokusem odbavení selhaného (blokačního) požadavku z fronty ESM->Badatelna / ESM->ELZA
queue:
  redelivery-delay: 1800000

6.1.3. Databáze

  • Všechny entity používají UUID.

  • Tabulky jsou generovány při prvním spuštění aplikace.

  • Aplikačnímu serveru musí být povolen přístup k DB s přihlašováním typu “md5”

6.1.4. Instalační balíček

Pro instalaci je dodán samostatný ESM instalační balíček.

Databáze je iniciována z DB dumpu aisDump.bin

Dále jsou dodány tyto přílohy:

  • esm.jar - zkompilovaná aplikace

  • application.yml - konfigurační soubor překrývající defaultní konfiguraci - vložit do pracovního adresáře aplikace. Jedná se o vzorový soubor, jednotlivé konfigurační hodnoty může být nutné upravit dle konkrétního prostředí.

  • httpd.conf - hlavní konfigurační soubor Apache

  • conf.d.zip - další konfigurační soubory Apache

  • web-build.zip - build GUI aplikace - rozbalit a nakopírovat obsah složky „build“ do /inet/www/html-ais/esm (dle httpd konfigurace)

  • ukDump.bin - dump dat archivu Univerzity Karlovy z PEVA II, který je možné použít v rámci procesu migrace mezivýstupu z DB PEVA II do DB AIS

Nástroje vývojáře

Po spuštění BE i FE části aplikace je nutné v GUI systému v sekci Nástroje vývojáře kliknout na tlačítko REINDEX ALL. Zároveň je v této sekci nutné iniciovat databázi ELZA a Badatelny migrovanými osobami, archivními soubory a ukládacími jednotkami. Dále je nutné v provést aktualizaci formátové knihovny: Nástroje vývojáře -> Skritpy -> Synchronizační API -> Pronom -> Aktualizovat.

Spuštění bez SSO a integrací (vývojové prostředí)

Pro spuštění bez SSO a integrací doporučujeme nepoužít přiložený application.yml ale použít soubor application.yml z návodu k migraci v němž není definováno SSO a tedy budou použity defaultní aplikační nastavení. Zároveň jsou v něm vypnuty integrace na moduly ELZA, Výběr apod.

Autentizaci testovacího uživatele (je součástí dumpu) je následně možné simulovat přes hlavičky. Pro simulování např. v prohlížeči Google Chrome je možné využít např. tento plugin: https://chrome.google.com/webstore/detail/modheader/idgpnmonknjnojddfkpgkljpfnnfcklj Následně je třeba použít hlavičky: SM_USER=un_pevaa1095 a SM_ROLES=620000010=SUPER_ADMIN

6.1.5. Integrace

Archival Storage

Uložení balíčku do Archival Storage probíhá vždy v rámci ingestu a vždy ve dvou krocích: 1. uložení, 2. dotaz na stav.

Uložení

ESM získává odpověď na požadavek uložení ve chvíli kdy jsou data nahrána do workspace Archival Storage, samotné uložení v Archival Storage však probíhá asynchronně. Pokud je iniciální odpověď chybová, ESM vyčká a pokusí se iniciální operaci několikrát zopakovat. Doba čekání i počet opakování je konfigurován v application.yml. Stejné hodnoty a mechanismus je použitý při požadavcích na export balíčku.

  • archivalStorage.async.retry.interval: 60 - počet sekund mezi pokusy

  • archivalStorage.async.retry.limit:3 - max. počet pokusů

Dotaz na stav

Po úspěšné odpovědi na požadavek uložení volá ESM periodicky Archival Storage API s dotazem na stav uložení.

  • archivalStorage.storeVerification.firstAttemptDelay: 500 - počet milisekund před prvním dotazem na stav (nemělo by být nižší než předpokládaná doba zpracování nejmenšího balíčku)

  • archivalStorage.storeVerification.retry.interval: 3000 - počet milisekund mezi dalšími dotazy na stav

  • archivalStorage.storeVerification.retry.limit: 5 - mx. počet dotazů na stav, pokud do této doby není balíček uložen je ingest ukončen s chybou a balíček rollbackován