Como instalar o BookStack no Saplo (base de conhecimento empresarial)

O Confluence para uma equipa de dez pessoas pode custar algumas centenas de euros por mês, e a licença é cobrada por utilizador, por isso a fatura aumenta à medida que a equipa cresce, mesmo que uses apenas uma fração das funcionalidades. O BookStack é uma base de conhecimento de código aberto que não tenta ser o Jira, uma wiki e uma ferramenta de gestão de projetos ao mesmo tempo, mas faz uma coisa bem: organiza a documentação numa estrutura legível e oferece um editor simples. Abaixo, passo a passo, como configurar o BookStack no Saplo.

Porquê o BookStack em vez do Confluence

O Confluence tem duas características que mais afetam as equipas e agências mais pequenas:

• licença baseada no número de utilizadores - quanto mais pessoas tiverem acesso à documentação, maior será a fatura mensal, independentemente da frequência com que realmente a utilizam,
• interface abrangente com funcionalidades que a maioria das empresas nunca irá utilizar - integrações com o Jira, macros, modelos empresariais, enquanto a necessidade real é, muitas vezes, uma simples lista de procedimentos e instruções.

O BookStack organiza o conteúdo numa hierarquia simples: uma estante agrupa livros, um livro é dividido em capítulos e um capítulo em páginas. Essa estrutura, por si só, impõe ordem, para que a documentação não se transforme, com o tempo, numa coleção aleatória de subpáginas sem qualquer lógica, o que é um problema comum com as wikis normais.

Requisitos

Para instalares o BookStack na Saplo, precisas de:

• Uma Box com o Docker a funcionar (o motor ativa-o automaticamente ao instalar a partir do catálogo, é necessário o nesting num contentor, o que a Saplo tem por padrão),
• Mínimo de 512 MB de RAM livre na Box e 2 GB de espaço em disco, o que já está incluído no plano Box S (27 € por ano),
• Um domínio ou subdomínio *.saploapp.pl incluído em qualquer plano, onde será alojada a base de conhecimento,
• Uma base de dados MySQL, o motor cria-a automaticamente na base de dados partilhada da Saplo e injeta as credenciais de conexão no contentor, não precisas de configurar nada manualmente.

Instalação passo a passo

1. No Painel Saplo, acede ao Catálogo de aplicações e seleciona BookStack (categoria "Negócios").
2. Indica a Box com um mínimo de 512 MB de RAM livre, onde o BookStack será instalado, e o domínio ou subdomínio sob o qual a base de conhecimento funcionará.
3. Confirma a instalação. O motor cria uma base de dados MySQL, instala um contentor Docker com a imagem oficial lscr.io/linuxserver/bookstack, expõe-no apenas ao loopback da Box e conecta-o ao nginx, que o serve sob o domínio indicado com SSL gratuito. Apenas a porta 443 é exposta externamente, não a porta bruta do contentor.
4. O motor aguarda que o contentor inicie de facto e verifica isso após a conclusão de docker compose up, porque o sucesso do comando por si só não significa que o processo interno não tenha falhado um momento depois.
5. Após a conclusão da instalação, a base de conhecimento está disponível sob o domínio indicado.

Primeira configuração

A imagem do BookStack tem uma conta de administrador predefinida, portanto, ao contrário do WordPress ou do Ghost, não passas por um assistente de criação de conta na primeira vez que acedes.

1. Acede ao endereço do domínio, por exemplo, wiedza.saploapp.pl, e inicia sessão com os dados predefinidos admin@admin.com / password.
2. Imediatamente após iniciares sessão, altera a palavra-passe do administrador em Definições da conta, pois os dados de login predefinidos são publicamente conhecidos, e deixá-los, mesmo que por alguns minutos, é deixar uma porta aberta.
3. Cria a primeira Prateleira (Shelf), por exemplo "Procedimentos da empresa", e nela o primeiro Livro (Book), por exemplo "Onboarding de colaborador".
4. Dentro do livro, adiciona Capítulos (Chapters) e Páginas (Pages) com conteúdo. O editor funciona em modo WYSIWYG ou markdown, podes alternar nas definições da página.
5. Em Definições → Utilizadores e funções, adiciona outros membros da equipa e atribui-lhes uma função: visualizador, editor ou administrador. As permissões também podem ser definidas separadamente para uma prateleira ou livro individual.

BookStack na Saplo vs. Confluence

Perguntas Frequentes

O BookStack tem um limite no número de utilizadores ou páginas? Não, o número de contas e documentos é limitado apenas pelos recursos da Box, não pela licença, portanto, adicionar outra pessoa à equipa não tem custos.

É necessário criar uma base de dados separada antes da instalação? Não, o motor Saplo cria automaticamente uma base de dados MySQL e injeta os dados de conexão no contentor. Não precisas de nenhuma configuração externa para a instalação.

É possível migrar a documentação existente do Confluence para o BookStack? O BookStack não tem um importador pronto para o Confluence, mas suporta a importação de páginas individuais de ficheiros HTML e Markdown, portanto, a migração de uma base de dados maior requer exportação manual e colagem do conteúdo.

Porque é que o primeiro login é feito numa conta predefinida e não num assistente? É assim que funciona a imagem Docker oficial do BookStack, a conta admin@admin.com está incorporada na imagem de forma fixa, por isso o primeiro passo após a instalação deve ser sempre a alteração da palavra-passe.

Posso restringir o acesso a um livro selecionado apenas a parte da equipa? Sim, as permissões no BookStack são definidas não apenas globalmente através de funções, mas também separadamente para cada prateleira, livro, capítulo ou página.

Se tiveres dúvidas ao configurar o BookStack na tua Box ou ao organizar a documentação da empresa, escreve-nos, nós ajudaremos com a primeira configuração.