.. Zdroj: elza/docs/admin-guide/source/04-configuration.rst, elza e87a93d6d1

.. _Admin_config:

=====================
Konfigurace aplikace
=====================

Konfigurační soubor
===================

Elza čte konfiguraci ze souboru :file:`config/elza.yaml` v pracovním
adresáři procesu (instalačním adresáři), případně ze souboru
:file:`elza.yaml` v tomto adresáři. Soubor je ve formátu YAML. Vzorový
soubor je součástí distribuce (:file:`server/config/elza.yaml`).

Hodnoty, které soubor neobsahuje, se přebírají z výchozích hodnot
aplikace. Libovolnou hodnotu lze nastavit také proměnnou prostředí, jejíž
název je klíč velkými písmeny s tečkami nahrazenými podtržítky (například
``ELZA_DATA_PASS`` pro ``elza.data.pass``), nebo systémovou vlastností
Javy (``-Delza.data.pass=...``). Proměnné prostředí a systémové vlastnosti
mají přednost před souborem.

Minimální konfigurace:

.. code-block:: yaml

   elza:
     data:
       url: jdbc:postgresql://localhost/elza
       user: elza
       pass: tajne
     workingDir: /opt/elza/work
     logFile: ${elza.workingDir}/log/elza.log
     siemLogFile: ${elza.workingDir}/log/siem.log

Změny se projeví po restartu aplikace.

Nastavení externích systémů (CAM, úložiště digitalizátů, mapové servery,
poskytovatelé AI) není součástí souboru; spravují se v administraci (viz
:doc:`07-integrace`). Autentizaci popisuje kapitola :doc:`05-zabezpeceni`.

Plánované úlohy se nastavují výrazy cron se šesti poli:
``<sekunda> <minuta> <hodina> <den-v-měsíci> <měsíc> <den-v-týdnu>``,
například ``0 0 4 ? * SAT`` pro každou sobotu ve 4:00. Hodnota ``-``
úlohu vypne.

Databáze a pracovní adresář
===========================

.. list-table::
   :header-rows: 1
   :widths: 32 18 50

   * - Klíč
     - Výchozí hodnota
     - Význam
   * - ``elza.data.url``
     - (povinné)
     - JDBC URL databáze, například ``jdbc:postgresql://localhost/elza``.
   * - ``elza.data.user``
     - (povinné)
     - Databázový uživatel.
   * - ``elza.data.pass``
     - (povinné)
     - Heslo databázového uživatele.
   * - ``elza.data.batchSize``
     - 1000
     - Maximální počet položek v jednom databázovém dotazu se seznamem
       hodnot (klauzule ``IN``) a velikost dávky hromadných operací.
   * - ``elza.workingDir``
     - ``./work``
     - Pracovní adresář: binární soubory (:file:`dms`), balíčky
       (:file:`dpkg`), vyhledávací index a další pracovní data. Uveďte
       absolutní cestu.
   * - ``elza.locale``
     - ``cs``
     - Locale pro řazení textů a pro formátování a čtení dat v aplikaci.
       Neurčuje jazyk uživatelského rozhraní.

Pool databázových spojení má 20 spojení
(``spring.datasource.hikari.maximumPoolSize``); zvyšujte jej jen spolu
s počty vláken uvedenými níže.

.. _Admin_config_web:

Webový server a nahrávání souborů
=================================

.. list-table::
   :header-rows: 1
   :widths: 32 18 50

   * - Klíč
     - Výchozí hodnota
     - Význam
   * - ``server.port``
     - 8080
     - HTTP port aplikace.
   * - ``server.address``
     - všechny adresy
     - Síťová adresa, na které server naslouchá. Pokud reverzní proxy
       běží na stejném serveru, nastavte ``127.0.0.1``.
   * - ``elza.upload.max_file_size``
     - ``25MB``
     - Maximální velikost jednoho nahrávaného souboru. ``-1`` limit ruší.
   * - ``elza.upload.max_request_size``
     - ``100MB``
     - Maximální velikost jednoho požadavku s nahrávanými soubory.
       ``-1`` limit ruší.
   * - ``elza.appName``
     - ``ELZA``
     - Název aplikace zobrazovaný v uživatelském rozhraní.
   * - ``elza.integrationScriptUrl``
     - (nenastaveno)
     - URL integračního skriptu, který doplní vlastní záhlaví a zápatí
       (viz :doc:`07-integrace`).

Použijte přesně klíče ``elza.upload.*`` s podtržítky; standardní klíče
``spring.servlet.multipart.*`` ani starý ``multipart.maxFileSize`` nemají
žádný účinek.

Další nastavení vloženého serveru popisují `vlastnosti serveru Spring Boot
<https://docs.spring.io/spring-boot/appendix/application-properties/index.html#appendix.application-properties.server>`_,
například dobu platnosti session (``server.servlet.session.timeout``),
session cookie (``server.servlet.session.cookie.name``,
``server.servlet.session.cookie.secure``) nebo maximální počet vláken pro
zpracování požadavků (``server.tomcat.threads.max``).

.. _Admin_config_accesslog:

Přístupový log (access log)
---------------------------

Vložený Tomcat umí zapisovat každý HTTP požadavek jako jeden řádek do
přístupového logu. Ve výchozím stavu je vypnutý. Nastavte i adresář,
jinak Tomcat zapisuje do dočasného adresáře:

.. code-block:: yaml

   server:
     tomcat:
       accesslog:
         enabled: true
         directory: ${elza.workingDir}/log
         prefix: access_log
         suffix: .log
         file-date-format: .yyyy-MM-dd
         pattern: "%h %{X-Forwarded-For}i %l %u %t \"%r\" %s %b %{ms}T"
         buffered: false
         rotate: true

Soubor má název :file:`access_log.<rrrr-MM-dd>.log` a rotuje se denně.
Pole vzoru jsou: ``%h`` adresa klienta (za reverzní proxy adresa proxy),
``%{X-Forwarded-For}i`` původní adresa klienta předaná proxy, ``%l`` a
``%u`` identita a uživatel (obvykle ``-``; přihlášení do Elzy zde vidět
nejsou), ``%t`` čas, ``%r`` řádek požadavku, ``%s`` stavový kód, ``%b``
velikost odpovědi v bajtech, ``%{ms}T`` doba zpracování v milisekundách.
Další pole popisuje `dokumentace přístupového logu Tomcat
<https://tomcat.apache.org/tomcat-10.1-doc/config/valve.html#Access_Logging>`_.
``buffered: false`` zapisuje každý řádek okamžitě; ``true`` je výkonnější
při vysoké zátěži.

Logování
========

.. list-table::
   :header-rows: 1
   :widths: 32 18 50

   * - Klíč
     - Výchozí hodnota
     - Význam
   * - ``elza.logFile``
     - (nenastaveno)
     - Cesta k aplikačnímu logu, například
       ``${elza.workingDir}/log/elza.log``. Rotuje se denně, uchovává se
       30 dní. Poslední řádky jsou zobrazeny i v administraci. Bez
       nastavení aplikace loguje pouze na konzoli.
   * - ``elza.siemLogFile``
     - (nenastaveno)
     - Cesta k bezpečnostnímu auditnímu logu (události autentizace ve
       formátu JSON), například ``${elza.workingDir}/log/siem.log``.
       Rotuje se denně, uchovává se 90 dní. Bez nastavení se auditní log
       nezapisuje. Viz :doc:`05-zabezpeceni`.

Úrovně logování se nastavují standardními klíči ``logging.level.*``,
například ``logging.level.cz.tacr.elza: debug``.

Zpracování na pozadí
====================

Dlouhotrvající činnosti se zpracovávají ve frontách na pozadí. Každá
fronta má maximální počet vláken a tam, kde to má smysl, maximální počet
úloh běžících současně pro jeden archivní soubor. Více vláken urychlí
zpracování mnoha archivních souborů, ale zvyšuje zátěž databáze a
spotřebu paměti.

.. list-table::
   :header-rows: 1
   :widths: 40 10 50

   * - Klíč
     - Výchozí hodnota
     - Význam
   * - ``elza.asyncActions.node.threadCount``
     - 4
     - Vlákna pro validaci jednotek popisu.
   * - ``elza.asyncActions.node.maxPerFund``
     - 2
     - Současně běžící validace pro jeden archivní soubor.
   * - ``elza.asyncActions.bulk.threadCount``
     - 4
     - Vlákna pro hromadné akce (funkce).
   * - ``elza.asyncActions.bulk.maxPerFund``
     - 1
     - Současně běžící hromadné akce pro jeden archivní soubor.
   * - ``elza.asyncActions.output.threadCount``
     - 2
     - Vlákna pro generování výstupů a zároveň vlákna fronty exportů (viz
       poznámka níže). Generování výstupů je paměťově náročné.
   * - ``elza.asyncActions.output.maxPerFund``
     - 1
     - Současně generované výstupy pro jeden archivní soubor.
   * - ``elza.asyncActions.export.maxPerFund``
     - 1
     - Současně běžící exporty pro jeden archivní soubor.
   * - ``elza.asyncActions.ap.threadCount``
     - 4
     - Vlákna pro zpracování archivních entit (validace, generování
       názvů).

.. note::

   Klíč ``elza.asyncActions.export.threadCount`` se načítá, ale ve verzi
   3.4 se fronta exportů řídí klíčem
   ``elza.asyncActions.output.threadCount``.

Vyhledávání a cache
===================

.. list-table::
   :header-rows: 1
   :widths: 40 10 50

   * - Klíč
     - Výchozí hodnota
     - Význam
   * - ``elza.search.node.maxCount``
     - 10000
     - Maximální počet výsledků fulltextového vyhledávání v jednotkách
       popisu.
   * - ``elza.search.node.maxCountPerFunds``
     - 1000
     - Maximální počet výsledků pro jeden archivní soubor.
   * - ``elza.search.node.maxTimeMs``
     - 10000
     - Časový limit v milisekundách pro sestavení výsledku vyhledávání.
   * - ``elza.levelTreeCache.size``
     - 30
     - Počet stromů verzí archivních souborů držených v paměti. Zvyšte
       při větším počtu uživatelů pracujících na různých archivních
       souborech a dostatku paměti.
   * - ``elza.levelTreeCache.display.daoId``
     - ``true``
     - Zobrazovat ve stromu informace o připojených digitalizátech.
   * - ``elza.ap.cache.batchsize``
     - 800
     - Velikost dávky při přestavbě cache archivních entit.
   * - ``elza.ap.cache.transsize``
     - 800
     - Počet archivních entit zpracovaných v jedné transakci při
       přestavbě cache.

.. _Admin_config_upload_reindex:

Plánovaná údržba
================

.. list-table::
   :header-rows: 1
   :widths: 30 22 48

   * - Klíč
     - Výchozí hodnota
     - Význam
   * - ``elza.reindex.cron``
     - ``0 0 4 ? * SAT``
     - Úplná přestavba vyhledávacího indexu, ve výchozím nastavení každou
       sobotu ve 4:00. Index lze přestavět také v administraci
       (*Přepočítat indexy*).
   * - ``elza.cleanup.cron``
     - ``0 0 3 * * *``
     - Denní úklid: nepoužívané datové záznamy, soubory importních dávek
       starší než 30 dní a prošlý obsah koše DMS.
   * - ``elza.cleanup.maxBatch``
     - 150000
     - Počet nepoužívaných datových záznamů smazaných v jedné transakci
       úklidu. Snižte pro kratší transakce.
   * - ``elza.dms.check.cron``
     - ``0 30 3 ? * SUN``
     - Kontrola konzistence úložiště binárních souborů vůči databázi.
       Osiřelé soubory se přesunou do koše.
   * - ``elza.dms.orphanMinAgeMinutes``
     - 60
     - Minimální stáří souboru, aby jej kontrola konzistence mohla
       považovat za osiřelý.
   * - ``elza.dms.trashRetentionDays``
     - 30
     - Počet dní, po kterých se obsah přesunutý do
       :file:`dms/_trash/<datum>/` smaže. Do té doby je smazání vratné.

Výstupy
=======

.. list-table::
   :header-rows: 1
   :widths: 38 16 46

   * - Klíč
     - Výchozí hodnota
     - Význam
   * - ``elza.export.jasperFormat``
     - ``PDF``
     - Formát výstupů generovaných ze šablon Jasper: ``PDF``, ``DOCX``,
       ``RTF`` nebo ``ODT``. U jiného formátu než PDF se do výstupu
       neslučují přílohy PDF.
   * - ``elza.export.jasperPageCacheSize``
     - 100
     - Počet stran výstupu držených při generování v paměti; ostatní
       strany se odkládají do souboru v dočasném adresáři. ``0`` ponechá
       celý dokument v paměti.
   * - ``elza.export.jasperSwapBlockSizeKb``
     - 1024
     - Velikost bloku odkládacího souboru v kB.
   * - ``elza.export.jasperSwapMinGrowCount``
     - 100
     - Počet bloků, o které se odkládací soubor zvětšuje.
   * - ``elza.export.outputRecordCacheSize``
     - 1000
     - Počet archivních entit držených v paměti při generování jednoho
       výstupu. ``0`` omezení ruší.
   * - ``elza.export.mapviewer.url``
     - prohlížeč map LightComp
     - Základní URL prohlížeče map pro odkazy na souřadnice ve výstupech.

.. _Admin_config_upload_fa:

Předávání výstupů do jiného systému
-----------------------------------

Vygenerovanou archivní pomůcku je možné odeslat do systému, který
implementuje službu SOAP FileTransfer. Odesílání se v uživatelském
rozhraní povoluje volbou ``elza.output.allowSend`` a vyžaduje nastavení
odesílatele:

.. code-block:: yaml

   elza:
     output:
       allowSend: true
       senderName: FtOutputSender
     findingAid:
       upload:
         url: https://dms.archiv.example/esm/cxf/ft
         username: elza
         password: tajne
         soapLogging: false

``soapLogging`` zapíše do logu celou komunikaci SOAP.

Přílohy
=======

``elza.attachment.mimeDefs`` uvádí typy souborů připojených k archivnímu
popisu, které mohou uživatelé v aplikaci editovat, a volitelné
generátory, které je pomocí externího programu převádějí do jiných
formátů:

.. code-block:: yaml

   elza:
     attachment:
       mimeDefs:
         - mimeType: text/plain
           editable: true
           generators:
             - outputMimeType: application/pdf
               command: txt2pdf {2} {4}
               outputFileName: result.pdf

``mimeType``
   MIME typ přílohy.
``editable``
   Zda mohou uživatelé soubory tohoto typu editovat. Uvádějte vždy.
``generators``
   Externí převody. ``command`` se spouští v dočasném adresáři; ``{0}`` se
   nahradí cestou k tomuto adresáři, ``{1}`` názvem vstupního souboru,
   ``{2}`` jeho úplnou cestou, ``{3}`` názvem výstupního souboru a ``{4}``
   jeho úplnou cestou. ``outputFileName`` je název souboru, který příkaz
   vytvoří (zástupné znaky se v něm nenahrazují), ``outputMimeType`` jeho
   typ.

Import
======

.. list-table::
   :header-rows: 1
   :widths: 30 16 54

   * - Klíč
     - Výchozí hodnota
     - Význam
   * - ``elza.import.batchInputDir``
     - (nenastaveno)
     - Adresář na serveru, ze kterého mohou uživatelé dávkově importovat
       archivní soubory (*Import ze složky na serveru*). Uživatelé mohou
       procházet jen jeho podadresáře. Bez nastavení je import ze složky
       na serveru vypnutý; nahrání z prohlížeče funguje vždy.
   * - ``elza.package.testing``
     - ``false``
     - Znovu nahrát balíček se stejnou verzí, jako má již nahraný
       balíček. Pouze pro vývoj balíčků.

.. _Admin_config_scope_del_ents:

Archivní entity
===============

.. list-table::
   :header-rows: 1
   :widths: 34 12 54

   * - Klíč
     - Výchozí hodnota
     - Význam
   * - ``elza.scope.deleteWithEntities``
     - ``false``
     - Povolit smazání oblasti, která ještě obsahuje archivní entity,
       společně s nimi. Zapínejte jen dočasně pro odstranění již
       nepoužívaných oblastí.

Mapové podklady
===============

``elza.map.layers`` uvádí mapové podklady nabízené v editoru souřadnic.
Každý podklad má ``name``, ``type`` (``OSM`` nebo ``WMS``), ``url``, u WMS
název vrstvy ``layer`` a ``initial: true`` pro podklad zobrazený jako
první:

.. code-block:: yaml

   elza:
     map:
       layers:
         - name: GR_ZM25
           type: WMS
           url: https://geoportal.cuzk.cz/WMS_ZM25_PUB/WMService.aspx
           layer: GR_ZM25
           initial: false

.. _Admin_config_ws_fonds_admin:

Webové služby
=============

.. list-table::
   :header-rows: 1
   :widths: 42 14 44

   * - Klíč
     - Výchozí hodnota
     - Význam
   * - ``elza.webservice.fonds.adminPermissionMode``
     - ``ADD_ONLY``
     - Jak služba ``FundService`` aktualizuje správce archivního souboru:
       ``ADD_ONLY`` přidá zaslané uživatele a skupiny a ostatní ponechá;
       ``NO_SYNC`` správce uvedené v požadavku ignoruje.

AI asistent
===========

Vlastní poskytovatel AI se nastavuje jako externí systém.

.. list-table::
   :header-rows: 1
   :widths: 42 10 48

   * - Klíč
     - Výchozí hodnota
     - Význam
   * - ``elza.ai.poll-failure-timeout-seconds``
     - 300
     - Požadavek selže, pokud poskytovatel není po tuto dobu nepřetržitě
       dostupný.
   * - ``elza.ai.request-lifetime-timeout-seconds``
     - 1800
     - Maximální stáří nedokončeného požadavku.

Monitorování
============

``management.*`` (správcovský port) a ``elza.monitoring.scheduler.*``
popisuje kapitola :doc:`08-monitorovani`.

Diagnostika
===========

Nastavení pro řešení problémů, nikoli pro běžný provoz:

.. list-table::
   :header-rows: 1
   :widths: 34 12 54

   * - Klíč
     - Výchozí hodnota
     - Význam
   * - ``elza.debug.clientLog``
     - ``true``
     - Zapisovat zprávy webového klienta do konzole prohlížeče.
   * - ``elza.debug.performanceLogger``
     - ``false``
     - Zapisovat do logu dobu zpracování každého REST požadavku.
   * - ``elza.debug.requests``
     - ``false``
     - Zapisovat do logu každý HTTP požadavek včetně obsahu, na úrovni
       DEBUG loggeru
       ``org.springframework.web.filter.CommonsRequestLoggingFilter``.
   * - ``elza.validate.unitdate.enabled``
     - ``true``
     - Kontrolovat datace jednotek popisu.
   * - ``elza.validate.stringfield.enabled``
     - ``true``
     - Odmítat prázdné textové hodnoty nebo hodnoty tvořené jen mezerami.

Již nepoužívané klíče
=====================

Tyto klíče lze z :file:`elza.yaml` odstranit:

- ``spring.jpa.properties.hibernate.dialect`` s dialektem PostGIS
  z konfigurací řady 2.x,
- ``multipart.maxFileSize`` (použijte ``elza.upload.*``),
- ``elza.accesspoints.sync`` (od verze 3.4 přesunuto do nastavení
  externího systému),
- ``elza.da.sync`` (od verze 3.4.5 přesunuto do nastavení úložiště
  digitalizátů),
- ``elza.ap.checkDb``, ``elza.hibernate.index.*``.
