============ Installation ============ There are two ways to install ELZA: - **Install scripts (recommended for Linux)** - a set of scripts that installs ELZA as a systemd service and automates deployment of new versions, database backups, health checks and unattended updates. - **Manual installation** from the binary distribution, on Linux or Windows. Both use the same binary distribution and the same configuration file. .. _install-scripts: Installation with the install scripts ===================================== The scripts and their documentation are published at https://get.lightcomp.com/elza/. They require Linux with systemd, PostgreSQL including its client tools (``pg_dump``), ``bash`` and ``curl``. The installation is started with: .. code-block:: bash curl -fsSL https://get.lightcomp.com/elza/elza-bootstrap.sh | bash -s -- --home /opt/elza The bootstrap script downloads the script bundle (verified by a checksum) into :file:`/opt/elza/scripts`, prepares the configuration file :file:`elza-env` and installs the systemd units. After editing :file:`elza-env` (at least the database connection), the first deployment is run with ``elza-deploy``. The scripts provide these commands: - ``elza-deploy`` - installs or upgrades the application: stops the service, backs up the database, downloads the distribution, switches atomically to the new version, starts the service and checks that it runs. - ``elza-backup`` - backs up the database with ``pg_dump`` and removes old backups. - ``elza-health`` - checks the state of the application and optionally reports it to a supervision service (see :ref:`monitoring-reporting`). - ``elza-update`` - unattended upgrade to a new version. The database still has to be prepared as described in :ref:`install-database`. The configuration of ELZA itself (:file:`elza.yaml`) is described in :doc:`04-configuration`. Manual installation =================== Contents of the distribution ---------------------------- The binary distribution is a ZIP file containing: - :file:`server/elza-tomcat-.jar` - the application with the embedded web server, - :file:`server/config/elza.yaml` - a sample configuration, - :file:`server/config/csc-metrics.json` - the list of metrics reported to a supervision service (see :doc:`09-monitoring`), - :file:`packages/` - the base packages: ``package-cz-base`` (code lists) and ``rules-cz-zp2015`` (description rules ZP2015), - :file:`data/all-institutions-import.xml` - the list of accredited archival institutions in the Czech Republic, - :file:`readme.txt` - a short installation overview. .. _install-database: Preparing the database ---------------------- #. Create a database user for ELZA, for example ``elza``. Do not use a superuser account for the application. #. Create an empty database owned by this user: .. code-block:: bash createdb -O elza -E UTF8 -l cs_CZ.UTF-8 -T template0 elza The locale determines the sorting of texts done by the database. Use the locale of the archival description (Czech for Czech archives); available locales are listed by ``locale -a``. On Windows the name is, for example, ``Czech_Czechia.1250``. The locale cannot be changed after the database has been created. #. Enable the PostGIS extension in the database. Creating an extension requires superuser rights, so run it as the ``postgres`` user: .. code-block:: bash psql -U postgres -d elza -c "CREATE EXTENSION postgis;" The tables are created by ELZA at its first start. Directory layout ---------------- ELZA needs an installation directory and a working directory, for example: - :file:`/opt/elza/server` - the JAR file and :file:`config/elza.yaml`, - :file:`/opt/elza/work` - the working directory. On Windows, for example :file:`D:\\Elza\\server` and :file:`D:\\Elza\\work`. Create a dedicated operating system user for the service, owning the working directory with full access to it. On Linux, keep a symbolic link to the current JAR, so that an upgrade only changes the link: :file:`/opt/elza/server/elza-tomcat.jar` -> :file:`elza-tomcat-3.4.7.jar`. The working directory contains: - :file:`dms/` - binary files (attachments, outputs, publications, import batches). Its structure is managed by ELZA and must not be modified by hand; it is backed up together with the database (see :doc:`10-backup`). - :file:`dpkg/` - packages loaded at startup (see :ref:`install-packages`). - :file:`log/` - log files, when configured as in the sample configuration. - other working data, which ELZA recreates when missing. Configuration ------------- Copy :file:`server/config/elza.yaml` to :file:`config/elza.yaml` next to the JAR file and set at least: - the database connection (``elza.data.url``, ``elza.data.user``, ``elza.data.pass``), - the working directory (``elza.workingDir``), - the packages the installation uses (``elza.packages.enabled``, see :ref:`install-packages`). .. code-block:: yaml elza: data: url: jdbc:postgresql://localhost/elza user: elza pass: secret workingDir: /opt/elza/work logFile: ${elza.workingDir}/log/elza.log siemLogFile: ${elza.workingDir}/log/siem.log packages: enabled: [CZ_BASE, ZP2015] All other settings are described in :doc:`04-configuration`. Running as a service -------------------- Before setting up the service, start the application once from the installation directory to check the configuration: .. code-block:: bash java -jar elza-tomcat.jar At the first start, ELZA creates the database schema. The application is ready when the log reports that it has started; it listens on port 8080. Example systemd unit (: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 Adjust the heap size (``-Xmx``) to the available memory. The working directory of the process must be the installation directory, so that :file:`config/elza.yaml` is found. Enable and start the service with ``systemctl enable --now elza``. With ``Restart=on-failure`` the restart from the administration works as it is: the application exits with code 3, which the unit restarts on (see :doc:`04-configuration`). On Windows, ELZA can be run as a service with a service wrapper such as WinSW or NSSM, running the same ``java -jar`` command. See also the `Spring Boot deployment documentation `_. First start =========== .. _install-first-admin: First administrator ------------------- While the database contains no user, the application shows the *Initial setup* dialog instead of the login. It creates the first administrator: a user with a password and the administrator permission. .. warning:: Until the first administrator exists, anyone who opens the application can create it. Create the administrator right after the first start, before the application is made available on the network, or set it in the configuration (see :ref:`install-users-from-config`). After *Create administrator*, the application logs in as the new administrator. The password must meet the password rules (see :doc:`05-security`); after the installation, all rules are off. The first administrator has no person (archival entity) assigned, because the archival entities need the packages loaded first. The person can be assigned later in *Administration* > *Users* > *Edit*. Other users are created as usual, with a person. .. _install-admin-from-config: .. _install-users-from-config: Users from the configuration ---------------------------- Users can also be set in the configuration, as a list of user names and passwords in ``elza.security.override``. ELZA applies the list at every startup, whether or not the database contains users: - If no user of this name exists, it is created as an administrator: a user without a person, with the administrator permission and **without a password in the database**. On an empty database, the *Initial setup* dialog is then not shown. - If the user exists, its password and permissions in the database do not change; a deactivated user is activated. A listed user logs in with their own password (from the database, if they have one) **or** with the configured password; one of them is enough. A login with the configured password does not require a password change, and the configured password does not expire. The user can change their password in the application; the configured password keeps working as long as the user is listed. Once the user is removed from the list, only their own password works - a user created from the list who never set one cannot log in until an administrator sets a password. The configured password never applies to the default user. .. code-block:: yaml elza: security: override: - username: jan.novak password: a-password - username: petr.svoboda password: another-password .. list-table:: :header-rows: 1 :widths: 36 18 46 * - Key - Default - Meaning * - ``elza.security.override[].username`` - (none) - User name. * - ``elza.security.override[].password`` - (none) - Password, as plain text. It is not stored in the database; a password that does not meet the password rules is only reported as a warning in the application log. An entry without a user name or a password, a user listed twice, or the removed keys ``elza.security.admin.username`` / ``.password`` stop the startup with an error. If one user cannot be applied (for example its name is the name of the default user while the default user is enabled), ELZA logs an error, applies the others and starts anyway. Every startup writes a warning for each listed user to the application log (the password itself is never logged). With ``elza.siemLogFile`` set, the security audit log records that the configured password is active (``override_active``), the user created or activated, a failure, and every login with the configured password (``authentication_type`` ``OVERRIDE``); see :doc:`05-security`. .. warning:: The password is stored in plain text and is valid next to the user's own password. Remove the entry from :file:`elza.yaml` once it is no longer needed, for example after the first start. Default user ------------ A new installation can also be accessed with the built-in default user (``admin`` with the password ``admin``), which has administrator rights; the *Sign in* button of the *Initial setup* dialog opens the login form for it. Use it only to create the administrator accounts, then disable it with ``elza.security.allowDefaultUser: false`` and restart the application. While the default user is enabled, the first administrator cannot be named ``admin``. See :doc:`05-security`. .. _install-packages: Loading the packages -------------------- ELZA needs the code lists and description rules from the packages in :file:`packages/`. The recommended way is to copy the ZIP files into the :file:`dpkg/` subdirectory of the working directory: at every start, ELZA loads each package from this directory whose version is newer than the imported one. An upgrade then only replaces the files in :file:`dpkg/` together with the JAR. Which packages of the directory the installation uses is set by ``elza.packages.enabled``, a list of package codes. At every start, ELZA loads from :file:`dpkg/` the packages that are already imported and the packages the list names, together with the packages they depend on; the other files of the directory are left alone. A package that a new version of ELZA adds to :file:`packages/` is therefore not imported into an existing installation unless it is listed. The distribution contains: - ``CZ_BASE`` - entity description according to the Czech CAM, and the shared code lists; required by ``ZP2015``, - ``ZP2015`` - the Czech description rules, - ``ISAAR_CPF`` - entity description according to the international standard ISAAR(CPF), in English; for installations outside the Czech practice or alongside ``CZ_BASE``. - ``ISADG`` - archival description of fonds according to the international standard ISAD(G), in English; needs ``ISAAR_CPF`` for creators and access points. See the user guide. Set the key before the first start. On an empty database without the key, ELZA imports every package of the directory. The log of the start lists the packages imported and skipped. .. note:: If :file:`dpkg/` contains an older version of a package than the one already imported, the application does not start. Remove the old file. *Administration* > *Package management* lists the packages of :file:`dpkg/` that are not loaded, with what the next start does with each of them. *Load at the next start* marks a package: the mark is a package record without content, and the next start imports the file (with the packages it requires). *Cancel the mark* removes it. The page then reminds that a restart is needed and offers *Restart the application*: the application exits with the code ``elza.restart.exitCode`` (3 by default) and the service manager starts it again; without a service manager it only stops (see :doc:`04-configuration`). Packages can also be imported there directly; an imported package is then upgraded from :file:`dpkg/` like the others, and the search index registers the fields of its new item types after a restart. A package deleted there stays deleted at the next start unless the key lists it. Importing institutions ---------------------- Import the list of archival institutions from :file:`data/all-institutions-import.xml` with *Archival entity import* in the *Archival entities* module. Next steps ---------- - Set up the reverse proxy and HTTPS: :doc:`06-reverse-proxy`. - Set up backups: :doc:`10-backup`. - Connect the monitoring: :doc:`09-monitoring`. - Configure authentication (LDAP, Kerberos, ...): :doc:`05-security`.