Olá pessoal, meu nome é Paulo, sou bibliotecário e escrevi este artigo para ajudar outros bibliotecários e auxiliares, principalmente aqueles que ainda utilizam sistemas de gerenciamento antigos ou fichas de empréstimo para gerenciar seus acervos.
Sistemas de gerenciamento de bibliotecas proprietários são extremamente caros, o Koha é uma excelente alternativa Open Source e gratuita, que não perde em nada para programas pagos como Pergamum e Sophia, implementá-lo na instituição onde trabalho gerou uma economia de milhares de reais aos cofres públicos do meu município.
Como outros tutoriais em português não eram muito detalhados, resolvi criar um guia que cobre todas as etapas para configurar um servidor completo com o sistema. Espero que seja útil.
Onde hospedar? As 5 formas de instalação
Como o Koha foi feito nativamente para rodar em Linux (especificamente Debian ou Ubuntu), a forma como você o hospeda define o quão estável seu sistema será.
- Servidor Linux Dedicado (O Ideal)
Utilizar um servidor do tipo “rack” ou até mesmo um desktop que esteja disponível na biblioteca.
Vantagens: Máximo desempenho, estabilidade total.
Desvantagens: Requer equipamento dedicado.
- Servidor em Nuvem (VPS)
Instalar em serviços como AWS, Hostinger, Hostgator.
Vantagens: Acessível de qualquer lugar do mundo com IP fixo e sem preocupação com queda de energia local.
Desvantagens: dependência de internet, custo mensal.
- Computador Linux com Interface Gráfica
Instalar no seu PC de uso diário .
Vantagens: Bom para quem está aprendendo e quer uma interface visual para gerenciar arquivos.
Desvantagens: O consumo de RAM da interface gráfica pode tirar recursos do banco de dados do Koha.
- Windows via VirtualBox
Criar uma “máquina dentro da outra”. Você roda um Linux virtual dentro do seu Windows.
Vantagens: Fácil de migrar para outra máquina.
Desvantagens: Muito pesado. Se o Windows travar, o Koha cai junto. A performance de disco é inferior, configuração da rede pode também ser difícil.
- Windows via WSL2
Uma camada do Linux que roda direto no kernel do Windows 10 ou 11.
Vantagens: Boa integração com os diretórios do Windows
Desvantagens: Configuração de rede (IP fixo) pode ser bem chata para quem quer que outras máquinas da rede local acessem o sistema.
Antes de começar: O que você precisa saber?
Dependendo do caminho que você escolher, as ferramentas de acesso mudam, então siga os passos apenas da opção que você escolheu.
Opção 1. Servidor Linux Dedicado
Recomendo instalar no sistema operacional Ubuntu Server.
Criar um pendrive bootável com o Balena Echer.
Entre na BIOS pela tecla de atalho (ESC, F1, F2, F11, F12, depende da placa) tem algumas opções de bios que devem ser mudadas (se possível), desligue o Secure Boot, mude o SATA MODE para AHCI (muitas placas não tem isso, daí ignore), depois disso dê boot pelo pendrive, vá até a seção de boot e selecione o USB.
O servidor deve estar conectado via cabo de rede.
A instalação é simples e intuitiva, você deve apenas se atentar em:
Definir a senha e usuário do servidor e anotar (escolha uma senha forte por questão de segurança).
Lembre-se de selecionar para instalar o open-ssh.
Agora vamos conectar, primeiro vamos saber o ip do servidor, vá para o terminal do servidor e coloque para abrir a porta:
sudo ufw allow 53682
E depois para saber o ip:
ip a
Depois vamos para o Powershell, vá para o menu iniciar do Windows (de outro computador) e pesquise por Powershell e abra o terminal, vamos conectar por ssh, coloque o valor do ip que você descobriu em ipdoservidor e o nome que você deu ao usuário em nomedousuario:
ssh -L 53682:127.0.0.1:53682 nomedousuario@ipdoservidor
Nota importante: Caso esse método de conectar no servidor com ssh não funcionar você pode usar o método simples: ssh nomedousuario@ipdoservidor Porém você pode ter problemas mais para frente no tutorial como programar os backups automáticos.
Opção 2. Servidor em Nuvem (VPS)
Onde contratar: Existem várias empresas, escolha um plano que tenha pelo menos 4GB de RAM (o Koha exige isso para rodar bem o banco de dados e a indexação).
Instalação:
No painel da empresa escolhida, crie uma “Instância” ou “Droplet”.
Selecione o sistema operacional Ubuntu Server.
A VPS será criada e você receberá um Endereço de IP, um Usuário (geralmente root ou ubuntu) e uma Senha (ou uma chave SSH).
Configuração de Segurança: Diferente do servidor local, a VPS tem um firewall no painel do site da empresa.
Você deve ir nas configurações de “Networking” ou “Firewall” no site da VPS e abrir as portas: 22 (SSH), 80 (OPAC) e 8080 (Staff).
Coloque ip fixo, pois ip dinâmico pode afetar a conexão com o servidor.
É importante dizer que muitos serviços de VPS fornecem um domínio, então se eles fornecerem você não precisará comprar um domínio do CloudFlare como vamos ver mais para frente.
Acesse o servidor VPS com ssh:
ssh -L 53682:127.0.0.1:53682 nomedousuario@ipdoservidor
Nota importante: Caso esse método de conectar no servidor com ssh não funcionar você pode usar o método simples: ssh nomedousuario@ipdoservidor Porém você pode ter problemas mais para frente no tutorial como programar os backups automáticos.
Opção 3. Computador Linux com Interface Gráfica
Instale uma distribuição Linux com interface gráfica que seja baseada em ubuntu, eu recomendo o Linux Mint pois é fácil de usar para iniciantes.
Criar um pendrive bootável com o Balena Echer.
Selecione a imagem do sistema operacional e o pendrive que será usado e flesheie a imagem.
Conecte o pendrive no computador e entre na bios pela tecla de atalho (ESC, F1, F2, F11, F12, depende da placa) tem algumas opções de bios que devem ser mudadas (se possível), desligue o Secure Boot, mude o SATA MODE para AHCI (muitas placas não tem isso, daí ignore), depois disso dê boot pelo pendrive, vá até a seção de boot e selecione o USB.
O processo de instalação do Linux Mint é bastante fácil e intuitivo, não esqueça de anotar a senha e usuário, abra o terminal dele para instalar o Koha.
Opção 4. Windows via VirtualBox
Ative a Virtualização na BIOS: Antes de tudo, reinicie o PC, entre na BIOS (geralmente teclas F2, Del ou F10) e procure por “Intel Virtualization Technology” ou “SVM Mode” (AMD). Ative essa opção, senão o VirtualBox não vai rodar sistemas de 64 bits.
Instale o VirtualBox: Baixe e instale a versão mais recente:
Baixe o Ubuntu Server:
Configuração de Rede (Crucial): Vá nas configurações da VM → Rede → Conectado a: Placa em modo Bridge. Isso permite que o Koha receba um IP da sua rede local, tornando o OPAC e o Staff acessíveis por outros computadores.
Criar a VM
No VirtualBox clique em “novo” coloque um nome na máquina, selecione a imagem do Ubuntu Server, a caixa escrita “Proceed with unattended installation” NÃO PODE ESTAR SELECIONADA, depois só finalizar a máquina, e abri-la.
A instalação é simples e intuitiva, você deve apenas se atentar em:
Definir a senha e usuário do servidor e anotar (escolha uma senha forte por questão de segurança).
Lembre-se de selecionar para instalar o open-ssh .
Agora vamos conectar, primeiro vamos saber o ip do servidor, vá para o terminal do servidor e coloque para abrir a porta:
sudo ufw allow 53682
E depois para saber o ip:
ip a
Depois vamos para o Powershell, vá para o menu iniciar do Windows (de outro computador) e pesquise por Powershell e abra o terminal, vamos conectar por ssh, coloque o valor do ip que você descobriu em ipdoservidor e o nome que você deu ao usuário em nomedousuario:
ssh -L 53682:127.0.0.1:53682 nomedousuario@ipdoservidor
Nota importante: Caso esse método de conectar no servidor com ssh não funcionar você pode usar o método simples: ssh nomedousuario@ipdoservidor Porém você pode ter problemas mais para frente no tutorial como programar os backups automáticos.
Opção 5. Windows via WSL2
A forma mais leve de rodar Linux dentro do Windows, sem a interface pesada de uma VM clássica.
Ative a Virtualização na BIOS: Assim como no VirtualBox, o WSL2 exige que a virtualização esteja ativa na sua placa-mãe. Procure por VT-x ou AMD-V na BIOS e mude para “Enabled”.
Ative os Recursos do Windows: No menu iniciar, pesquise por “Ativar ou desativar recursos do Windows” e marque:
Subsistema do Windows para Linux.
Plataforma de Máquina Virtual.
Instale o Ubuntu: pesquise por PowerShell no mecanismo de busca do Windows e clique com o botão direito e execute como administrador. Agora com o terminal do Powershell aberto digite:
wsl --install.
Reinicie o PC.
Agora no mecanismo de busca pesquise por Ubuntu clique com o botão direito e fixe na barra de tarefas para deixar mais prático e vai abrir o terminal, é importante notar que o terminal deve estar sempre aberto para o sistema Koha funcionar.
Vamos começar a instalação do sistema:
Para quem não está habituado com Linux sempre que você iniciar o terminal você deverá dar permissão de administrador para fazer a maioria das ações, então sempre que ligar o terminal digite:
sudo su
digitar senha do usuário.
Também é importante saber que muitas vezes depois de alguma ação ele pede confirmação, algo como “Y/N?” ou “S/N?” então confirme com “y” ou “s” , sempre preste a atenção nisso.
sudo apt update
sudo apt upgrade
sudo apt autoremove
Instalar um editor de textos que será importante mais para frente:
sudo apt install nano
Adicionar repositório:
sudo sh -c 'wget -qO - https://debian.koha-community.org/koha/gpg.asc | gpg --dearmor -o /usr/share/keyrings/koha-keyring.gpg’
sudo sh -c 'echo "deb [signed-by=/usr/share/keyrings/koha-keyring.gpg] https://debian.koha-community.org/koha oldstable main" >> /etc/apt/sources.list.d/koha.list’
Atualizar os repositórios:
sudo apt update
Instalar o servidor MariaDB:
sudo apt install -y mariadb-server
Colocar uma senha no MariaDB, substituir “senha” (de preferência uma senha forte, lembre-se de anotar):
sudo mysqladmin -u root password senha
Instalar o Sistema Koha:
sudo apt install -y koha-common
acessar uma arquivo de texto para editar (para salvar aperte ctrl +O, enter, para sair ctrl X):
sudo nano /etc/koha/koha-sites.conf
vai abrir um texto, em “intraport =” coloque “intraport = 8080” e clique ctrl + o, enter e ctrl + x para salvar e fechar.
(Se essas portas não funcionarem use 8081 para o intraport e 8082 para o opacport)
criar uma instância para o Koha:
sudo a2enmod rewrite
sudo a2enmod cgi
sudo service apache2 restart
sudo koha-create --create-db library
Abrir outro arquivo de texto:
sudo nano /etc/apache2/ports.conf
vai aparecer uma linha escrito “Listen 80” abaixo dela coloque uma linha “Listen 8080”.
(para salvar aperte ctrl +O, enter, para sair ctrl X):
(Se essa portas não funcionarem troque por Listen 8081 e Listen 8082)
Reinicie o servidor:
sudo service apache2 restart
habilitar os módulos:
sudo a2dissite 000-default
sudo a2enmod deflate
sudo a2ensite library
sudo service apache2 restart
sudo service memcached restart
Instalar um pacote para deixar o sistema em português:
sudo koha-translate --list
sudo koha-translate --list --available
sudo koha-translate --install pt-BR
Vamos agora descobrir a senha, escreva no terminal:
sudo nano /etc/koha/sites/library/koha-conf.xml
vai abrir o bloco de notas, vá para baixo e vai encontrar algo como:
a senha é este conjunto de caracteres entre esses dois “”, anote essa senha, ela será muito importante mais para frente.
Agora nós temos dois caminhos, para quem quer começar o Koha do zero e quem quer restaurar por um arquivo de backup:
Caminho 1. Restaurar do zero:
Digite no terminal:
ip a
Agora que descobrimos o ip vamos acessar o koha pelo navegador, digite no seu navegador, substitua o “ip” pelo que você descobriu:
Ip:8080
Você verá uma tela assim:
No User name coloque: koha_library
E em Password a senha que tínhamos descoberto.
Na interface de configuração você pode deixar em português, a configuração é intuitiva, lembre-se de anotar o login e senha de bibliotecário para poder logar e usar o staff do sistema, também na parte para selecionar os módulos adicionais selecione todos, e você já pode começar a usar o sistema do zero.
Caminho 2. Restaurar o sistema com um arquivo de backup:
Use um arquivo de backup do Koha de uma instalação anterior, se ele estiver compactado como .tx .gz você pode descompactá-lo com o Winrar ou 7zip. nomeie ele como koha_library.sql.
Vamos mandar esse arquivo para o servidor, primeiro coloque o arquivo de backup na pasta documentos do Windows (o comando a seguir é dado pelo Powershell do Windows ou seja ele não pode estar conectado por ssh no servidor).
scp “C:\Users\nomedousuariodowindos\Documents\koha_library.sql” nomedousuariodavm@ip:/home/nomedousuariodalinux/
(Se não descobrir a localização do arquivo arraste ele para o Powershell que ele vai selecionar o diretório correto)
(Quem estiver no WSL2 ou no Linux com interface gráfica basta arrastar o arquivo de backup para a pasta de usuário: /linux /home/nomedousuário/ koha_library.sql)
Beleza, agora vamos tirar o banco de dados provisório que tínhamos feito:
sudo mysql -uroot -p
drop database koha_library;
create database koha_library;
quit;
Agora a restauração em si, essa parte pode ter erro talvez seja necessário conferir os nomes da instancias:
sudo mysql -uroot -p koha_library < koha_library.sql
Verifique se deu certo
Reindexar os dados, a última linha demora um pouco:
sudo service memcached restart
sudo koha-upgrade-schema library
sudo koha-rebuild-zebra -v -f library
Esse último processo pode ser muito demorado dependendo do número de registros depois de finalizar pode entrar no sistema, decubra o ip pelo terminal:
ip a
Coloque no seu navegador (substitua o ip pelo que você descobriu):
Ip:8080
Coloque seu nome de usuário e senha e já pode usar.
Como expor o servidor à internet:
Agora eu recomendo fortemente usar o serviço de Cloudflare tunnel pois é a forma mais profissional e segura de expor seu servidor para a internet, e para o se site aparecer no mecanismo de busca do Google.
A acesse o site do Cloudflare:
Crie uma conta no site em seguida compre um domínio para a sua biblioteca, os preços são muito baixos, um domínio .org custa na casa do 50 ou 60 reais por ano, coloque o nome que você achar melhor e que seja facilmente reconhecível para a sua biblioteca.
Agora no site do CloudFlare vá em: “Zero Trust” → “redes” →"Túneis" (ou conectores).
Clique na opção: “+ criar um túnel”
Selecione “CloudFlare”, nomeie o seu túnel e salve.
Em “Escolha seu ambiente” selecione “Debian” e “64-bit” (presumindo que seu computador é 64-bit)
Depois disso irá aparecer as linhas de comando “Se você não tiver o cloudflared instalado na sua máquina” e “Após concluir a instalação do Cloudflared em seu computador, será possível instalar um serviço para executar automaticamente o túnel sempre que o computador for iniciado” copie e cole a primeira e depois essa segunda no terminal do servidor.
Agora vamos definir as rotas, na parte superior clique em “Rotas de aplicativo publicadas”
Clique em “+ Adicionar uma rota de aplicativo publicada” e faça duas rotas, uma para o staff e a outra para o opac.
Vamos preencher os campos, coloque o domínio que você comprou, como você tem apenas um domínio você vai precisar definir um subdomínio no staff ou opac.
A parte do caminho pode por vazio.
No tipo deixe “HTTP”
Na URL pode deixar pelo localhost ou com o ip (que você encontroi pelo comando ip a), por exemplo:
Staff: localhost:8080 | ipdoservidor:8080
Opac: localhost:80 | ipdoservidor:80
Agora para fazer o seu site ser descoberto pelo mecanismo de busca do Google acesse o Google Search Console:
Coloque na parte de domínio o seu domínio, eles vão te enviar um arquivo TXT, agora volte na parte do ClouFlare em “Domínio” clique nos três pontos ao lado do seu domínio e clique em “configurar o DNS” depois em “adicionar registro” e coloque o TXT.
Dentro das configurações globais no Koha permita a opção “OpacNoIndex” e coloque o seu domínio em na opção: RobotPublicAddress
Importante notar que pode demorar dias para o seu site aparecer no Google, tenha paciência.
Backups manuais
Agora vamos aprender como fazer backups do Koha, primeiro vamos fazer um backup manual:
sudo mysqldump -uroot -p koha_library | xz > koha_library.sql.xz
O backup estará na raiz da pasta do usuário no Linux
Backups automático para o Google Drive
Atualizar:
sudo apt update
sudo apt upgrade
Instalar o Rclone:
sudo apt install rclone
Configurar o Rclone, lembre-se que para configurar o backup automático tem entrar pelo ssh no powershell de uma forma diferente e liberar a porta:
rclone config
Digite ‘n’ para adicionar um novo controle remoto.
coloque o nome:
gdrive
Selecione o serviço de nuvem Google Drive na lista para enviar o backup. Precisamos inserir o número do serviço de nuvem. Então, insira o número correto do Google Drive. Vai aparecer as opções veja o número do Google Drive e digite o número dele
Pressione Enter duas vezes (para deixar em branco o ID do cliente e o ID secreto do cliente)
Selecione o tipo de permissão e digite o número ‘1’ para conceder acesso total.
Pressione Enter (para deixar em branco o ID da pasta raiz e o arquivo da conta de serviço)
Digite ‘N’, pois não precisamos de configuração avançada.
Digite “Y” para usar a configuração automática.
Ao digitar “Y” e pressionar Enter, copie o link que apareceu no terminal, abra no navegador e conceda a permissão.
Após conceder a permissão, você configurou o rclone com sucesso.
Agora digite “n” para não configurar isso como uma unidade de equipe.
Pressione “Y” de novo para confirmar.
Digite ‘Q’ para sair da configuração e entre com o usuário sudo ou root.
Vamos criar uma pasta para os backups:
mkdir -p /home/nomedousuariolinux/logs
Aplique o seguinte comando para abrir o crontab no terminal:
sudo nano /home/nomedousuariolinux/backup_aut.sh
Adicione as linhas abaixo no final do arquivo
colocar esses dados:
#!/bin/bash
# ============================
# Backup automático do banco de dados Koha
# Somente o banco, sem arquivos extras
# ============================
DATA=$(date +%Y-%m-%d_%Hh%M)
DIR_BACKUP=“/var/backups”
DIR_LOG=“/home/nomedousuáriolinux/logs”
mkdir -p “$DIR_BACKUP”
mkdir -p “$DIR_LOG”
LOG_FILE=“$DIR_LOG/backup_$DATA.log”
echo “Iniciando backup em $DATA” >> “$LOG_FILE”
DB_NAME=“koha_library”
DB_USER=“koha_library”
DB_PASS=‘suasenha’
SQL_FILE=“$DIR_BACKUP/koha_library_$DATA.sql.gz”
# Dump apenas do banco
mysqldump -u"$DB_USER" -p"$DB_PASS" “$DB_NAME” | gzip > “$SQL_FILE”
if [ $? -ne 0 ]; then
echo “ERRO: Falha ao gerar o dump do banco!” >> “$LOG_FILE”
exit 1
fi
echo “Dump gerado: $SQL_FILE” >> “$LOG_FILE”
# Enviar para Google Drive e remover local
/usr/bin/rclone --config /root/.config/rclone/rclone.conf move “$SQL_FILE” gdrive:Backup_Koha >> “$LOG_FILE” 2>&1
if [ $? -eq 0 ]; then
echo “Backup enviado para o Drive e removido localmente.” >> “$LOG_FILE”
else
echo “ERRO: Falha ao enviar para o Drive. Arquivo local mantido.” >> “$LOG_FILE”
fi
# Limpeza de arquivos antigos (7 dias)
find “$DIR_BACKUP” -name “koha_library_*.sql.gz” -mtime +7 -exec rm {} ;
echo “Backup finalizado.” >> “$LOG_FILE”
Substitua nomedousuáriolinux
substitua ‘sua senha’ pela senha do banco de dados que tinhamos visto antes, e deixe a senha entre aspas simples:
sudo nano /etc/koha/sites/library/koha-conf.xml
(Como sempre Ctrl + O, entre e Ctrl + X para salvar e sair)
Agora vamos agendar esses backups:
crontab -e
coloque o texto, dessa forma está para fazer backup as 17:40, mude os números pra por o horário que quer, lembrando que primeiro os minutos e depois a hora, como está no texto
40 17 * * * /bin/bash /home/servidor/backup_aut.sh
Dar permissão:
sudo chmod +x /home/servidor/backup_aut.sh
Espere dar horário para ver se os backups estão indo para a pasta do Google Drive corretamente.
Configurações secundárias
Agora vamos ativar algumas configurações secundárias:
Ativar Plack, ele tira o modo cgi para deixar o sistema mais rápido:
sudo a2enmod headers proxy_http
sudo systemctl restart apache2
sudo koha-plack --enable library
sudo koha-plack --start library
Agora vamos adicionar o módulo de etiquetas:
sudo apt install glabels
Módulo para enviar email para os leitores:
sudo apt install postfix libsasl2-modules -y
Abra o arquivo:
crontab -e
cole
# 1. Gera os avisos de atraso às 08:00
00 08 * * * koha-shell library -c “/usr/share/koha/bin/cronjobs/overdue_notices.pl -v -t -e”
# 2. Processa e envia os e-mails da fila às 08:05
05 08 * * * koha-shell library -c “/usr/share/koha/bin/cronjobs/process_message_queue.pl -v”
(ctrl + o, enter, ctrl + x)
Agora para o sistema sempre estar atualizado para funcionar da melhor forma possível vamos habilitar as atualizações automáticas:
sudo apt update
sudo apt install unattended-upgrades
sudo dpkg-reconfigure --priority=low unattended-upgrades
Limpeza e reparo do banco de dados
crontab -e
cole:
0 4 1 * * /usr/bin/mysqlcheck -u root --auto-repair --optimize --all-databases
0 3 * * 0 /sbin/shutdown -r now
0 3 1 * * apt-get clean && apt-get autoremove -y
0 4 1 * * journalctl --vacuum-time=7d
(ctrl + O, enter, ctrl +x)
Segurança
Acionar o Firewall:
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 8080/tcp
sudo ufw allow 53682/tcp
sudo ufw enable
Serviço que protege as portas que estão abertas:
sudo apt install libapache2-mod-security2 -y
Atulizações de segurança:
sudo apt install unattended-upgrades
sudo dpkg-reconfigure --priority=low unattended-upgrades
Serviço para impedir ataques de bruteforce:
sudo apt install fail2ban -y
Antivírus:
sudo apt install clamav
Sempre importante atualizar em tempos em tempos para manter a segurança e estabilidade:
Atualizar o sistema
Para atualizar tando o sistema operacional quanto o Koha Digite:
sudo apt update && sudo apt upgrade -y && sudo apt autoremove -y