Como instalar o HedgeDoc na Saplo (edição colaborativa de documentos Markdown em tempo real)

Tomar notas de uma reunião, enquanto o resto da equipa espera ou adiciona comentários ao lado no chat, é mais lento do que escrever o mesmo documento em conjunto e em tempo real. O Notion e o Dropbox Paper conseguem fazer isso, mas à custa de uma conta na cloud de terceiros e de uma subscrição que aumenta com o número de pessoas na equipa. O HedgeDoc é um editor Markdown de código aberto onde várias pessoas trabalham no mesmo documento em simultâneo, veem os cursores e as alterações dos outros em tempo real, e tu podes instalá-lo no teu próprio Box. Abaixo, passo a passo, como instalar o HedgeDoc no Saplo.

Porquê HedgeDoc em vez de Notion ou Dropbox Paper

As ferramentas pagas de edição colaborativa de documentos têm duas características que mais afetam as pequenas equipas e os freelancers:

• o preço aumenta com o número de pessoas - o plano gratuito geralmente é suficiente para uma pessoa, e adicionar cada colaborador extra à equipa no Notion ou ferramenta similar é um item separado na fatura a cada mês,
• o conteúdo dos documentos está num servidor de terceiros - notas de reuniões, planos de projetos e rascunhos de textos estão nas mãos de uma empresa externa, não nas tuas.

HedgeDoc funciona como um contentor Docker com o seu próprio contentor PostgreSQL na tua Box, para que todo o conteúdo dos documentos e o histórico de edições permaneçam na tua infraestrutura, sem taxa por pessoa e sem limite no número de documentos.

HedgeDoc, Trilium e Wiki.js/BookStack: três nichos de notas diferentes no catálogo Saplo

No catálogo Saplo já temos Trilium Notes, Wiki.js e BookStack, então a pergunta natural é: qual a diferença entre eles e HedgeDoc? A resposta está na finalidade de cada uma dessas ferramentas:

• Trilium Notes é um bloco de notas para uma única pessoa - uma base de conhecimento e notas hierárquica, construída por um único utilizador ao longo do tempo, sem foco na edição em tempo real por várias pessoas em simultâneo.
• Wiki.js e BookStack são wikis empresariais com versionamento de páginas, estrutura de categorias e permissões - ideais para documentação com uma estrutura fixa e histórico de alterações, mas não para um rascunho rápido e colaborativo em tempo real.
• HedgeDoc foca-se exclusivamente na edição simultânea e em tempo real de um único documento Markdown - vês os cursores dos outros participantes e as suas alterações em direto, sem a estrutura de uma base de conhecimento completa e sem um sistema de permissões como num wiki empresarial.

Se estás a construir uma base de conhecimento pessoal, experimenta Trilium. Se a tua equipa precisa de documentação estruturada com histórico de versões, escolhe Wiki.js ou BookStack. Se o objetivo é escrever notas de reunião ou um rascunho de texto em tempo real, aqui e agora, em colaboração com alguém, HedgeDoc é a melhor opção.

Requisitos

Para instalares o HedgeDoc no Saplo, precisas de:

• Uma Box com o Docker ativado (o motor liga-o automaticamente na instalação a partir do catálogo, é necessário nesting no contentor, que o Saplo tem por predefinição),
• Um mínimo de 1 GB de RAM livre na Box e 2 GB de espaço em disco, ou seja, o plano Box M (65 €/ano) ou superior,
• Um domínio ou subdomínio *.saploapp.pl, incluído em todos os planos, onde o editor será alojado,
• NÃO precisas de criar uma base de dados separada manualmente - o HedgeDoc requer uma base de dados SQL, e o motor configura um contentor PostgreSQL dedicado no mesmo docker-compose (a base de dados partilhada do Saplo apenas suporta MySQL/MariaDB).

Instalação passo a passo

1. No painel da Saplo, vai a Catálogo de aplicações e escolhe HedgeDoc (categoria "Negócios").
2. Indica uma Box com, no mínimo, 1 GB de RAM livre para o editor e o domínio ou subdomínio onde irá funcionar.
3. Confirma a instalação. O motor cria um contentor a partir da imagem oficial quay.io/hedgedoc/hedgedoc juntamente com um contentor dedicado postgres:15-alpine, gera uma password aleatória para a base de dados e um segredo de sessão aleatório. Em seguida, expõe a aplicação exclusivamente no loopback da Box, que está ligado ao nginx, que a serve sob o domínio indicado com SSL gratuito. Apenas a porta 443 é exposta externamente, não a porta bruta do contentor.
4. Após docker compose up, o motor verifica adicionalmente se a página HedgeDoc realmente responde via HTTP, porque o primeiro arranque do contentor faz migrações do esquema da base de dados e pode demorar mais do que os típicos segundos, pelo que o estado de "contentor em funcionamento" ainda não significa que a aplicação esteja pronta.
5. A edição colaborativa funciona através de websocket no mesmo domínio da aplicação - não requer nenhuma configuração adicional no lado do cliente ou uma porta separada.

Primeira configuração

O HedgeDoc, ao contrário do Directus ou do Wiki.js, não tem o conceito de conta de administrador - qualquer pessoa que se registe é um utilizador comum e vê apenas os seus próprios documentos e aqueles para os quais recebeu um link.

1. Acede ao endereço de domínio, por exemplo, notatki.saploapp.pl, e cria a primeira conta no assistente de registo, na primeira vez que acederes ao site.
2. Cria um novo documento com o botão New note - recebes um link de edição exclusivo que envias a qualquer pessoa que precise de colaborar no conteúdo.
3. Os colaboradores abrem o mesmo link e veem imediatamente os cursores e as alterações de outras pessoas em tempo real, sem a necessidade de criar uma conta própria, se o documento tiver acesso aberto para edição.
4. Exportas o documento concluído para PDF, HTML ou um ficheiro Markdown puro a partir do menu do documento, ou partilhas apenas para leitura com um link separado.
5. Podes ver o histórico de versões do documento na vista Revision, o que te permite reverter para conteúdo anterior sem ter de copiar manualmente as cópias de segurança.

HedgeDoc na Saplo vs. Notion e Dropbox Paper

Perguntas Frequentes

O HedgeDoc precisa de uma base de dados separada? Sim, ao contrário de algumas aplicações no catálogo da Saplo, o HedgeDoc requer uma base de dados SQL, por isso o motor cria um contentor PostgreSQL dedicado para ele no mesmo docker-compose, não utilizando a base de dados Saplo partilhada disponível apenas para MySQL/MariaDB.

Qual a diferença entre o HedgeDoc e o Trilium Notes, já que ambos estão no catálogo da Saplo? O Trilium é um bloco de notas hierárquico para uma pessoa, construído ao longo do tempo. O HedgeDoc foca-se na edição simultânea e em tempo real de um único documento por várias pessoas.

É preciso criar uma conta para editar um documento em conjunto? Não, se o documento tiver acesso de edição aberto, basta o link - só crias uma conta para teres uma lista dos teus próprios documentos guardados permanentemente.

É possível exportar um documento pronto para fora do HedgeDoc? Sim, no menu do documento podes exportar o conteúdo para PDF, HTML ou um ficheiro Markdown puro.

Se a tua equipa escreve notas e rascunhos em conjunto, em tempo real, e procura um editor simples para isso, sem uma subscrição por pessoa, contacta-nos, e nós ajudamos-te a escolher a Box certa para a tua equipa.