Como fazer self-hosting do Kanboard em 2026: SQLite, plugins e upgrades seguros

Uma implantação do Kanboard que falha nem sempre trava. Ela pode exibir uma página de login enquanto o SQLite não consegue gravar porque o diretório de dados montado pertence ao usuário errado. Comece por uma verificação de ponta a ponta: substitua o login padrão, crie um projeto e uma tarefa, mova-a entre colunas, faça upload de um arquivo e teste um plugin instalado.

Essa verificação corresponde ao propósito catalogado do Kanboard: um quadro kanban minimalista baseado em SQLite. Ela também revela dependências ausentes, suposições incorretas sobre o proxy e dados efêmeros antes que um uptime probe consiga detectar esses problemas.

Separe o Kanboard das dependências

A menor topologia responsável para o Kanboard contém um listener privado na porta 80, uma rota de ingress e uma fronteira de estado documentada. O requisito do runtime local é um volume de dados com permissão de escrita e SMTP opcional. Mantenha o ciclo de vida explícito para que mover o Kanboard entre hosts não altere o comportamento silenciosamente.

Valide a topologia pedindo que um cliente limpo substitua o login padrão, crie um projeto e uma tarefa, mova-a entre colunas, faça upload de um arquivo e teste um plugin instalado. Observe o locking do SQLite, o volume de anexos, as ações em background e o comportamento do plugin com usuários simultâneos enquanto o sistema estiver em execução. O resultado mostra se a próxima melhoria deve ser feita em memória, armazenamento, rede ou em um worker separado, em vez de incentivar um dimensionamento arbitrário do container.

Domínios, cabeçalhos do proxy e porta 80

A emissão de TLS é apenas metade da rota do Kanboard. Disponibilize o quadro por HTTPS e defina a URL da aplicação se os plugins precisarem dela. Envie o tráfego internamente para a porta 80 e encaminhe o esquema externo para que as URLs geradas e os secure cookies permaneçam consistentes.

Use o cenário completo do Kanboard a partir de uma rede limpa, não apenas a página raiz. Um erro 502 ou de certificado pode ser isolado com a configuração automática de domínio e TLS. Se o tráfego chegar ao processo e o SQLite não conseguir gravar porque o diretório de dados montado pertence ao usuário errado, diagnostique essa condição no ponto em que ela ocorre, em vez de acumular redirects.

Torne a inicialização do Kanboard reproduzível

Uma inicialização com formato de produção é intencionalmente simples: estado nomeado, porta explícita e nenhum secret dentro da imagem.

docker run -d \
  --name kanboard \
  --restart unless-stopped \
  -p 127.0.0.1:80:80 \
  -v kanboard-data:/var/www/app/data \
  kanboard/kanboard:latest

O exemplo é uma base, não uma stack de suporte completa. Confirme o requisito local antes de expor o serviço: um volume de dados com permissão de escrita e SMTP opcional. Verifique os mounts efetivos e o listener; depois, tente substituir o login padrão, criar um projeto e uma tarefa, movê-la entre colunas, fazer upload de um arquivo e testar um plugin instalado. Fixe a imagem que está funcionando antes do próximo restart.

Monitore a carga de trabalho, não apenas o container

Para o Kanboard, monitore uma transação em vez de um processo: substitua o login padrão, crie um projeto e uma tarefa, mova-a entre colunas, faça upload de um arquivo e teste um plugin instalado. Combine a latência e a taxa de erros com o locking do SQLite, o volume de anexos, as ações em background e o comportamento do plugin com usuários simultâneos, para que um alerta identifique o componente limitado.

O ensaio de upgrade deve abranger o fato de que database migrations e compatibilidade de plugins exigem um snapshot antes de uma atualização da imagem do Kanboard. Faça o restore, execute a migration e rode a transação antes da substituição em produção. Se o SQLite não conseguir gravar porque o diretório de dados montado pertence ao usuário errado, não apague os dados para deixar a inicialização verde; compare versão, variáveis, mounts e alcance das dependências, nessa ordem.

Comprove a implantação do Kanboard de ponta a ponta

Um production gate para o Kanboard deve poder ser executado por alguém que não tenha criado a implantação. Forneça a essa pessoa a versão fixada, uma conta de teste não sensível e esta tarefa: substituir o login padrão, criar um projeto e uma tarefa, movê-la entre colunas, fazer upload de um arquivo e testar um plugin instalado. Se as instruções exigirem acesso ao shell não documentado, o serviço ainda não está operacionalmente pronto.

Repita o gate depois de substituir apenas o container. Em seguida, restaure o database SQLite, os arquivos enviados, os plugins e a configuração em uma infraestrutura vazia e comprove que os projetos, o histórico de tarefas, os usuários, os anexos e os plugins retornam e que o quadro restaurado aceita uma nova tarefa. Meça o locking do SQLite, o volume de anexos, as ações em background e o comportamento do plugin com usuários simultâneos durante as duas execuções bem-sucedidas; diferenças inesperadas geralmente revelam um cache, índice, worker ou mount de dados ausente.

Adicione um failure drill: envie uma entrada inofensiva próxima do limite de recurso ou formato associado a esta fronteira: o SQLite não consegue gravar porque o diretório de dados montado pertence ao usuário errado. O Kanboard deve emitir um erro útil, preservar o estado existente e se recuperar quando a condição válida retornar. Salve os timestamps e as linhas de log relevantes, com os secrets ocultados. Essas evidências se tornam a referência para a próxima alteração de imagem ou configuração.

Volumes são apenas a primeira camada de recuperação

Crie um recovery manifest para o Kanboard: database SQLite, arquivos enviados, plugins e configuração. Monte /var/www/app/data antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Verifique agora a propriedade e o espaço livre, porque um caminho montado, mas sem permissão de escrita, se comporta como se não houvesse persistência alguma.

Faça backup em um failure domain separado do servidor em execução. Recrie o Kanboard a partir da imagem fixada e verifique se os projetos, o histórico de tarefas, os usuários, os anexos e os plugins retornam e se o quadro restaurado aceita uma nova tarefa. O guia de persistent volumes ajuda a transformar esse exercício em uma política de snapshots e retenção.

Proteja a parte valiosa do Kanboard

Uma implantação segura do Kanboard começa pela remoção de privilégios. Evite manter as credenciais padrão admin/admin; em vez disso, remova admin/admin imediatamente, restrinja o acesso aos projetos e revise os plugins antes de conceder a eles acesso aos dados de produção.

O Kanboard não exige um secret de bootstrap neste baseline; proteja a conta de administrador real ou a autenticação upstream. Restrinja as rotas administrativas, use DNS privado para as dependências e revise cada bind mount. Quando os logs forem enviados para um sistema central, filtre secrets e conteúdo privado antes que saiam do servidor.

Onde o Dockup elimina trabalho no Kanboard

Um template do Dockup deve codificar a imagem, a porta 80, os mounts, o timing do health check, o domínio, o TLS e a entrega de secrets. O Dockup deve preservar as configurações do runtime do Kanboard enquanto o operador confirma este requisito local: um volume de dados com permissão de escrita e SMTP opcional. A mesma implantação pode ser direcionada para servidores Dockup ou para capacidade anexada pelo cliente.

Depois que a rota estiver ativa, aplique a configuração pública e tente substituir o login padrão, criar um projeto e uma tarefa, movê-la entre colunas, fazer upload de um arquivo e testar um plugin instalado. Faça backup do database SQLite, dos arquivos enviados, dos plugins e da configuração e mantenha o exercício de restore no plano operacional; essas são responsabilidades do Kanboard que continuam visíveis depois do provisionamento da infraestrutura.

Perguntas frequentes

O que o Kanboard precisa para uma implantação em produção?

Direcione o container do Kanboard na porta 80 por meio de uma única origem HTTPS. O requisito do runtime local é um volume de dados com permissão de escrita e SMTP opcional. Não considere o Kanboard pronto até conseguir substituir o login padrão, criar um projeto e uma tarefa, movê-la entre colunas, fazer upload de um arquivo e testar um plugin instalado.

Quais dados do Kanboard devem fazer parte de um backup?

Persista /var/www/app/data e inclua o database SQLite, os arquivos enviados, os plugins e a configuração no mesmo recovery manifest. Um restore limpo do Kanboard só é bem-sucedido quando os projetos, o histórico de tarefas, os usuários, os anexos e os plugins retornam e o quadro restaurado aceita uma nova tarefa.

O Kanboard exige HTTPS atrás de um reverse proxy?

Use HTTPS para a origem pública do Kanboard e mantenha a porta 80 na rota interna. Aplique corretamente a configuração do Kanboard: disponibilize o quadro por HTTPS e defina a URL da aplicação se os plugins precisarem dela. Para o Kanboard, o HTTPS protege credenciais ou conteúdo de usuários durante o trânsito e mantém consistente o comportamento do cliente sensível à origem.

Como testar um upgrade do Kanboard?

Restaure o estado atual do Kanboard em uma implantação isolada, aplique a versão candidata e repita a transação de aceitação. Preste atenção especial, porque database migrations e compatibilidade de plugins exigem um snapshot antes de uma atualização da imagem do Kanboard. Mantenha a imagem anterior do Kanboard até entender os limites de data migration e rollback.