.. Zdroj: docs/admin-guide/source/02-installation.rst, elza 18b7804099

.. _admin_install:

=========
Instalace
=========

Aplikaci Elza je možné nainstalovat dvěma způsoby:

- **Instalačními skripty (doporučeno pro Linux)** - sada skriptů, která
  nainstaluje Elzu jako službu systemd a automatizuje nasazování nových
  verzí, zálohování databáze, kontrolu stavu a bezobslužné aktualizace.
- **Ručně** z binární distribuce, v Linuxu nebo ve Windows.

Oba způsoby používají stejnou binární distribuci a stejný konfigurační
soubor.

.. _admin_deployment_scripts:

Instalace pomocí instalačních skriptů
=====================================

Skripty a jejich dokumentace jsou publikovány na adrese
https://get.lightcomp.com/elza/ (v angličtině). Vyžadují Linux se systemd,
PostgreSQL včetně klientských nástrojů (``pg_dump``), ``bash`` a
``curl``. Instalace se spouští příkazem:

.. code-block:: bash

   curl -fsSL https://get.lightcomp.com/elza/elza-bootstrap.sh | bash -s -- --home /opt/elza

Bootstrap skript stáhne balík skriptů (ověřený kontrolním součtem) do
adresáře :file:`/opt/elza/scripts`, připraví konfigurační soubor
:file:`elza-env` a nainstaluje jednotky systemd. Po úpravě
:file:`elza-env` (minimálně připojení k databázi) se první nasazení
provede příkazem ``elza-deploy``.

Skripty poskytují tyto příkazy:

- ``elza-deploy`` - instalace nebo aktualizace aplikace: zastaví službu,
  zazálohuje databázi, stáhne distribuci, atomicky přepne na novou verzi,
  spustí službu a ověří, že běží.
- ``elza-backup`` - záloha databáze pomocí ``pg_dump`` s mazáním starých
  záloh.
- ``elza-health`` - kontrola stavu aplikace a volitelné hlášení stavu
  dohledovému systému (viz :ref:`admin_deployment_scripts_reporting`).
- ``elza-update`` - bezobslužná aktualizace na novou verzi.

Databázi je i v tomto případě nutné připravit podle
:ref:`admin_install_db`. Konfigurace vlastní aplikace
(:file:`elza.yaml`) je popsána v kapitole :doc:`04-konfigurace`.

Ruční instalace
===============

Obsah distribuce
----------------

Binární distribuce je soubor ZIP, který obsahuje:

- :file:`server/elza-tomcat-<verze>.jar` - aplikaci s vloženým webovým
  serverem,
- :file:`server/config/elza.yaml` - vzorovou konfiguraci,
- :file:`server/config/csc-metrics.json` - seznam metrik předávaných
  dohledovému systému (viz :doc:`09-monitorovani`),
- :file:`packages/` - základní balíčky: ``package-cz-base`` (číselníky)
  a ``rules-cz-zp2015`` (pravidla popisu ZP2015),
- :file:`data/all-institutions-import.xml` - seznam akreditovaných
  archivů v České republice,
- :file:`readme.txt` - stručný přehled instalace.

.. _admin_install_db:

Příprava databáze
-----------------

#. Vytvořte pro Elzu databázového uživatele, například ``elza``. Pro
   přístup aplikace nepoužívejte účet superuživatele.

#. Vytvořte prázdnou databázi, jejímž vlastníkem je tento uživatel:

   .. code-block:: bash

      createdb -O elza -E UTF8 -l cs_CZ.UTF-8 -T template0 elza

   Locale určuje řazení textů prováděné databází. Použijte locale
   archivního popisu (pro české archivy češtinu); dostupná locale vypíše
   příkaz ``locale -a``. Ve Windows je název například
   ``Czech_Czechia.1250``. Locale nelze po vytvoření databáze změnit.

#. Povolte v databázi rozšíření PostGIS. Vytvoření rozšíření vyžaduje
   práva superuživatele, proveďte je proto jako uživatel ``postgres``:

   .. code-block:: bash

      psql -U postgres -d elza -c "CREATE EXTENSION postgis;"

Tabulky vytvoří Elza při prvním spuštění.

Struktura adresářů
------------------

Elza potřebuje instalační a pracovní adresář, například:

- :file:`/opt/elza/server` - soubor JAR a :file:`config/elza.yaml`,
- :file:`/opt/elza/work` - pracovní adresář.

Ve Windows například :file:`D:\\Elza\\server` a :file:`D:\\Elza\\work`.

Pro službu vytvořte samostatného uživatele operačního systému, který je
vlastníkem pracovního adresáře a má k němu plná práva. V Linuxu je vhodné
odkazovat na aktuální JAR symbolickým linkem, aby aktualizace změnila jen
link: :file:`/opt/elza/server/elza-tomcat.jar` ->
:file:`elza-tomcat-3.4.7.jar`.

Pracovní adresář obsahuje:

- :file:`dms/` - binární soubory (přílohy, výstupy, publikace, importní
  dávky). Jeho strukturu spravuje Elza a nesmí se ručně upravovat;
  zálohuje se společně s databází (viz :doc:`10-zalohovani`).
- :file:`dpkg/` - balíčky načítané při startu (viz
  :ref:`admin_install_dpkg`).
- :file:`log/` - logy, pokud jsou nastaveny jako ve vzorové konfiguraci.
- další pracovní data, která si Elza v případě potřeby znovu vytvoří.

.. _Admin_InstallBinConf:

Konfigurace
-----------

Zkopírujte :file:`server/config/elza.yaml` do :file:`config/elza.yaml`
vedle souboru JAR a nastavte minimálně:

- připojení k databázi (``elza.data.url``, ``elza.data.user``,
  ``elza.data.pass``),
- pracovní adresář (``elza.workingDir``),
- balíčky, které instalace používá (``elza.packages.enabled``, viz
  :ref:`admin_install_dpkg`).

.. 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
     packages:
       enabled: [CZ_BASE, ZP2015]

Ostatní nastavení popisuje kapitola :doc:`04-konfigurace`.

Spuštění jako služby
--------------------

Před nastavením služby aplikaci jednou spusťte z instalačního adresáře a
ověřte konfiguraci:

.. code-block:: bash

   java -jar elza-tomcat.jar

Při prvním spuštění Elza vytvoří databázové schéma. Aplikace je připravena,
jakmile log oznámí její spuštění; naslouchá na portu 8080.

Příklad jednotky systemd (:file:`/etc/systemd/system/elza.service`):

.. code-block:: ini

   [Unit]
   Description=ELZA
   After=network.target postgresql.service

   [Service]
   User=elza
   WorkingDirectory=/opt/elza/server
   ExecStart=/usr/bin/java -Xmx4g -Dfile.encoding=UTF-8 -jar /opt/elza/server/elza-tomcat.jar
   SuccessExitStatus=143
   Restart=on-failure

   [Install]
   WantedBy=multi-user.target

Velikost paměti (``-Xmx``) upravte podle dostupné paměti. Pracovním
adresářem procesu musí být instalační adresář, aby byl nalezen soubor
:file:`config/elza.yaml`. Službu povolíte a spustíte příkazem
``systemctl enable --now elza``. S ``Restart=on-failure`` funguje restart
z administrace bez dalšího nastavení: aplikace skončí s návratovým kódem 3,
po kterém ji jednotka spustí znovu (viz :doc:`04-konfigurace`).

Ve Windows lze Elzu provozovat jako službu pomocí nástroje jako WinSW nebo
NSSM, který spouští stejný příkaz ``java -jar``. Viz také `dokumentace
Spring Boot k nasazení
<https://docs.spring.io/spring-boot/how-to/deployment/installing.html>`_.

První spuštění
==============

.. _admin_install_first_admin:

První administrátor
-------------------

Dokud databáze neobsahuje žádného uživatele, zobrazí aplikace místo
přihlášení dialog *Úvodní nastavení*. Ten založí prvního administrátora:
uživatele s heslem a oprávněním administrátora.

.. warning::

   Dokud první administrátor neexistuje, může jej založit kdokoli, kdo
   aplikaci otevře. Založte administrátora hned po prvním spuštění, ještě
   než aplikaci zpřístupníte v síti, nebo jej nastavte v konfiguraci (viz
   :ref:`admin_install_users_from_config`).

Po stisku *Vytvořit administrátora* se aplikace přihlásí jako nový
administrátor. Heslo musí splňovat pravidla pro hesla (viz
:doc:`05-zabezpeceni`); po instalaci jsou všechna pravidla vypnutá.

První administrátor nemá přiřazenou osobu (archivní entitu), protože
archivní entity vyžadují nejprve nahrané balíčky. Osobu lze přiřadit
později v *Administrace* > *Uživatelé* > *Upravit*. Další uživatelé se
zakládají obvyklým způsobem, s osobou.

.. _admin_install_users_from_config:

Uživatelé z konfigurace
-----------------------

Uživatele lze nastavit také v konfiguraci, jako seznam uživatelských jmen
a hesel v ``elza.security.override``. Elza seznam uplatní při každém
startu bez ohledu na to, zda databáze uživatele obsahuje:

- Pokud uživatel tohoto jména neexistuje, založí se jako administrátor:
  uživatel bez osoby, s oprávněním administrátora a **bez hesla
  v databázi**. Na prázdné databázi se pak dialog *Úvodní nastavení*
  nezobrazí.
- Pokud uživatel existuje, jeho heslo ani oprávnění v databázi se nemění;
  deaktivovaný uživatel se aktivuje.

Uvedený uživatel se přihlásí svým vlastním heslem (z databáze, pokud jej
má) **nebo** heslem z konfigurace; stačí kterékoli z nich. Přihlášení
heslem z konfigurace nevyžaduje změnu hesla a heslo z konfigurace
neexpiruje. Uživatel si může heslo v aplikaci změnit; heslo z konfigurace
platí dál, dokud je uživatel v seznamu uveden. Po odebrání uživatele ze
seznamu platí jen jeho vlastní heslo - uživatel založený ze seznamu, který
si heslo nikdy nenastavil, se nepřihlásí, dokud mu je nenastaví
administrátor. Heslo z konfigurace nikdy neplatí pro výchozího uživatele.

.. code-block:: yaml

   elza:
     security:
       override:
         - username: jan.novak
           password: nejake-heslo
         - username: petr.svoboda
           password: jine-heslo

.. list-table::
   :header-rows: 1
   :widths: 36 18 46

   * - Klíč
     - Výchozí hodnota
     - Význam
   * - ``elza.security.override[].username``
     - (nenastaveno)
     - Uživatelské jméno.
   * - ``elza.security.override[].password``
     - (nenastaveno)
     - Heslo jako prostý text. Neukládá se do databáze; heslo, které
       nesplňuje pravidla pro hesla, se jen ohlásí varováním v logu
       aplikace.

Položka bez uživatelského jména nebo hesla, uživatel uvedený dvakrát nebo
odstraněné klíče ``elza.security.admin.username`` / ``.password`` zastaví
start s chybou. Pokud jednoho uživatele nelze uplatnit (například jeho
jméno je jménem výchozího uživatele a výchozí uživatel je zapnutý), Elza
zapíše chybu do logu, uplatní ostatní a nastartuje.

Každý start zapíše do logu aplikace varování pro každého uvedeného
uživatele (samotné heslo se nikdy nezapisuje). Při nastaveném
``elza.siemLogFile`` zaznamená bezpečnostní auditní log, že je heslo
z konfigurace aktivní (``override_active``), založení nebo aktivaci
uživatele, chybu a každé přihlášení heslem z konfigurace
(``authentication_type`` ``OVERRIDE``); viz :doc:`05-zabezpeceni`.

.. warning::

   Heslo je uloženo jako prostý text a platí vedle vlastního hesla
   uživatele. Jakmile položku nepotřebujete, například po prvním startu,
   odstraňte ji z :file:`elza.yaml`.

Výchozí uživatel
----------------

Nová instalace je přístupná také pod vestavěným výchozím uživatelem
(``admin`` s heslem ``admin``), který má oprávnění administrátora;
tlačítko *Přihlásit* dialogu *Úvodní nastavení* pro něj otevře
přihlašovací formulář. Použijte jej jen k vytvoření účtů administrátorů,
poté jej vypněte volbou ``elza.security.allowDefaultUser: false``
a aplikaci restartujte. Dokud je výchozí uživatel zapnutý, nemůže se první
administrátor jmenovat ``admin``. Viz :doc:`05-zabezpeceni`.

.. _admin_install_dpkg:

Nahrání balíčků
---------------

Elza potřebuje číselníky a pravidla popisu z balíčků v adresáři
:file:`packages/`. Doporučeným způsobem je zkopírovat soubory ZIP do
podadresáře :file:`dpkg/` pracovního adresáře: při každém startu Elza
nahraje z tohoto adresáře každý balíček, jehož verze je vyšší než verze
již nahraného balíčku. Aktualizace pak jen nahradí soubory v :file:`dpkg/`
spolu se souborem JAR.

Které balíčky adresáře instalace používá, určuje ``elza.packages.enabled``,
seznam kódů balíčků. Při každém startu Elza nahraje z :file:`dpkg/` balíčky,
které jsou již naimportované, a balíčky uvedené v seznamu, spolu s balíčky,
na kterých závisejí; ostatní soubory adresáře ponechá beze změny. Balíček,
který nová verze Elzy přidá do :file:`packages/`, se proto do existující
instalace nenaimportuje, pokud není v seznamu uveden. Distribuce obsahuje:

- ``CZ_BASE`` - popis entit podle českého CAM a sdílené číselníky;
  vyžaduje jej ``ZP2015``,
- ``ZP2015`` - česká pravidla popisu,
- ``ISAAR_CPF`` - popis entit podle mezinárodního standardu ISAAR(CPF),
  v angličtině; pro instalace mimo českou praxi nebo vedle ``CZ_BASE``,
- ``ISADG`` - archivní popis souborů podle mezinárodního standardu
  ISAD(G), v angličtině; pro původce a přístupová místa potřebuje
  ``ISAAR_CPF``. Viz uživatelská příručka.

Klíč nastavte před prvním startem. Na prázdné databázi bez klíče Elza
naimportuje všechny balíčky adresáře. Log startu uvádí naimportované
a přeskočené balíčky.

.. note::

   Pokud :file:`dpkg/` obsahuje starší verzi balíčku, než je verze již
   nahraná, aplikace nenastartuje. Starý soubor odstraňte.

*Administrace* > *Správa balíčků* (viz :ref:`ug_admin_packet`) uvádí
balíčky z :file:`dpkg/`, které nejsou nahrané, a co s každým z nich udělá
příští start. *Načíst při příštím startu* balíček označí: značkou je
záznam balíčku bez obsahu a příští start soubor naimportuje (s balíčky,
které vyžaduje). *Zrušit označení* značku odstraní. Stránka pak připomene,
že je potřeba restart, a nabídne *Restartovat aplikaci*: aplikace skončí
s návratovým kódem ``elza.restart.exitCode`` (výchozí 3) a správce služeb
ji spustí znovu; bez správce služeb se jen zastaví (viz
:doc:`04-konfigurace`).

Balíčky tam lze také přímo naimportovat; naimportovaný balíček se pak
aktualizuje z :file:`dpkg/` jako ostatní a vyhledávací index zaregistruje
pole jeho nových typů prvků po restartu. Balíček tam smazaný zůstane při
příštím startu smazaný, pokud jej klíč neuvádí.

Import institucí
----------------

Seznam archivů naimportujte ze souboru
:file:`data/all-institutions-import.xml` volbou *Import rejstříkových
hesel* v modulu *Archivní entity*.

Další kroky
-----------

- Nastavení reverzní proxy a HTTPS: :doc:`06-reverzni-proxy`.
- Nastavení zálohování: :doc:`10-zalohovani`.
- Napojení monitorování: :doc:`09-monitorovani`.
- Nastavení autentizace (LDAP, Kerberos, ...): :doc:`05-zabezpeceni`.
