⚙
Instalação guiada
Pré-validação de sistema, disco, rede e portas; instalação e ajuste de Koha, MariaDB, Apache, Memcached e Plack, além de SWAP, NTP e fuso horário.
✦ Koha • Debian • Ubuntu • Windows 10/11
Koha sem a parte complicada.
O koha.nexus é um assistente inteligente, gratuito e fácil de usar para instalar, configurar, manter e ampliar o Koha Integrated Library System por meio de um painel amigável e guiado.
22 idiomasPainel e pacotes do Koha
2 sistemasLinux ou Windows via WSL 2
16+ recursosGestão, manutenção e biblioteca
GPL-3.0+Software livre e modificável
instalação — terminal
$ wget https://raw.githubusercontent.com/PauloFBaldiFH/koha.nexus/refs/heads/main/installer $ sudo bash installer KOHA.NEXUS ✓ Validando o servidor... ✓ Instalando Koha ✓ Configurando banco de dados ✓ Preparando backups ✓ Configurando acesso → Painel pronto: sudo config.sh
Tudo em um só lugar
Um painel pensado para quem precisa fazer a biblioteca funcionar.
Da instalação inicial ao backup, indexação, segurança, migração, catalogação e publicação na internet, os principais recursos ficam reunidos em um único ponto de controle.
🗄
Central de backups
Backups SQL comprimidos, exportação MARC21, cópias manuais e integração opcional com Google Drive usando rclone.
🛡
Restore seguro
O backup é validado e testado em banco temporário antes de qualquer substituição do catálogo atual.
⌕
Pesquisa e indexação
Alternância entre Zebra e Elasticsearch 7, watchdog do indexador e ferramentas de reparo e reconstrução.
☁
Publicação na internet
Cloudflare Tunnel sem necessidade de abrir portas, Certbot para SSL e assistente para Google Search Console.
🔐
Segurança
Fail2ban, firewall UFW, possibilidade de restringir o acesso ao staff em 8080 e rotação da senha do banco.
📚
Ferramentas de biblioteca
Importação, relatórios, qualidade do catálogo, privacidade LGPD, movimentação anual de categorias e mais.
🇧🇷
Localização brasileira
CPF, etiquetas Pimaco, ficha catalográfica, feriados, relatórios censitários e referências bibliográficas em ABNT.
💬
WhatsApp e Telegram
Entrega dos avisos do Koha por gateways de WhatsApp ou bot do Telegram, de forma opcional.
✂
Catalogação assistida
PHA ou Cutter-Sanborn, CDD, calculadora Cutter, substituição segura de registros MARC e auxílio de IA.
🪟
Windows + WSL 2
Executa o Koha em um único computador Windows, com atalhos, notificações, bandeja e ferramentas de diagnóstico.
↻
Autoatualização
Atualização do painel pelo GitHub com verificação SHA-256 do instalador.
Comece aqui
Instalação no Linux em poucos comandos.
O projeto é voltado para Debian 11/12/13 ou Ubuntu 22.04/24.04, em amd64 ou arm64, e também pode rodar no Windows por meio do WSL 2.
Instalador direto
Baixe o instalador atual e execute-o com privilégios administrativos.
bash
wget https://raw.githubusercontent.com/PauloFBaldiFH/koha.nexus/refs/heads/main/installer sudo bash installer
Clonar o repositório
Também é possível manter os arquivos de tradução junto do script e trabalhar offline.
bash
git clone https://github.com/PauloFBaldiFH/koha.nexus.git cd koha.nexus sudo bash installer
Requisitos mínimos
- Debian 11/12/13 ou Ubuntu 22.04/24.04, 64-bit
- 2 GB de RAM; 4 GB ou mais recomendado
- 5 GB livres; 10 GB ou mais recomendado
- root ou usuário com sudo
- Acesso à internet para os repositórios do Koha
- Portas 80 e 8080 livres
Depois da instalação
- Abra o staff em
http://SERVER-IP:8080 - Finalize o Web Installer do Koha
- Crie seu super librarian pelo painel
- O catálogo público fica em
http://SERVER-IP:80 - Reabra o painel a qualquer momento com
sudo config.sh
Windows 10 / 11
Um Koha completo em um único PC, usando WSL 2.
A edição para Windows foi pensada para bibliotecas pequenas, treinamento e avaliação, mantendo os serviços do Koha dentro de Debian no WSL 2 e oferecendo ferramentas nativas no Windows.
🪟
Instalação
Abra o PowerShell normalmente e execute:
PowerShell
[Net.ServicePointManager]::SecurityProtocol='Tls12'; irm https://raw.githubusercontent.com/PauloFBaldiFH/koha.nexus/main/windows/install.ps1 | iex
Mais fácil: o botão acima baixa o
Install-Koha.cmd. Não é necessário abrir o PowerShell manualmente.
WSL 2
Debian
systemd
Windows Terminal
Notificações
Bandeja do sistema
1
Verificação do computador
Confere Windows compatível, arquitetura 64-bit, memória, espaço livre e virtualização habilitada no BIOS.
2
WSL 2 + Debian
Instala o WSL 2, prepara o Debian e configura o usuário administrativo e o systemd.
3
Ambiente Koha
Instala o Koha dentro do Debian e cria os atalhos, tarefas agendadas e ferramentas de controle do Windows.
4
Rede da biblioteca
Configura o acesso dos outros computadores da rede e testa as portas 80 e 8080.
5
Operação diária
Start, Stop, Restart, status, diagnóstico, reconstrução do índice e desligamento seguro ficam acessíveis sem abrir um console.
Notificações
Quedas, recuperação, backups, pouco espaço e desligamentos não limpos podem gerar alertas no Windows.
Diagnóstico em um clique
Exporta logs e informações úteis para suporte, removendo senhas, tokens e chaves.
Parada segura
O Koha é encerrado por etapas antes do WSL e do Windows serem desligados.
Ferramentas de biblioteca
Mais do que instalar o Koha: cuidar do acervo.
As ferramentas do painel utilizam os mecanismos do próprio Koha e seguem um fluxo de proteção com bloqueio, pré-visualização, confirmação e backup verificado antes de alterações.
🪄
Magic Import Tool
Uma única porta de entrada para planilhas, MARC, arquivos compactados, acervo, exemplares, usuários e dados de circulação.
CSV • TSV • XLSX • ODS • DBF • MARC21 • MARCXML↶
Desfazer importação MARC
Permite reverter um lote de importação de forma controlada, preservando a segurança do catálogo.
📊
Pacote de relatórios SQL
Relatórios somente leitura para empréstimos, atrasos, aquisições, itens sem código, obras nunca emprestadas e itens perdidos.
🔄
Troca de categorias por ano letivo
Move usuários entre categorias utilizando critérios definidos pela biblioteca, com dry run antes da execução.
🧪
Qualidade dos dados
Executa a verificação de inconsistências do catálogo sem alterar os registros.
🔒
Privacidade e LGPD
Anonimização de históricos antigos e exclusão controlada de usuários expirados que atendam aos critérios definidos.
Proteção por padrão: as operações que alteram dados seguem lock compartilhado com backup,
prévia, confirmação e cópia
PRE-* verificada antes da mudança.
Catalogação
PHA, Cutter-Sanborn, CDD e IA trabalhando junto do catalogador.
O projeto reúne ferramentas auxiliares para classificação, notação de autor, cálculo de Cutter e substituição segura de registros MARC, sem retirar do profissional a etapa de revisão.
A
Notação de autor
Usa a própria tabela PHA ou Cutter-Sanborn carregada pela biblioteca e mostra os números já utilizados no catálogo.
▥
Consulta CDD
Pesquisa por número ou assunto a partir da cópia da CDD da própria biblioteca, com integração ao formulário de catalogação.
✂
Cutter Calculator
Calcula a notação, sugere classes a partir do catálogo e pode preencher 090, 092 ou o campo de chamada do exemplar.
M
Replace a MARC record
Substitui um registro por MARC ou XML através de preview, lock transacional e salvamento da versão anterior.
🤖
AI cataloguing
Recebe fotos da capa, folha de rosto e verso, gera uma proposta de registro e aplica regras catalográficas antes da revisão.
👁
Modelos locais ou em nuvem
Suporta serviços compatíveis com OpenAI e modelos locais via Ollama ou LM Studio, sem incluir tokens no painel.
Fluxo da catalogação com IA
- Fotos do livro e instruções opcionais
- Resposta estruturada em JSON
- Aplicação de regras AACR2/ISBD e MARC
- Revisão pelo bibliotecário/operador
- Preview obrigatório antes de gravar
- Registro e resposta do modelo podem ser preservados para auditoria
Princípio importante
A IA funciona como assistente de catalogação. A proposta gerada é revisada
e só então enviada ao Koha. O projeto também prevê mecanismos para não inventar campos
sem suporte nas fotografias ou no contexto fornecido.
Brasil: localization
Recursos pensados para a rotina das bibliotecas brasileiras.
Os recursos brasileiros são opt-in: nada é aplicado automaticamente durante a instalação ou por agendamento.
| Recurso | O que oferece | Proteção |
|---|---|---|
| CPF | Auditoria de CPF usando dígitos verificadores e identificação de números compartilhados. | Somente leitura até confirmação |
| Etiquetas Pimaco | Modelos para folhas A4 e Letter, incluindo espinha, código de barras e título. | PRE-LABELS |
| Ficha catalográfica | Ficha em estilo usado por bibliotecas brasileiras, integrada à visualização do registro e com referência ABNT. | PRE-FICHA |
| Calendário brasileiro | Feriados nacionais e datas móveis, com opção de feriado municipal. | PRE-CALENDAR |
| Censos | Relatórios para indicadores relacionados a MEC, INEP, IBGE e SNBP, conforme os dados existentes no Koha. | PRE-CENSO |
| ABNT NBR 6023:2018 | Geração de referências e bibliografias a partir dos registros MARC21 em HTML e texto. | Somente leitura |
Observação: os dados dos censos representam o que está registrado no Koha.
O README recomenda conferir cada resultado contra o formulário oficial antes do envio.
Operação e segurança
Automação sem esconder o que está acontecendo.
O painel centraliza tarefas recorrentes e mostra os pontos importantes para manutenção, diagnóstico e recuperação.
Automação padrão
| Quando | Tarefa |
|---|---|
| Diariamente 23:00 | Backup SQL comprimido e upload opcional para a nuvem |
| Domingos 03:00 | Exportação MARC21 |
| Diariamente 01:30 | Limpeza de sessões e fila do Zebra |
| Diariamente 05:00 | Reinício do Plack |
| A cada 2 min | Watchdog do indexador Zebra |
| A cada 5 min | Watchdog do Elasticsearch, quando usado |
Arquivos importantes
/root/koha_credentials.txt— credenciais iniciais/var/backups/koha_sql— backups SQL/var/backups/koha_marc— backups MARC/etc/koha-easy-install/— configurações do painel/var/log/koha-easy-install/— logs do painel e validações~/importar— pasta de entrada da Magic Import Tool
Diagnóstico
O painel reúne status, checagem de saúde, logs do Apache, manutenção profunda do banco e relatórios prontos para suporte.
health check
Apache logs
MariaDB
Koha
logs
Falha de energia
O projeto prevê verificação após um reboot não limpo, criação de novo backup e atualização do índice quando necessário. No Windows, a rotina de desligamento seguro tenta parar o Koha antes do sistema.
Desinstalação é destrutiva: o
uninstall.sh remove permanentemente o Koha,
bancos de dados, backups locais e configurações. Faça cópias fora do servidor antes de usar.
Projeto livre
Feito para ser usado, estudado e melhorado.
O projeto inclui testes, traduções, ferramentas para colaboradores e verificação do checksum do instalador para atualização automática.
🧪
Testes
Conjunto de testes Bats para backup/restore, indexação, ferramentas de biblioteca, WSL e componentes Windows.
🌎
Traduções
Dicionários versionados por idioma, validação de cobertura e rejeição automática de traduções que perdem variáveis.
🔏
Verificação
O instalador usa SHA-256 para validar sua própria atualização.
Licença
GNU General Public License v3.0 ou posterior (GPL-3.0-or-later). O projeto pode ser usado, estudado, compartilhado e modificado. Distribuições modificadas devem continuar sob GPL e disponibilizar o código-fonte correspondente. O software é fornecido sem garantia.