Koha Ukraine Wiki - Внесок користувача [uk]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-17T16:09:54Z

Dubyk: /* 5. Перемикання на Elasticsearch та побудова індексів */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: yes
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: yes
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

== Пошуковий рушій ==
=== Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''' (типове значення в базі даних — '''Zebra'''; саме встановлення пакунка koha-elasticsearch і заповнення блоку <elasticsearch> це значення НЕ змінюють — перемикання завжди окремий ручний крок, див. нижче). У цій редакції інструкції за основний рушій обрано Elasticsearch — підтримка кирилиці реалізується штатним плагіном ICU, а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch (містить CLI-утиліти koha-elasticsearch і koha-es-indexer) ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок '''ELASTICSEARCH_SERVER''' у конфіг-файлі екземпляра (вище, розділ „Створення екземпляра“) — це ЛИШЕ адреса: koha-create підставляє її прямою заміною плейсхолдера __ELASTICSEARCH_SERVER__ у шаблоні /etc/koha/sites/<instance>/koha-conf.xml (перевірено в debian/scripts/koha-create офіційного репозиторію Koha). Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і SearchEngine НЕ перемикає.

'''Щодо версії 26.05:''' беріть щонайменше '''26.05.01''', не 26.05.00 — у 26.05.00 була помилка індексації Elasticsearch (Bug 42485, "Elasticsearch dynamic mapping date detection causes indexing failures with ARRAY MARC format"), виправлена в 26.05.01 (там-таки закрито і CVE-2026-6428). Для LTS 24.11 так само — беріть останній maintenance-випуск гілки, не .00.

==== 1. Встановлення сервера Elasticsearch (окремо від koha-elasticsearch) ====
Koha 26.05 орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
Пакунок під час установлення один раз друкує в консоль автогенерований пароль користувача elastic та інформацію про security auto-configuration (самопідписаний CA й сертифікати створюються в /etc/elasticsearch/certs/). Для автоматизації пароль зручніше не ловити з логу apt, а перегенерувати окремою командою (крок 3 нижче).
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Швидка перевірка (без валідації TLS-сертифіката):
curl -k https://localhost:9200 -u elastic
Коректніший варіант для скриптів автоматизації (з валідацією CA, який ES сам згенерував):
curl --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic https://localhost:9200

==== 2. Плагіни ICU та українського аналізатора ====
Плагін '''analysis-icu''' Koha вимагає обов'язково: власний файл Koha admin/searchengine/elasticsearch/index_config.yaml напряму визначає аналізатори analyzer_standard, analyzer_phrase, analyzer_stdno через icu_tokenizer і фільтр icu_folding — без плагіна Koha не зможе навіть створити індекс. Плагін '''analysis-ukrainian''' (офіційна документація: https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-ukrainian.html) реєструє в Elasticsearch аналізатор ukrainian на основі лематизатора Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik).
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
''Увага: обидва плагіни прив'язані до конкретної збірки Elasticsearch. Після кожного оновлення пакунка elasticsearch їх потрібно перевстановити (remove, потім install) — інакше Koha не зможе відкрити індекс: analyzer_phrase з index_config.yaml посилається саме на icu_folding, і без плагіна ES поверне помилку на кшталт "failed to find filter under name [icu_folding]".''

'''Чесно про analysis-ukrainian:''' сам плагін лише робить аналізатор ukrainian ДОСТУПНИМ у Elasticsearch. Koha його ніде автоматично не використовує — у стандартному index_config.yaml немає жодної згадки українського аналізатора, усі мови проходять через один і той самий analyzer_standard (icu_tokenizer + icu_folding). Щоб реально задіяти лематизацію для української, потрібно:
# скопіювати собі /usr/share/koha/intranet/cgi-bin/admin/searchengine/elasticsearch/index_config.yaml і додати в копії власний аналізатор на основі ukrainian;
# вказати шлях до копії в koha-conf.xml через <elasticsearch_index_config> (рядок-заготовка вже є в шаблоні koha-conf-site.xml.in, лише закоментований);
# за потреби так само перевизначити мапінг полів через <elasticsearch_index_mappings>;
# застосувати зміни через сторінку /cgi-bin/koha/admin/searchengine/elasticsearch/mappings.pl?op=reset&i_know_what_i_am_doing=1&reset_fields=1 і повний переіндекс (крок 5).
Це предмет окремого тестування на тестовому екземплярі, а не «встановили плагін — і все запрацювало». Без цього кастомізування ви отримуєте лише icu_tokenizer + icu_folding — це вже помітно кращий пошук кирилицею за посимвольну токенізацію, але не повноцінну лематизацію словоформ.

==== 3. Автентифікація (ES 8.x має security увімкненою за замовчуванням) ====
Скидаємо/встановлюємо пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
(для автоматизації додайте -b/--batch, щоб пропустити підтвердження, і -i, якщо задаєте пароль самі, а не автогенерований)
Прописуємо ці дані в /etc/koha/sites/ukr_unimarc/koha-conf.xml — у блоці <elasticsearch> елементи '''userinfo''' і '''use_https''' вже присутні в офіційному шаблоні koha-conf-site.xml.in, просто закоментовані; розкоментовуємо й заповнюємо:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>
Альтернатива без userinfo — вписати user:pass прямо в адресу сервера (це також штатно підтримується):
<server>elastic:ВАШ_ПАРОЛЬ@127.0.0.1:9200</server>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Задокументоване на Koha Wiki рішення — додати параметр handle_args, який Koha прозоро передає в конструктор Search::Elasticsearch, а той — у HTTP::Tiny (саме HTTP::Tiny і підтримує ключ verify_SSL; handle_args як параметр Search::Elasticsearch::Role::Cxn підтверджено офіційною документацією модуля):
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть koha-common і Plack/індексувальні служби екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Перемикання на Elasticsearch та побудова індексів ====
1) Адміністрація → Глобальні системні преференції → Пошук → '''SearchEngine''' → значення '''Elasticsearch''' → Зберегти. Крок обов'язковий: типове значення в базі — Zebra, і жоден з попередніх кроків його не змінює.
2) Перша повна побудова індексів, з прапорцем -d (видалити старий індекс перед перебудовою — критично при першому переході чи після зміни index_config.yaml чи mappings.yaml):
sudo koha-elasticsearch --rebuild -d -v ukr_unimarc
(--rebuild — обов'язкова дія команди, без неї скрипт завершиться з помилкою; без -b/-a перебудовуються ОБИДВА типи записів — це поведінка за замовчуванням, тож вказувати -b і -a одночасно немає сенсу, це виходить еквівалентно відсутності обох прапорців)
3) Запускаємо фонову індексувальну службу (підхоплює подальші зміни в БД без ручних перебудов):
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Швидка перевірка, що Koha дійсно використовує ES, а не залишилась на Zebra: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує).

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Практичне налаштування: лематизація analysis-ukrainian для вибраних полів ====
Це розширення пункту 2: конкретний, перевірений у джерельному коді Koha 26.05.01 спосіб реально задіяти аналізатор ukrainian, без правок Perl-коду.

'''Механізм перевизначення.''' У шаблоні koha-conf-site.xml.in закладено (закоментовано) три незалежні override-файли, кожен зчитується напряму в Koha/SearchEngine/Elasticsearch.pm через C4::Context->config(...):



Для нашої задачі index_config.yaml чіпати не потрібно (аналізатори типу ukrainian реєструються самим ES-плагіном, а не в цьому файлі) — працюємо лише з field_config.yaml (типи полів) і mappings.yaml (яке поле яким типом індексується).

'''Крок 1 — копіюємо типові файли собі''' (оригінали в /usr/share/koha перезаписуються при кожному оновленні пакунка koha-common, редагувати їх напряму не можна):
sudo mkdir -p /etc/koha/sites/ukr_unimarc/searchengine/elasticsearch
sudo cp /usr/share/koha/intranet/cgi-bin/admin/searchengine/elasticsearch/field_config.yaml \
/usr/share/koha/intranet/cgi-bin/admin/searchengine/elasticsearch/mappings.yaml \
/etc/koha/sites/ukr_unimarc/searchengine/elasticsearch/

'''Крок 2 — у копії field_config.yaml додаємо новий тип поруч з "default"''', зберігаючи ті самі під-поля phrase/raw/ci_raw (вони й далі потрібні для точного пошуку, сортування й фільтрів — міняємо лише основний аналізатор):
default_uk:
type: text
analyzer: ukrainian
search_analyzer: ukrainian
fields:
phrase:
type: text
analyzer: analyzer_phrase
search_analyzer: analyzer_phrase
raw:
type: keyword
normalizer: nfkc_cf_normalizer
ci_raw:
type: keyword
normalizer: icu_folding_normalizer

'''Крок 3 — у копії mappings.yaml точково міняємо тип потрібних полів''' з default на default_uk. Файл величезний (у 26.05.01 — понад 4000 рядків), редагуємо конкретні блоки. Розумний мінімум для першого запуску — поля, де морфологічна варіативність пошукового запиту найбільше заважає читачам (заголовок, автор, предметні рубрики):
title:
label: title
type: default_uk # було: default
...
Аналогічно знаходимо блоки author та su (предметні рубрики) і міняємо їм type. Інші поля (ідентифікатори, дати, stdno-подібні) не чіпаємо.

'''Крок 4 — прописуємо шляхи в koha-conf.xml''' (розкоментовуємо, index_mappings не чіпаємо — лишаємо закоментованим, якщо не змінювали index_config.yaml):
<elasticsearch_field_config>/etc/koha/sites/ukr_unimarc/searchengine/elasticsearch/field_config.yaml</elasticsearch_field_config>
<elasticsearch_index_mappings>/etc/koha/sites/ukr_unimarc/searchengine/elasticsearch/mappings.yaml</elasticsearch_index_mappings>

'''Крок 5 — застосовуємо й переіндексовуємо.''' Зміни мапінгу застосовуються лише через reset у веб-інтерфейсі (це прямо застережено коментарем у самому шаблоні koha-conf-site.xml.in: reset скидає й будь-які зміни, зроблені раніше через Search engine configuration UI):
https://<staff-інтерфейс>/cgi-bin/koha/admin/searchengine/elasticsearch/mappings.pl?op=reset&i_know_what_i_am_doing=1&reset_fields=1
Далі повний переіндекс:
sudo koha-elasticsearch --rebuild -d -v ukr_unimarc

''Не перевірено емпірично (у пісочниці немає робочого Elasticsearch): як саме аналізатор ukrainian обробляє не-українські токени (латиницею написані прізвища іноземних авторів, назви іншими мовами) — найімовірніше, пропускає без лематизації, але без реального тесту на змішаномовних записах стверджувати напевно не можу. Перевірте на тестовому екземплярі з реальними даними, перш ніж переносити на прод.''

'''Чому не "і ICU, і лематизація одночасно" (multi-field з бустом у запиті).''' Архітектурно можна додати ukrainian ще одним під-полем (fields:) поруч із phrase/raw/ci_raw, зберігши analyzer_standard основним. Але для основного ключового пошуку Koha (Koha/SearchEngine/Elasticsearch/QueryBuilder.pm, sub build_query) будує query_string по базовому імені поля з його типовим analyzer/search_analyzer — довільні додаткові під-поля в цей запит автоматично не потрапляють. Суфікси .phrase/.raw/.ci_raw жорстко прописані в коді лише для конкретних сценаріїв (точні збіги, сортування, префіксний пошук). Щоб і новий .ukrainian-варіант реально брав участь у звичайному пошуку (з бустом поруч з основним полем), знадобиться правити сам QueryBuilder.pm — тобто повертаємось до проблеми, заради якої відмовлялись від Zebra: такий патч не переживає оновлення koha-common. Тому в цій інструкції — свідомий компроміс: конфігураційна заміна аналізатора на вибраних полях (Кроки 1–5), без патчів Perl-коду, ціною втрати ICU-фолдингу саме на цих полях.

=== Zebra з підтримкою кирилиці (стара альтернатива) ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна додати рядок Enabled: no у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: no
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-16T16:03:19Z

Dubyk: /* Альтернатива (legacy): Zebra з підтримкою кирилиці */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: yes
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: yes
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

== Пошуковий рушій ==
=== Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''' (типове значення в базі даних — '''Zebra'''; саме встановлення пакунка koha-elasticsearch і заповнення блоку <elasticsearch> це значення НЕ змінюють — перемикання завжди окремий ручний крок, див. нижче). У цій редакції інструкції за основний рушій обрано Elasticsearch — підтримка кирилиці реалізується штатним плагіном ICU, а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch (містить CLI-утиліти koha-elasticsearch і koha-es-indexer) ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок '''ELASTICSEARCH_SERVER''' у конфіг-файлі екземпляра (вище, розділ „Створення екземпляра“) — це ЛИШЕ адреса: koha-create підставляє її прямою заміною плейсхолдера __ELASTICSEARCH_SERVER__ у шаблоні /etc/koha/sites/<instance>/koha-conf.xml (перевірено в debian/scripts/koha-create офіційного репозиторію Koha). Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і SearchEngine НЕ перемикає.

'''Щодо версії 26.05:''' беріть щонайменше '''26.05.01''', не 26.05.00 — у 26.05.00 була помилка індексації Elasticsearch (Bug 42485, "Elasticsearch dynamic mapping date detection causes indexing failures with ARRAY MARC format"), виправлена в 26.05.01 (там-таки закрито і CVE-2026-6428). Для LTS 24.11 так само — беріть останній maintenance-випуск гілки, не .00.

==== 1. Встановлення сервера Elasticsearch (окремо від koha-elasticsearch) ====
Koha 26.05 орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
Пакунок під час установлення один раз друкує в консоль автогенерований пароль користувача elastic та інформацію про security auto-configuration (самопідписаний CA й сертифікати створюються в /etc/elasticsearch/certs/). Для автоматизації пароль зручніше не ловити з логу apt, а перегенерувати окремою командою (крок 3 нижче).
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Швидка перевірка (без валідації TLS-сертифіката):
curl -k https://localhost:9200 -u elastic
Коректніший варіант для скриптів автоматизації (з валідацією CA, який ES сам згенерував):
curl --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic https://localhost:9200

==== 2. Плагіни ICU та українського аналізатора ====
Плагін '''analysis-icu''' Koha вимагає обов'язково: власний файл Koha admin/searchengine/elasticsearch/index_config.yaml напряму визначає аналізатори analyzer_standard, analyzer_phrase, analyzer_stdno через icu_tokenizer і фільтр icu_folding — без плагіна Koha не зможе навіть створити індекс. Плагін '''analysis-ukrainian''' (офіційна документація: https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-ukrainian.html) реєструє в Elasticsearch аналізатор ukrainian на основі лематизатора Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik).
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
''Увага: обидва плагіни прив'язані до конкретної збірки Elasticsearch. Після кожного оновлення пакунка elasticsearch їх потрібно перевстановити (remove, потім install) — інакше Koha не зможе відкрити індекс: analyzer_phrase з index_config.yaml посилається саме на icu_folding, і без плагіна ES поверне помилку на кшталт "failed to find filter under name [icu_folding]".''

'''Чесно про analysis-ukrainian:''' сам плагін лише робить аналізатор ukrainian ДОСТУПНИМ у Elasticsearch. Koha його ніде автоматично не використовує — у стандартному index_config.yaml немає жодної згадки українського аналізатора, усі мови проходять через один і той самий analyzer_standard (icu_tokenizer + icu_folding). Щоб реально задіяти лематизацію для української, потрібно:
# скопіювати собі /usr/share/koha/intranet/cgi-bin/admin/searchengine/elasticsearch/index_config.yaml і додати в копії власний аналізатор на основі ukrainian;
# вказати шлях до копії в koha-conf.xml через <elasticsearch_index_config> (рядок-заготовка вже є в шаблоні koha-conf-site.xml.in, лише закоментований);
# за потреби так само перевизначити мапінг полів через <elasticsearch_index_mappings>;
# застосувати зміни через сторінку /cgi-bin/koha/admin/searchengine/elasticsearch/mappings.pl?op=reset&i_know_what_i_am_doing=1&reset_fields=1 і повний переіндекс (крок 5).
Це предмет окремого тестування на тестовому екземплярі, а не «встановили плагін — і все запрацювало». Без цього кастомізування ви отримуєте лише icu_tokenizer + icu_folding — це вже помітно кращий пошук кирилицею за посимвольну токенізацію, але не повноцінну лематизацію словоформ.

==== 3. Автентифікація (ES 8.x має security увімкненою за замовчуванням) ====
Скидаємо/встановлюємо пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
(для автоматизації додайте -b/--batch, щоб пропустити підтвердження, і -i, якщо задаєте пароль самі, а не автогенерований)
Прописуємо ці дані в /etc/koha/sites/ukr_unimarc/koha-conf.xml — у блоці <elasticsearch> елементи '''userinfo''' і '''use_https''' вже присутні в офіційному шаблоні koha-conf-site.xml.in, просто закоментовані; розкоментовуємо й заповнюємо:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>
Альтернатива без userinfo — вписати user:pass прямо в адресу сервера (це також штатно підтримується):
<server>elastic:ВАШ_ПАРОЛЬ@127.0.0.1:9200</server>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Задокументоване на Koha Wiki рішення — додати параметр handle_args, який Koha прозоро передає в конструктор Search::Elasticsearch, а той — у HTTP::Tiny (саме HTTP::Tiny і підтримує ключ verify_SSL; handle_args як параметр Search::Elasticsearch::Role::Cxn підтверджено офіційною документацією модуля):
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть koha-common і Plack/індексувальні служби екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Перемикання на Elasticsearch та побудова індексів ====
1) Адміністрація → Глобальні системні преференції → Пошук → '''SearchEngine''' → значення '''Elasticsearch''' → Зберегти. Крок обов'язковий: типове значення в базі — Zebra, і жоден з попередніх кроків його не змінює.
2) Перша повна побудова індексів, з прапорцем -d (видалити старий індекс перед перебудовою — критично при першому переході чи після зміни index_config.yaml чи mappings.yaml):
sudo koha-elasticsearch --rebuild -d -v ukr_unimarc
(--rebuild — обов'язкова дія команди, без неї скрипт завершиться з помилкою; без -b/-a перебудовуються ОБИДВА типи записів — це поведінка за замовчуванням, тож вказувати -b і -a одночасно немає сенсу, це виходить еквівалентно відсутності обох прапорців)
3) Запускаємо фонову індексувальну службу (підхоплює подальші зміни в БД без ручних перебудов):
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Швидка перевірка, що Koha дійсно використовує ES, а не залишилась на Zebra: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує).

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

=== Zebra з підтримкою кирилиці (стара альтернатива) ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна додати рядок Enabled: no у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: no
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-16T16:02:26Z

Dubyk: /* Пошуковий рушій: Elasticsearch (рекомендовано) */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: yes
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: yes
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

== Пошуковий рушій ==
=== Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''' (типове значення в базі даних — '''Zebra'''; саме встановлення пакунка koha-elasticsearch і заповнення блоку <elasticsearch> це значення НЕ змінюють — перемикання завжди окремий ручний крок, див. нижче). У цій редакції інструкції за основний рушій обрано Elasticsearch — підтримка кирилиці реалізується штатним плагіном ICU, а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch (містить CLI-утиліти koha-elasticsearch і koha-es-indexer) ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок '''ELASTICSEARCH_SERVER''' у конфіг-файлі екземпляра (вище, розділ „Створення екземпляра“) — це ЛИШЕ адреса: koha-create підставляє її прямою заміною плейсхолдера __ELASTICSEARCH_SERVER__ у шаблоні /etc/koha/sites/<instance>/koha-conf.xml (перевірено в debian/scripts/koha-create офіційного репозиторію Koha). Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і SearchEngine НЕ перемикає.

'''Щодо версії 26.05:''' беріть щонайменше '''26.05.01''', не 26.05.00 — у 26.05.00 була помилка індексації Elasticsearch (Bug 42485, "Elasticsearch dynamic mapping date detection causes indexing failures with ARRAY MARC format"), виправлена в 26.05.01 (там-таки закрито і CVE-2026-6428). Для LTS 24.11 так само — беріть останній maintenance-випуск гілки, не .00.

==== 1. Встановлення сервера Elasticsearch (окремо від koha-elasticsearch) ====
Koha 26.05 орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
Пакунок під час установлення один раз друкує в консоль автогенерований пароль користувача elastic та інформацію про security auto-configuration (самопідписаний CA й сертифікати створюються в /etc/elasticsearch/certs/). Для автоматизації пароль зручніше не ловити з логу apt, а перегенерувати окремою командою (крок 3 нижче).
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Швидка перевірка (без валідації TLS-сертифіката):
curl -k https://localhost:9200 -u elastic
Коректніший варіант для скриптів автоматизації (з валідацією CA, який ES сам згенерував):
curl --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic https://localhost:9200

==== 2. Плагіни ICU та українського аналізатора ====
Плагін '''analysis-icu''' Koha вимагає обов'язково: власний файл Koha admin/searchengine/elasticsearch/index_config.yaml напряму визначає аналізатори analyzer_standard, analyzer_phrase, analyzer_stdno через icu_tokenizer і фільтр icu_folding — без плагіна Koha не зможе навіть створити індекс. Плагін '''analysis-ukrainian''' (офіційна документація: https://www.elastic.co/guide/en/elasticsearch/plugins/current/analysis-ukrainian.html) реєструє в Elasticsearch аналізатор ukrainian на основі лематизатора Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik).
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
''Увага: обидва плагіни прив'язані до конкретної збірки Elasticsearch. Після кожного оновлення пакунка elasticsearch їх потрібно перевстановити (remove, потім install) — інакше Koha не зможе відкрити індекс: analyzer_phrase з index_config.yaml посилається саме на icu_folding, і без плагіна ES поверне помилку на кшталт "failed to find filter under name [icu_folding]".''

'''Чесно про analysis-ukrainian:''' сам плагін лише робить аналізатор ukrainian ДОСТУПНИМ у Elasticsearch. Koha його ніде автоматично не використовує — у стандартному index_config.yaml немає жодної згадки українського аналізатора, усі мови проходять через один і той самий analyzer_standard (icu_tokenizer + icu_folding). Щоб реально задіяти лематизацію для української, потрібно:
# скопіювати собі /usr/share/koha/intranet/cgi-bin/admin/searchengine/elasticsearch/index_config.yaml і додати в копії власний аналізатор на основі ukrainian;
# вказати шлях до копії в koha-conf.xml через <elasticsearch_index_config> (рядок-заготовка вже є в шаблоні koha-conf-site.xml.in, лише закоментований);
# за потреби так само перевизначити мапінг полів через <elasticsearch_index_mappings>;
# застосувати зміни через сторінку /cgi-bin/koha/admin/searchengine/elasticsearch/mappings.pl?op=reset&i_know_what_i_am_doing=1&reset_fields=1 і повний переіндекс (крок 5).
Це предмет окремого тестування на тестовому екземплярі, а не «встановили плагін — і все запрацювало». Без цього кастомізування ви отримуєте лише icu_tokenizer + icu_folding — це вже помітно кращий пошук кирилицею за посимвольну токенізацію, але не повноцінну лематизацію словоформ.

==== 3. Автентифікація (ES 8.x має security увімкненою за замовчуванням) ====
Скидаємо/встановлюємо пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
(для автоматизації додайте -b/--batch, щоб пропустити підтвердження, і -i, якщо задаєте пароль самі, а не автогенерований)
Прописуємо ці дані в /etc/koha/sites/ukr_unimarc/koha-conf.xml — у блоці <elasticsearch> елементи '''userinfo''' і '''use_https''' вже присутні в офіційному шаблоні koha-conf-site.xml.in, просто закоментовані; розкоментовуємо й заповнюємо:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>
Альтернатива без userinfo — вписати user:pass прямо в адресу сервера (це також штатно підтримується):
<server>elastic:ВАШ_ПАРОЛЬ@127.0.0.1:9200</server>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Задокументоване на Koha Wiki рішення — додати параметр handle_args, який Koha прозоро передає в конструктор Search::Elasticsearch, а той — у HTTP::Tiny (саме HTTP::Tiny і підтримує ключ verify_SSL; handle_args як параметр Search::Elasticsearch::Role::Cxn підтверджено офіційною документацією модуля):
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть koha-common і Plack/індексувальні служби екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Перемикання на Elasticsearch та побудова індексів ====
1) Адміністрація → Глобальні системні преференції → Пошук → '''SearchEngine''' → значення '''Elasticsearch''' → Зберегти. Крок обов'язковий: типове значення в базі — Zebra, і жоден з попередніх кроків його не змінює.
2) Перша повна побудова індексів, з прапорцем -d (видалити старий індекс перед перебудовою — критично при першому переході чи після зміни index_config.yaml чи mappings.yaml):
sudo koha-elasticsearch --rebuild -d -v ukr_unimarc
(--rebuild — обов'язкова дія команди, без неї скрипт завершиться з помилкою; без -b/-a перебудовуються ОБИДВА типи записів — це поведінка за замовчуванням, тож вказувати -b і -a одночасно немає сенсу, це виходить еквівалентно відсутності обох прапорців)
3) Запускаємо фонову індексувальну службу (підхоплює подальші зміни в БД без ручних перебудов):
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Швидка перевірка, що Koha дійсно використовує ES, а не залишилась на Zebra: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує).

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна додати рядок Enabled: no у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: no
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-14T13:07:11Z

Dubyk: /* Вимкнення оновлення Koha */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: yes
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: yes
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системним параметром '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна додати рядок Enabled: no у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: no
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-14T12:29:57Z

Dubyk: /* Підключення репозитарію Koha */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: yes
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Enabled: yes
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системним параметром '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-14T12:17:35Z

Dubyk: /* 8. Початкова індексація */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системним параметром '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-14T12:17:26Z

Dubyk: /* 6. Перезапуск служб */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системним параметром '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-14T12:16:50Z

Dubyk: /* Створення екземпляра */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системним параметром '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-14T12:16:38Z

Dubyk: /* ports.conf */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системним параметром '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-14T12:16:28Z

Dubyk: /* ports.conf */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системним параметром '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-14T12:16:12Z

Dubyk: /* koha-ukr-unimarc-site.conf */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системним параметром '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-14T12:15:58Z

Dubyk: /* koha-ukr-unimarc-site.conf */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системним параметром '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-14T12:15:37Z

Dubyk: /* DNS */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системним параметром '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-14T12:12:23Z

Dubyk: /* Пошуковий рушій: Elasticsearch (рекомендовано) */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системним параметром '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-14T11:50:24Z

Dubyk: /* Варіант з доменами */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

''Зауваження: символ підкреслення не використовуйте для доменів (є не коректним символом у DNS-іменах). Це важливо зокрема для отримання сертифіката Let's Encrypt.''

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-14T11:43:53Z

Dubyk: /* Команда „koha-create“ */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T15:22:11Z

Dubyk: /* Встановлення БД MariaDB та допоміжних пакунків */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

===Інший порт для phpmyadmin (опційно)===
Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:19:36Z

Dubyk: /* Оновлення Koha */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 26.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:18:30Z

Dubyk: /* 5. Індексація та перемикання Koha на Elasticsearch */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 5. Індексація та перемикання Koha на Elasticsearch ====
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:18:05Z

Dubyk: /* 6. Початкова індексація */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

=== 5. Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 8. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:17:53Z

Dubyk: /* 5. Перемкнути системне налаштування пошукового рушія */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

=== 5. Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 7. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 6. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:17:29Z

Dubyk: /* 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ====
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

=== 5. Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 5. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 6. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:17:01Z

Dubyk: /* Пошуковий рушій: Elasticsearch (рекомендовано) */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

=== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ===
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

=== 5. Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 5. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 6. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:16:48Z

Dubyk: /* Пошуковий рушій: Elasticsearch (рекомендовано) */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

=== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ===
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

=== 5. Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 5. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 6. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Пошуковий рушій: Elasticsearch (рекомендовано) ==

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:16:36Z

Dubyk: /* 4. Перезапуск служб */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

=== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ===
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

=== 5. Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

==== 6. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 5. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 6. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Пошуковий рушій: Elasticsearch (рекомендовано) ==

=== Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:15:38Z

Dubyk: /* Особливість Debian 13 (trixie): HTTP::Tiny і TLS */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

=== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ===
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 4. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 5. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 6. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Пошуковий рушій: Elasticsearch (рекомендовано) ==

=== Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:15:26Z

Dubyk: /* 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

=== 4. Особливість Debian 13 (trixie): HTTP::Tiny і TLS ===
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

==== 4. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 5. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 6. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Пошуковий рушій: Elasticsearch (рекомендовано) ==

=== Особливість Debian 13 (trixie): HTTP::Tiny і TLS ===
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

=== Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:13:56Z

Dubyk: /* Плагіни ICU та українського аналізатора */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 5. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 6. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Пошуковий рушій: Elasticsearch (рекомендовано) ==

=== Особливість Debian 13 (trixie): HTTP::Tiny і TLS ===
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

=== Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:12:37Z

Dubyk: /* 2. Плагін analysis-icu (потрібен для коректного аналізу, зокрема нелатинських/кириличних текстів) */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагіни ICU та український аналізатор ====
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 5. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 6. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Пошуковий рушій: Elasticsearch (рекомендовано) ==

=== Плагіни ICU та українського аналізатора ===
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

=== Особливість Debian 13 (trixie): HTTP::Tiny і TLS ===
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

=== Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:10:25Z

Dubyk: /* Пошуковий рушій: Elasticsearch (рекомендовано) */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагін analysis-icu (потрібен для коректного аналізу, зокрема нелатинських/кириличних текстів) ====
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 5. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 6. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Пошуковий рушій: Elasticsearch (рекомендовано) ==

=== Плагіни ICU та українського аналізатора ===
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

=== Особливість Debian 13 (trixie): HTTP::Tiny і TLS ===
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

=== Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:09:56Z

Dubyk: /* Пошуковий рушій: Elasticsearch (рекомендовано) */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Встановлення сервера Elasticsearch (не входить у koha-elasticsearch) ====
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
#sudo systemctl daemon-reload
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

==== 2. Плагін analysis-icu (потрібен для коректного аналізу, зокрема нелатинських/кириличних текстів) ====
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 5. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 6. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Пошуковий рушій: Elasticsearch (рекомендовано) ==
Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

=== Встановлення сервера Elasticsearch ===
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

=== Плагіни ICU та українського аналізатора ===
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

=== Особливість Debian 13 (trixie): HTTP::Tiny і TLS ===
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

=== Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]

Обговорення:Встановлення Koha з репозитарію на ОС Debian

2026-07-13T13:05:44Z

Dubyk: /* Elasticsearch: доведення налаштування до робочого стану (пріоритет) */

= Встановлення АБІС Koha з репозитарію на ОС Debian =
Розглядається встановлення АБІС Koha версій '''24.11–26.05''' '''з репозитарію''' [http://debian.koha-community.org/ debian.koha-community.org] на ОС '''Debian 13 (trixie)''' — поточному стабільному релізі Debian.
На даний час це найбільш протестований і розповсюджений варіант.
Окрім цього ще є варіант [[Встановлення Koha з джерела на ОС Debian|встановлення АБІС Koha з джерельних кодів]], що є дещо більш гнучким щодо налаштування, але і складнішим.

'''Стан документа''' (редакція липень 2026 р.): перехід на Debian 13 (trixie) як основну ОС; актуалізовано таблицю версій Koha; пошуковим рушієм за замовчуванням у цій інструкції обрано '''Elasticsearch''' (з плагінами ICU та українського аналізатора) замість Zebra; варіант із патчем кирилиці для Zebra залишено нижче як legacy-альтернатива для тих, хто ще не перейшов. Номери версій Koha та Debian зсуваються що 6–24 місяці — перед встановленням звіряйте таблицю нижче з посиланнями на Koha Wiki.

Див. також
* [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Debian Koha & Debian] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Category:Installation Category:Installation] на Koha Wiki
* [https://wiki.koha-community.org/wiki/Koha_on_ubuntu_-_packages Koha on ubuntu - packages] на Koha Wiki

= Встановлення ОС Debian GNU/Linux 13 (trixie) =
Див. також:
* https://www.debian.org/releases/trixie/ — сторінка релізу Debian 13 trixie
* https://d-i.debian.org/manual/uk.amd64/index.html Debian GNU/Linux гайд інсталяції
Перевірка поточної версії Debian:
lsb_release -d
Щодо сумісності Коха з іншими версіями ОС див.
* [https://wiki.koha-community.org/wiki/System_requirements_and_recommendations Системні вимоги та рекомендації] (англ.)

'''Примітка щодо Debian 12 (bookworm).''' Станом на липень 2026 р. bookworm має статус oldstable: Koha на ньому й далі працює і підтримується пакунками debian.koha-community.org, але нові інсталяції варто розгортати вже на trixie. Якщо йдеться не про нову інсталяцію, а про оновлення наявного сервера з bookworm на trixie — дотримуйтесь офіційного порядку: спершу довести bookworm до останніх оновлень, і лише тоді переходити на trixie (а не встановлювати систему „з нуля“).

== Підключення гілок non-free та contrib для пакунків Дебіан ==
Перевіряємо у /etc/apt/sources.list чи підключені гілки non-free та contrib
sudo mc -e /etc/apt/sources.list
deb http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-proposed-updates contrib main non-free non-free-firmware

deb http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian/ trixie-backports contrib main non-free non-free-firmware

deb http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware
deb-src http://deb.debian.org/debian-security/ trixie-security contrib main non-free non-free-firmware

sudo apt-get update
sudo apt-get upgrade

= Попередні налаштування =
== Локаль з UTF-8 ==
Перевірка локалі:
sudo locale
у виводі повинно бути магічне „'''UTF-8'''“ (en.UTF-8 тощо), наприклад для України
LANG=uk_UA.UTF-8
LANGUAGE=
LC_CTYPE="uk_UA.UTF-8"
LC_NUMERIC="uk_UA.UTF-8"
LC_TIME="uk_UA.UTF-8"
LC_COLLATE="uk_UA.UTF-8"
LC_MONETARY="uk_UA.UTF-8"
LC_MESSAGES="uk_UA.UTF-8"
LC_PAPER="uk_UA.UTF-8"
LC_NAME="uk_UA.UTF-8"
LC_ADDRESS="uk_UA.UTF-8"
LC_TELEPHONE="uk_UA.UTF-8"
LC_MEASUREMENT="uk_UA.UTF-8"
LC_IDENTIFICATION="uk_UA.UTF-8"
Якщо '''UTF-8''' не згадується, то встановлюємо локаль
apt install locales locales-all
sudo /usr/sbin/update-locale LANG=uk_UA.UTF-8 LANGUAGE="uk_UA:uk"

== Підключення репозитарію Koha ==
В репозитарії [http://debian.koha-community.org/ debian.koha-community.org] доступні стабільні версії, які виходять 2 рази на рік (травень і листопад) і підтримуються 18–42 місяці залежно від того, LTS це реліз чи ні (https://wiki.koha-community.org/wiki/Koha_Versioning).
Налаштування ключів:
sudo apt update
sudo apt install apt-transport-https ca-certificates curl gnupg2
sudo mkdir -p --mode=0755 /etc/apt/keyrings
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Якщо ви дотримуєтесь певного номера версії Koha, ви залишаєтесь на цій версії Koha, доки не буде змінено вихідні коди пакунків.
Це рекомендується для виробничих середовищ, щоб "випадково" не оновитися до нового великого випуску.
Коли ви запускаєте оновлення, ви оновлюєтесь лише до останнього випуску технічного обслуговування для обраної версії.

Поточні номери версій Koha та їхні статус (станом на липень 2026 р.; точні номери зсуваються щопівроку — звіряйте на [https://wiki.koha-community.org/wiki/Koha_on_Debian Koha_on_Debian]):
* '''26.05 (stable)''' — поточний стабільний реліз
* '''25.11 (oldstable)''' — на один реліз позаду поточного стабільного
* '''25.05 (oldoldstable)''' — на два релізи позаду поточного стабільного
* '''24.11 (LTS)''' — довготривала підтримка (Long Term Support), орієнтовно до травня 2028 р.
* 22.11 — попередня LTS-версія; підтримка добігає кінця, для нових інсталяцій вже не використовується

Щоб оновити список джерел пакетів для використання релізу 26.05:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Щоб оновити список джерел пакетів для використання LTS-релізу 24.11:
sudo tee /etc/apt/sources.list.d/koha.sources <<EOF
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 24.11
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
EOF
Замість номера версії можна вказати символьну назву (stable, oldstable, oldoldstable) — Suites стане, напр., stable. Для продакшн-середовища це '''не рекомендовано''': при переході репозитарію на новий stable ви автоматично й без попереднього тестування отримаєте великий реліз з новими можливостями.

Примітка: якщо ви раніше використовували старий формат списку джерел APT, видаліть файл /etc/apt/sources.list.d/koha.list — одночасна наявність старого й нового форматів джерела для того самого репозитарію спричиняє конфлікти APT.
Оновлюємо список доступних для встановлення пакунків
sudo apt update

= Встановлення Koha =
== Встановлення пакунків Koha ==
sudo apt-get install koha-common koha-deps koha-perldeps koha-l10n koha-elasticsearch
Якщо під час встановлення виникають помилки конфігурації, читаємо стандартну інструкцію про налаштування
less /usr/share/doc/koha-common/README.Debian

== Встановлення БД MariaDB та допоміжних пакунків ==
На Debian 13 (trixie) типова СУБД для Koha — MariaDB (у репозитарії trixie немає пакунка mysql-server: Oracle не постачає його для Debian, тож MariaDB — фактично єдина реалістична опція).
sudo apt-get install mariadb-server
sudo mariadb-secure-installation

За винятком першого питання, на всі питання можна відповісти Так (“'''Y'''”). Необхідно встановити root пароль (надалі „ПарольАдмінаMySQL“)!
sudo apt-get install memcached libmemcached-tools
sudo apt install aptitude
sudo apt install php-twig
sudo apt install phpmyadmin php libapache2-mod-php
* для „phpmyadmin“ вибрати (пробілом позначити зірочкою) лише „apache2“
* configure database for phpmyadmin with dbconfig-common? — так та встановити пароль застосунку
Типово phpmyadmin доступний за адресою http://localhost/phpmyadmin

Якщо потрібен доступ до phpmyadmin на іншому порті, то у файлі /etc/phpmyadmin/phpmyadmin.service змінити
...
<port>8888</port>
...
та додати цей порт у файл /etc/apache2/ports.conf
Listen 8888
Перезапуск Apache
sudo systemctl restart apache2
По умовчанню вхід через phpmyadmin для root закрито.
За потреби можна створити іншого користувача
mysql -u root -p
CREATE USER 'sysadmin'@'localhost' IDENTIFIED BY 'парольдляsysadmin';
та надати йому привілеї на усі БД:
GRANT ALL PRIVILEGES ON *.* TO 'sysadmin'@'localhost' WITH GRANT OPTION;
exit
sudo systemctl restart mariadb

== Пакунки з CPAN (лише за потреби) ==
'''Пріоритет — пакунки Debian та Koha''' (koha-deps, koha-perldeps): спільнота Koha прямо не рекомендує ставити perl-модулі напряму з CPAN на системах на базі Debian — тоді оновлення безпеки цих модулів лягає на вас особисто, а не на пакунковий менеджер дистрибутива. CPAN варто використовувати лише як крайній засіб, коли конкретного модуля немає ні в Debian, ні в репозитарії debian.koha-community.org.

Перелік відсутніх модулів дивимось на сторінці „Домівка > Про АБІС Koha > Модулі Perl“ вже після встановлення koha-common — залежності змінюються від версії до версії, тож наведений нижче перелік (актуальний станом на кінець 2023 р.) варто сприймати як приклад типових „проблемних“ пакунків, а не остаточний список:
* '''HTTPD::Bench::ApacheBench''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libhttpd-bench-apachebench-perl&searchon=names&suite=all&section=all]
* '''Text::CSV::Unicode''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libtext_csv_unicode-perl&searchon=names&suite=all&section=all]
* '''Selenium::Remote::Driver''' — перевірка в Debian: [https://packages.debian.org/search?keywords=libselenium_remote_driver-perl&searchon=names&suite=all&section=all]
* '''Locale::XGettext::TT2'''
* '''Test::PerlTidy'''

Якщо модуля дійсно немає в жодному репозитарії, встановлюємо командами (при першому використанні CPAN підтверджуємо автоматичне налаштування та підключення до Інтернету):
sudo apt-get install make libgdbm-dev apache2-dev libdatetimex-easy-perl
sudo perl -MCPAN -e 'install HTTPD::Bench::ApacheBench'
sudo perl -MCPAN -e 'install Test::Differences'
sudo perl -MCPAN -e 'install Text::CSV::Unicode'
sudo perl -MCPAN -e 'install Selenium::Remote::Driver'
sudo perl -MCPAN -e 'install Locale::XGettext::TT2'
sudo perl -MCPAN -e 'install Test::PerlTidy'

== Налаштування Apache та сценарій „koha-post-install-setup“ ==
1) Виконуємо сценарій
sudo koha-post-install-setup
(він задіює модулі Rewrite та Suexec для Apache)
2) Додатково задіюємо модулі Deflate, Cgi, headers, proxy_http
sudo a2enmod deflate
sudo a2enmod rewrite
sudo a2enmod cgi
sudo a2enmod headers proxy_http
3) Редагуємо /etc/apache2/conf-available/charset.conf
AddCharset UTF-8 .utf8
AddDefaultCharset UTF-8
та задіюємо його
sudo a2enconf charset
4) Перезапуск Apache
sudo systemctl restart apache2

== Створення екземпляра АБІС Koha ==
=== Варіанти налаштування АБІС Koha з доменами та портами ===
==== Варіант з портами 80 та 8080 (тестовий, локальна мережа) ====

Підходить, коли Koha доступна напряму за IP-адресою сервера в локальній мережі, без реального доменного імені. Електронний каталог (для читачів) — порт 80, адміністративний інтерфейс (для бібліотекарів) — порт 8080.

===== koha-ukr-unimarc-site.conf =====

Створюємо файл
sudo mc -e /etc/koha/koha-ukr-unimarc-site.conf
наступного змісту
DOMAIN="" # ПОРОЖНЬО для доступу за IP. НЕ "localhost" — koha-create формує ServerName як OPACPREFIX+ІМ'Я_ЕКЗЕМПЛЯРА+OPACSUFFIX+DOMAIN без роздільників, тож "localhost" дав би "ukr_unimarclocalhost". Порожній DOMAIN — стандартна практика офіційної інструкції для IP-based встановлення.
OPACPORT="80" # TCP-порт інтерфейсу читачів (типово 80, якщо пропустити)
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="8080" # TCP-порт адміністративного інтерфейсу
INTRAPREFIX=""
INTRASUFFIX=""
ZEBRA_MARC_FORMAT="unimarc" # Формат MARC для індексування Zebra
ZEBRA_LANGUAGE="uk" # Основна мова індексування Zebra. Дійсні значення: cs, el, en(типово), es, fr, nb, ru, uk.
DEFAULTSQL="" # значення зазвичай не потрібне
USE_MEMCACHED="yes" # Використовувати memcache для екземпляра.
MEMCACHED_SERVERS="127.0.0.1:11211" # Список host:port memcached-серверів через кому.
MEMCACHED_PREFIX="koha_" # Префікс простору імен memcached для екземпляра.
ENABLE_SRU="yes" # Увімкнути сервер Z39.50/SRU (типово вимкнено).
SRU_SERVER_PORT="7090" # TCP-порт для Z39.50/SRU-сервера (типово 7090).
ELASTICSEARCH_SERVER="127.0.0.1:9200" # Elasticsearch-сервер (host:port). Підставляється напряму в <server> усередині блоку <elasticsearch> в koha-conf.xml створюваного екземпляра.

''Щодо BIBLIOS_INDEXING_MODE / AUTHORITIES_INDEXING_MODE - ці два рядки в попереднньому конфігу є "мертвим" залишком старих інструкцій і в них тепер немає сенсу''

===== ports.conf =====

Порт 80 Apache вже слухає за замовчуванням, тож у /etc/apache2/ports.conf достатньо додати лише порт адмін-інтерфейсу:
Listen 8080

Типовий сайт-заглушка Apache (000-default) також слухає порт 80, і за відсутності збігу за ServerName саме він відповідатиме на прямі звернення за IP. Для чистого IP-доступу його варто вимкнути:
sudo a2dissite 000-default
sudo systemctl restart apache2

''Якщо з якоїсь причини типова сторінка Apache на порту 80 усе ж потрібна — тоді трюк із портом 8008 лишається робочим альтернативним варіантом (перенесення VirtualHost 000-default на порт 8008).''

===== Створення екземпляра =====

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc

Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

OPAC буде доступний на http://<IP-сервера>/, адмін-інтерфейс — на http://<IP-сервера>:8080/.

==== Варіант з доменами ====

Для випадку, коли для АБІС Koha заздалегідь виділено окремі домени, наприклад:
catalog.librarydomain.ua
koha.librarydomain.ua

===== DNS =====

Налаштуйте A-записи (або CNAME) обох імен на IP-адресу сервера у вашого DNS-провайдера чи у внутрішньому DNS.

Загальні технічні поради — https://wiki.koha-community.org/wiki/How_to_set_up_a_domain_name_for_Koha

koha-create будує імена хостів за жорсткою формулою (незмінно й у 26.05):
OPAC: http://<OPACPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><OPACSUFFIX><DOMAIN>:<OPACPORT>
STAFF: http://<INTRAPREFIX><ІМ'Я_ЕКЗЕМПЛЯРА><INTRASUFFIX><DOMAIN>:<INTRAPORT>

Ім'я екземпляра завжди підставляється в середину — прибрати його самими лише змінними koha-sites.conf неможливо. Тобто отримати рівно "catalog.librarydomain.ua" (без імені екземпляра в назві хоста) стандартною схемою напряму не вийде.

===== koha-ukr-unimarc-site.conf =====
DOMAIN=".librarydomain.ua" # Крапка на початку ОБОВ'ЯЗКОВА — інакше ім'я екземпляра й домен зіллються без роздільника (буде "ukr_unimarclibrarydomain.ua")
OPACPORT="80"
OPACPREFIX=""
OPACSUFFIX=""
INTRAPORT="80"
INTRAPREFIX=""
INTRASUFFIX="-intra" # додає "-intra" перед доменом в адмін-адресі
ZEBRA_MARC_FORMAT="unimarc"
ZEBRA_LANGUAGE="uk"
DEFAULTSQL=""
USE_MEMCACHED="yes"
MEMCACHED_SERVERS="127.0.0.1:11211"
MEMCACHED_PREFIX="koha_"
ENABLE_SRU="yes"
SRU_SERVER_PORT="7090"
ELASTICSEARCH_SERVER="127.0.0.1:9200"

Це дасть OPAC на http://ukr_unimarc.librarydomain.ua/ та staff-інтерфейс на http://ukr_unimarc-intra.librarydomain.ua/ (обидва на порту 80 — розрізняються доменним іменем, не портом).

Створюємо екземпляр (значення DOMAIN/PREFIX/SUFFIX на цьому етапі не важливі — вони все одно будуть переписані), а потім вручну підправляємо ServerName у згенерованому файлі Apache:

sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
sudo nano /etc/apache2/sites-available/ukr_unimarc.conf

У першій секції (<VirtualHost *:80> для ЕК) знайти рядок
ServerName ...
і замінити на
ServerName catalog.librarydomain.ua

У другій секції (<VirtualHost *:80> для Intranet замінити на
ServerName koha.librarydomain.ua

Зберегти файл і перезапустити Apache:
sudo systemctl restart apache2

=== Команда „koha-create“ ===
Синтаксис — [https://wiki.koha-community.org/wiki/Commands_provided_by_the_Debian_packages#koha-create на вікі] та в [https://github.com/Koha-Community/Koha/blob/main/debian/scripts/koha-create коді на GitHub], а також через вбудовану довідку „koha-create --help“. '''Звірено з поточним --help/кодом на момент 26.05.'''

koha-create [--create-db|--request-db|--populate-db|--use-db] \
[--marcflavor marc21(default)|unimarc] \
[--zebralang cs|el|en(default)|es|fr|nb|ru|uk] \
[--elasticsearch-server localhost:9200(default)] \
[--use-memcached] \
[--memcached-servers 127.0.0.1:11211,host2:port2,...] \
[--memcached-prefix KOHA|koha_|...] \
[--enable-sru] \
[--sru-port 7090(default)|9998] \
[--defaultsql /path/to/some.sql] \
[--configfile /path/to/config] \
[--passwdfile /path/to/passwd] \
[--dbhost host] \
[--database dbname] \
[--adminuser admin_user_id_in_db] \
[--template-cache-dir /var/cache/koha/<instance>/templates(default)] \
[--timezone time/zone (America/Argentina)] \
[--upload-path /var/lib/koha/<instancename>/uploads(default)|...] \
[--tmp-path dir /var/lib/koha/<instance>/tmp(default)] \
[--letsencrypt] \
[--smtp-host host] \
[--smtp-port NN] \
[--smtp-timeout NN] \
[--smtp-ssl-mode mode [disabled(default)|ssl|starttls] \
[--smtp-user-name user] \
[--smtp-password pass] \
[--smtp-debug] \
[--mb-host localhost(default)] \
[--mb-port NN default: 61613] \
[--mb-user guest(default)] \
[--mb-pass guest(default)] \
[--mb-vhost koha_<instance>(default)] \
[--keep-cookie NAME] \
[--help,-h] \
instancename

''Зауваження: довжина екземпляра Коха („instancename“) наразі обмежена 11 символами (див. [https://github.com/digibib/kohadevbox/issues/56], [https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=10205]). Екземпляр з назвою більшої довжини буде непрацездатним.''

Зверніть увагу на прапорець '''--elasticsearch-server''' — він одразу прописує адресу ES-сервера в koha-conf.xml створюваного екземпляра (типово localhost:9200), що корисно тепер, коли Elasticsearch — основний рушій пошуку в цій інструкції.

Створення екземпляра АБІС Koha (українська, Unimarc)
sudo koha-create --create-db --configfile /etc/koha/koha-ukr-unimarc-site.conf ukr_unimarc
Вивід:
Koha instance is empty, no staff user created.
Starting Koha worker daemon for ukr_unimarc (default):.
Starting Koha indexing daemon for ukr_unimarc:.

=== Пошуковий рушій: Elasticsearch (рекомендовано) ===

Koha підтримує два пошукові рушії, що перемикаються системною преференцією SearchEngine: Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано Elasticsearch — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

Рядок ELASTICSEARCH_SERVER у конфіг-файлі вище — це ЛИШЕ адреса, яку koha-create підставить у <server> всередині блока <elasticsearch> файлу /etc/koha/sites/ukr_unimarc/koha-conf.xml. Сам Elasticsearch це НЕ встановлює, автентифікацію НЕ налаштовує і пошуковий рушій в Koha НЕ перемикає. Щоб Elasticsearch реально запрацював, потрібні додаткові кроки (актуально для 26.05, Elasticsearch 8.x):

==== 1. Сам сервер Elasticsearch (не входить у koha-elasticsearch) ====
curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
echo "deb [signed-by=/etc/apt/keyrings/elasticsearch.asc] https://artifacts.elastic.co/packages/8.x/apt stable main" | sudo tee /etc/apt/sources.list.d/elasticsearch.list
sudo apt update
sudo apt install elasticsearch
sudo systemctl daemon-reload
sudo systemctl enable --now elasticsearch.service

==== 2. Плагін analysis-icu (потрібен для коректного аналізу, зокрема нелатинських/кириличних текстів) ====
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
''Увага: після кожного оновлення пакета elasticsearch плагін потрібно перевстановлювати (remove, потім install) — інакше після апдейту Koha видаватиме помилку на кшталт "Custom Analyzer [analyzer_phrase] failed to find filter under name [icu_folding]".''

==== 3. Автентифікація (ES 8.x має безпеку увімкненою за замовчуванням) ====
Отримати/скинути пароль користувача elastic:
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password -u elastic
Прописати ці дані вручну в /etc/koha/sites/ukr_unimarc/koha-conf.xml (ЦЕ НЕ робиться через koha-sites.conf/ELASTICSEARCH_SERVER — тільки прямим редагуванням готового koha-conf.xml), у блоці <elasticsearch> розкоментувати й заповнити:
<userinfo>elastic:ВАШ_ПАРОЛЬ</userinfo>
<use_https>1</use_https>

==== 4. Перезапуск служб ====
sudo systemctl restart elasticsearch.service
sudo systemctl restart koha-common.service

Перевірка (з автентифікацією):
curl -k -u 'elastic:ВАШ_ПАРОЛЬ' https://localhost:9200

==== 5. Перемкнути системне налаштування пошукового рушія ====
У staff-інтерфейсі: More > Administration > Global system preferences > Searching → SearchEngine → Elasticsearch → Save.

==== 6. Початкова індексація ====
sudo koha-elasticsearch --rebuild -d ukr_unimarc

Перевірка: пошук у каталозі за "*" (зірочка) має повертати результати (у Zebra зірочка так не працює — це ознака, що Elasticsearch справді використовується).

''Примітка щодо кластера з кількома нодами: коментар у самому шаблоні koha-conf-site.xml.in каже, що елемент <server> "may be repeated to include all servers on your cluster" — але це стосується ручного редагування вже згенерованого koha-conf.xml, а не значення змінної ELASTICSEARCH_SERVER (вона одна адреса, без розбору списку через кому чи подібне).''

=== Альтернатива (legacy): Zebra з підтримкою кирилиці ===
Якщо з якихось причин потрібно залишитися на Zebra як основному рушії пошуку (наприклад, обмежені ресурси сервера — Elasticsearch помітно вимогливіший до RAM), нижче — перевірений роками спосіб підтримки кирилиці для Zebra. Без цього патчу пошук українською/кирилицею в Zebra або не працює, або дає некоректні результати.

Необхідно додати кириличні символи до файлу
/etc/koha/zebradb/etc/word-phrase-utf.chr
а саме виправити на наступне:
lowercase {0-9}{a-z}αβγδεζηθικλμνξοπρστυφχψωæäåąßćęłńóśøöüźżабвгдежзийклмнопрстуфхцчшщьыъэюяёєїґўі’
uppercase {0-9}{A-Z}ΑΒΓΔΕΖΗΘΙΚΛΜΝΞΟΠΡΣΤΥΦΧΨΩÆÄÅĄẞĆĘŁŃÓŚØÖÜŹŻАБВГДЕЖЗИЙКЛМНОПРСТУФХЦЧШЩЬЫЪЭЮЯЁЄЇҐЎІ’

space {\001-\040}!"#$%&'\()*+,-./:;<=>?@\[\\]^_`\{|}~{\x88-\x89}{\x98-\x9C}
Без цієї зміни пошук або не буде працювати або даватиме некоректні результати.
Також для коректного сортування кирилиці аналогічні зміни також потрібно внести і до файлу
/etc/koha/zebradb/lang_defs/en/'''sort-string-utf.chr''' (наявність uk/sort-string-utf.chr наразі не дає бажаного результату).
При оновленнях пакунка „koha-common“ також потрібно вносити ці зміни — це і є головний практичний недолік порівняно з Elasticsearch-варіантом вище: патч не переживає оновлення пакунка і його доводиться накладати заново щоразу.

==== Запуск служби Zebra ====
sudo koha-zebra --start ukr_unimarc

==== Запуск індексації Zebra ====
sudo koha-rebuild-zebra -f -v ukr_unimarc

== Веб-встановлювач ==
=== Актуальні українські sql-файли ===
Частина локалізованих SQL-таблиць '''українською''' була долучена латкою https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=18537 у 2017 р. для версії Koha 17.05.05 та вище.
Оновлення для українських SQL-таблиць доступні у Dropbox Сергія Дубика за адресою:
'https://www.dropbox.com/sh/nybt54x8yhh7frq/AACfsG32sJnBgNh1CdivXDjYa?dl=0'
Тека '''SQL_Koha_25_05_0X_adds/uk-UA_additional/uk-UA''' містить оновлення, які необхідно скопіювати у теку '''uk-UA''' у '''/usr/share/koha/intranet/cgi-bin/installer/data/mysql'''
Виконайте наступну команду
sudo find /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA -type d -exec chmod ugo+x {} \;
щоб надати привілеї теці /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA. Інакше інсталятор її не побачить.

=== Утворення локалізованих шаблонів ===
Спочатку дивимося перелік доступних мов
sudo koha-translate --list --available
Встановлюємо переклади для української
sudo koha-translate --install uk-UA
Ця команда також згенерує деякі перекладені дані для Коха (у форматі '''yaml'''-файлів) у теці
/usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA
разом з раніше скопійованими '''SQL'''-файлами. Примітка: sudo koha-translate --update uk-UA також генерує yaml-файли (потрібно при встановленні екземплярів Коха).
Також можете встановити деякі інші мови інтерфейсу
sudo koha-translate --install pl-PL
sudo koha-translate --install de-DE
sudo koha-translate --install fr-FR
sudo koha-translate --install it-IT
sudo koha-translate --install cs-CZ
sudo koha-translate --install bg-Cyrl
…

=== Кроки веб-встановлювача ===
Типовий логін для екземляра напр. „ukr_unimarc“ буде:
koha_ukr_unimarc
Пароль та логін можна переглянути за допомогою:
sudo koha-passwd ukr_unimarc
або логін і пароль зберігаються у файлі '''/etc/koha/sites/ukr_unimarc/koha-conf.xml''', у розділі '''config''' знаходимо користувача ('''user''') та пароль ('''pass'''). Також побачити логін та пароль можна через команди
sudo xmlstarlet sel -t -v 'yazgfs/config/user' /etc/koha/sites/ukr_unimarc/koha-conf.xml
sudo xmlstarlet sel -t -v 'yazgfs/config/pass' /etc/koha/sites/ukr_unimarc/koha-conf.xml

У веб-оглядачі переходимо за адресою http://localhost:8080/?language=uk-UA (чи http://localhost:8888/?language=uk-UA). Бачимо запит на авторизацію від веб-встановлювача.
Крок 1: мова '''uk-UA''', перевірка залежностей
Крок 2: налаштування бази даних, перевірка з’єднання, існування БД та привілеїв
Крок 3: створення таблиць, вибір МАРК-стандарту '''Unimarc''' (УкрМарк), вибір типових даних (послідовно '''вибираємо усі¹²''' '''дані''', імпорт 1-10 хв.).
¹Які типові дані можна вимкнути:
* Приклади користувачів
* Приклади бібліотек/підрозділів
²Також варто вимкнути типову структуру unimarc_sample_fastadd_framework (вона конфліктує з unimarc_sample_fastadd_framework_FA_UKR) у блоці „Факультативне“.

==== Процес імпорту даних ====
Для імпорту даних Koha використовуватиме дані з теки /usr/share/koha/intranet/cgi-bin/installer/data/mysql/uk-UA.
У цій теці будуть як дані, згенеровані самою Коха (у форматі yml-файлів) так і дані sql-скриптів (з набору Сергія Дубика).
На 3 кроці слідкуємо за помилками при імпорті типових даних. Якщо є помилки — знаходимо відповідні sql-файли, виправляємо їх та імпортуємо вручну (напр., через phpmyadmin) або очищуємо таблиці і перезапускаємо веб-встановлювач. Також повідомляйте про sql-помилки Сергія Дубика, serhijdubykЖАБКАgmail.com.
Для очищення таблиць (ОБЕРЕЖНО - БУДУТЬ ВИТЕРТІ УСІ ДАНІ з БД koha_ukr_unimarc) та перезапуску веб-встановлювача можна використати наступний bash-скрипт delete_all_data_in_db_koha_ukr_unimarc.sh:
#!/bin/bash
# MySQL сервер та інформація про підключення
INSTANCE="ukr_unimarc"
MYSQL_USER="koha_"$INSTANCE
MYSQL_PASSWORD="ваш_пароль"
MYSQL_HOST="localhost" # або інший хост, на якому запущено MySQL
MYSQL_DB="koha_"$INSTANCE
# Вибір всіх таблиць в базі даних
TABLES=$(mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -se "SHOW TABLES")
# Вимкнення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 0;"
# Цикл для виконання DELETE для кожної таблиці
for table in $TABLES
do
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "DELETE FROM $table;"
done
# Включення перевірки зовнішніх ключів
mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" -h "$MYSQL_HOST" "$MYSQL_DB" -e "SET FOREIGN_KEY_CHECKS = 1;"
echo "Всі дані з бази даних $MYSQL_DB були очищені."
sudo systemctl restart koha-common
sudo systemctl restart apache2
sudo systemctl restart mariadb
sudo systemctl restart memcached
koha-plack --restart $INSTANCE
Інколи, для кращого очищення, цей скрипт потрібно запускати повторно.

==== Помилка „Gateway Timeout“ ====
Рідко, скоріш на повільних серверах, на 3-му кроці може з’являтися помилка „Gateway Timeout“. Спробуйте в налаштуваннях Apache (/etc/apache2/apache2.conf) виставити більший час (Timeout 1200), виконати
sudo systemctl restart apache2
та перезапустити веб-встановлювач (й попередньо очистити таблиці).

==== Адаптаційний етап ====
=====Створення бібліотеки/підрозділу=====
Створюємо свій підрозділ, напр.
Код бібліотеки/підрозділу: AB
Найменування: Абонемент
=====Створення категорії користувачів=====
Якщо у sql-даних були вибрані типові категорії користувачів, то цей крок Коха пропустить.
===== Створення адміністратора Коха=====
Вводимо дані адміністратора Коха - прізвище, ім’я, номер читацького квитка, бібліотека / підрозділ, категорію користувача, логін, пароль.
===== Створення нового типу одиниць =====
Якщо у sql-даних були вибрані приклади типів одиниць, то цей крок Коха пропустить.
===== Створення нового правила обігу =====
Наприклад, вибираємо
Підрозділ бібліотеки: Абонемент
Категорія користувача: Студент
Тип одиниці: BOOK
Поточна дозволена кількість видач: 50
Термін випозичання: 14
Одиниці: дні
Продовження (дозволена кількість): 1
=====Встановлення завершено!=====
Вітаємо, Ви закінчили і готові до використання Коха

== Пошуковий рушій: Elasticsearch (рекомендовано) ==
Koha підтримує два пошукові рушії, що перемикаються системною преференцією '''SearchEngine''': Zebra (класичний, історично типовий) та Elasticsearch. У цій редакції інструкції за основний рушій обрано '''Elasticsearch''' — насамперед тому, що підтримка кирилиці/української реалізується штатними, підтримуваними Elastic-плагінами (ICU + офіційний плагін українського аналізатора), а не ручним патчем внутрішніх файлів Zebra, який доводиться повторно накладати після кожного оновлення пакунка koha-common.

Пакунок koha-elasticsearch ми вже встановили разом з іншими пакунками Koha на початку інструкції.

=== Встановлення сервера Elasticsearch ===
Koha станом на середину 2026 р. орієнтується на гілку Elasticsearch 8.x. Java (OpenJDK) для Elasticsearch зазвичай підтягується автоматично як залежність пакунка elasticsearch; за потреби додатково:
sudo apt install openjdk-21-jdk-headless
Підключаємо офіційний репозитарій Elastic та ключ:
sudo apt install apt-transport-https
sudo curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch -o /etc/apt/keyrings/elasticsearch.asc
sudo tee /etc/apt/sources.list.d/elasticsearch.sources <<EOF
Types: deb
URIs: https://artifacts.elastic.co/packages/8.x/apt
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/elasticsearch.asc
EOF
sudo apt update
sudo apt install elasticsearch
Під час встановлення пакунок покаже автоматично згенерований пароль вбудованого користувача elastic — за потреби (автентифікація/TLS) збережіть його; для одновузлової локальної інсталяції під Koha безпеку кластера зазвичай спрощують, див. офіційну документацію Elastic щодо мінімальної конфігурації для single-node.
Запуск і автозапуск служби:
sudo systemctl enable --now elasticsearch
Перевірка:
curl -k https://localhost:9200 -u elastic

=== Плагіни ICU та українського аналізатора ===
Плагін '''analysis-icu''' Koha вимагає обов'язково — без нього індексація/пошук у Koha з увімкненим Elasticsearch не запрацюють коректно. Плагін '''analysis-ukrainian''' — офіційний плагін Elastic, що інтегрує лематизатор Lucene UkrainianMorfologikAnalyzer (проєкт Morfologik) і додає якісне визначення словоформ для української замість „сирої“ посимвольної токенізації.
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-icu
sudo /usr/share/elasticsearch/bin/elasticsearch-plugin install analysis-ukrainian
sudo systemctl restart elasticsearch
Плагін analysis-ukrainian надає ES-аналізатор з назвою '''ukrainian'''. Прив'язка цього аналізатора до конкретних полів у мапінгу, який Koha створює для індексів biblios/authorities, — це вже налаштування на рівні мапінгу Elasticsearch (Адміністрація → Search engine configuration, або пряме редагування YAML-мапінгу в коді Koha); універсального „одна команда і все запрацювало“ рецепта тут немає, тому перш ніж переносити зміни на прод — перевірте поведінку на тестовому екземплярі й звіряйтеся з актуальною сторінкою https://wiki.koha-community.org/wiki/Elasticsearch. Навіть без ручного тюнінгу мапінгу підключений icu_tokenizer уже суттєво покращує коректність токенізації кирилиці порівняно з типовим standard-аналізатором.

=== Особливість Debian 13 (trixie): HTTP::Tiny і TLS ===
На Debian 13 (trixie) через оновлену версію бібліотеки HTTP::Tiny (0.083+), яку постачає ОС, з'єднання Koha з Elasticsearch може обриватися помилками перевірки TLS-сертифіката, навіть якщо ви звертаєтесь до localhost. Рішення — додати до секції <elasticsearch> у /etc/koha/sites/ukr_unimarc/koha-conf.xml:
<elasticsearch>
<server>127.0.0.1:9200</server>
<index_name>koha_ukr_unimarc</index_name>
<handle_args>
<verify_SSL>0</verify_SSL>
</handle_args>
</elasticsearch>
Після зміни — перезапустіть Koha-служби для екземпляра (нижче, розділ „Включення Plack“ і сусідні).

=== Індексація та перемикання Koha на Elasticsearch ===
1) У пошуку системних преференцій відкриваємо '''SearchEngine''' (Адміністрація → Глобальні системні преференції → Пошук) і перемикаємо значення з Zebra на '''Elasticsearch'''.
2) Будуємо індекси для потрібного екземпляра:
sudo koha-elasticsearch --rebuild -b -a -v ukr_unimarc
(прапорці -b і -a — окремо бібліографічні та авторитетні записи; без них перебудує обидва)
3) Запускаємо/перевіряємо індексувальну службу ES для екземпляра:
sudo koha-es-indexer --start ukr_unimarc
sudo koha-es-indexer --status ukr_unimarc
4) Перевірка результату: пошук символу '''*''' у каталозі має повернути весь фонд (у Zebra зірочка окремо як пошуковий термін не спрацьовує, в Elasticsearch — спрацьовує) — це швидкий індикатор, що Koha дійсно звертається до ES, а не залишилася на Zebra.

Служба Zebra (zebrasrv, індексувальний демон) на екземплярі, як і раніше, продовжує працювати у фоні навіть при увімкненому Elasticsearch — частина внутрішніх операцій Koha історично досі покладається на Zebra, тож вимикати її повністю не варто без окремого дослідження вашої версії Koha.

== Включення Plack ==
koha-plack --enable ukr_unimarc; koha-plack --start ukr_unimarc
Щодо продуктивності див. також тут:
* https://wiki.koha-community.org/wiki/Performance

== Створення sitemap ==
koha-sitemap --enable ukr_unimarc
koha-sitemap --generate ukr_unimarc

== E-mail ==
За замовчуванням надсилання пошти вимкнене. Це дозволяє спершу довести налаштування до ладу, перш ніж ризикувати надіслати небажані сповіщення користувачам. Щоб увімкнути пошту:
sudo koha-email-enable ukr_unimarc

== Вимкнення оновлення Koha ==
Для більш контрольованого оновлення пакунків Коха можна тимчасово закоментувати рядок Suites (або весь блок) у /etc/apt/sources.list.d/koha.sources, напр.:
Types: deb
URIs: https://debian.koha-community.org/koha/
# Suites: 26.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
Це дозволить легко оновлювати інші пакунки Debian, не зачіпаючи koha-common.

= Виправлення проблем =
Деколи стає відомо про проблему у поточній версії Koha. Зазвичай виправлення з’являється в наступній версії.
Це у випадку, якщо про проблему повідомлено на [https://bugs.koha-community.org/bugzilla3/ баґтрекер Koha] і знайдено й прийнято її вирішення (латка) до виходу наступної версії.
Тут згадуватимуться проблеми й їх вирішення для поточних версій Koha (приклад актуальної на 2026 р. проблеми — TLS-помилка Elasticsearch на Debian 13, описана вище в розділі про Elasticsearch).

Див. також: [[Виправлення та вдосконалення для АБІС Koha]], зроблені українською спільнотою АБІС Koha.

= Оновлення Koha =
Нова версія Koha виходить кожні шість місяців з набором нових функцій. Також кожен місяць виходять коригувальні оновлення.
Оновлення проходить легко для варіанту [[Встановлення Koha з репозитарію на ОС Debian|встановлення Koha з пакунків Debian]].
Більш стабільними є версії Коха, що пройшли декілька коригувальних оновлень.
Можна оновлювати Коху до версії з певної стабільної гілки. Напр., якщо потрібно оновити Коху до найновішої коригувальної версії у гілці 25.05, то у файлі /etc/apt/sources.list.d/koha.sources
має бути наступне
Types: deb
URIs: https://debian.koha-community.org/koha/
Suites: 25.05
Components: main
Signed-By: /etc/apt/keyrings/koha.asc
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install koha-common
Деколи необхідно оновити ключ debian-сховища Koha:
sudo curl -fsSL https://debian.koha-community.org/koha/gpg.asc -o /etc/apt/keyrings/koha.asc
Для більшого контролю над наступними оновленнями Коха можна закоментувати рядок Suites у /etc/apt/sources.list.d/koha.sources (і розкоментовувати чи змінювати при ручному оновленні АБІС Koha) — див. розділ „Вимкнення оновлення Koha“ вище.

Якщо оновлюєте екземпляр, який уже перейшов на Elasticsearch (розділ вище), після встановлення нової версії koha-common доцільно одразу перевірити:
* чи не зникло (і не потребує повторного додавання) налаштування <verify_SSL>0</verify_SSL> у koha-conf.xml — деякі мажорні оновлення перегенеровують конфігураційні файли;
* чи не з'явилися нові поля в мапінгу ES, що потребують повної переіндексації (koha-elasticsearch --rebuild -f).

== Встановлення/оновлення допоміжних perl-модулів ==
Після оновлення, перевіряємо в бібліотечному інтерфейсі сторінку „Домівка > Про АБІС Koha > Модулі Perl“.
Ви можете побачити відсутні модулі Perl, виділені різними кольорами.
=== Пакунки з репозитарію Debian ===
Деякі згадувані тут пакунки могли бути відсутні у репозиторії Debian на момент підготовки пакунки з Koha. Пробуємо знайти відсутні пакунки через пошук
https://www.debian.org/distrib/packages#search_packages
Знайдені пакунки довстановлюємо
sudo apt-get install знайдений_пакунок
Напр.
sudo apt-get install libhttp-tiny-perl
=== Пакунки з CPAN ===
Perl-пакунки, наразі не пакетизовані й відсутні у репозитарії Debian, встановлюємо напряму з репозитарію perl-пакунків CPAN (див. застереження в розділі „Пакунки з CPAN (лише за потреби)“ вище — це крайній засіб, не типовий шлях).
sudo cpan
install Test::DBIx::Class
install Readonly::XS
install HTTPD::Bench::ApacheBench

== Оновлення локалізації ==
sudo koha-translate --update uk-UA
та, за потреби, інших мов (pl-PL, de-DE, fr-FR)
Однак, при оновленні пакунків Koha локалізація оновлюється автоматично для усіх вибраних мов.

= Вилучення Koha =
Вилучення пакунка „koha-common“ не приводить до автоматичного вилучення екземплярів АБІС Koha. '''Попередньо''' необхідно зупинити та вилучити усі екземпляри АБІС Koha командами
sudo systemctl restart mariadb
sudo systemctl restart apache2
sudo koha-zebra --stop ukr_unimarc
sudo koha-indexer --stop ukr_unimarc
sudo koha-es-indexer --stop ukr_unimarc
sudo koha-plack --stop ukr_unimarc
sudo koha-disable ukr_unimarc
sudo koha-remove ukr_unimarc
sudo /sbin/userdel ukr_unimarc-koha
sudo /sbin/groupdel ukr_unimarc-koha
sudo systemctl restart memcached
Якщо екземпляр використовував Elasticsearch і ви остаточно позбуваєтесь індексів, додатково видаліть індекс(и) цього екземпляра з Elasticsearch (типово мають назву на кшталт koha_ukr_unimarc_biblios, koha_ukr_unimarc_authorities):
curl -k -X DELETE "https://localhost:9200/koha_ukr_unimarc_*" -u elastic
Якщо Elasticsearch більше ніде на цьому сервері не потрібен (не використовується іншими екземплярами):
sudo systemctl stop elasticsearch
sudo apt-get purge elasticsearch
sudo rm -rf /var/lib/elasticsearch /etc/elasticsearch

Інколи виникає помилка userdel: user ukr_unimarc-koha is currently used by process 4793 /usr/sbin/deluser: `/usr/sbin/userdel ukr_unimarc-koha' returned error code 8. Див. https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=4880.
Перегляд переліку наявних екземплярів
sudo koha-list
Остаточне вилучення пакунків Koha
sudo apt-get purge koha-common koha-deps koha-perldeps koha-elasticsearch
Перевірте також теки:
/var/spool/koha
/var/log/koha
/var/lib/koha
/var/cache/koha
/usr/share/koha
/etc/koha
Можна очистити вміст цих тек щодо екземпляру ukr_unimarc
rm -rf /var/spool/koha/ukr_unimarc
rm -rf /var/log/koha/ukr_unimarc
rm -rf /var/lib/koha/ukr_unimarc
rm -rf /var/cache/koha/ukr_unimarc
У випадку якщо це був останній екземпляр та Вам не потрібна тека /usr/share/koha, то вилучайте й повністю теку /usr/share/koha
rm -rf /usr/share/koha
Примітка: Теку /usr/share/koha мала вилучити команда „apt-get purge koha-common“, однак там могли залишитися файли перекладів чи інші ваші зміни чи долучені файли.
У теці /etc/koha команда „apt-get purge koha-common“ також вилучила більшість файлів. Залишилася тека /etc/koha/sites/ukr_unimarc, її вилучаємо
rm -rf /etc/koha/sites/ukr_unimarc
Також там могли зберегтися конфіг налаштування екземпляра (/etc/koha/koha-ukr-unimarc-site.conf) та інші ваші зміни. Якщо нічого з цього не потрібно, то вилучаємо теку /etc/koha/
rm -rf /etc/koha
Вилучення налаштувань для веб-сервера Apache2
rm /etc/apache2/sites-enabled/ukr_unimarc.conf
rm /etc/apache2/sites-available/ukr_unimarc.conf
Якщо після видалення планується перевстановлення Коха, то ще потрібно
sudo systemctl restart memcached

= Налаштування =
Щодо додаткових налаштувань та адаптацій див. тут: [[Налаштування Koha, встановленої з джерела]].

= Див. також =
* [[Встановлення Koha з джерела на ОС Debian]]
* [[Оновлення Koha, встановленої з джерела]]
* [[Коротка інструкція для адміністратора АБІС Koha]]
* [[Короткий посібник користувача АБІС Koha]]
[[Category:АБІС Koha]]