Como fazer self-host do Vikunja em 2026: URL pública, banco de dados e armazenamento de arquivos

Se você já tentou fazer self-host do Vikunja, provavelmente conhece este cenário frustrante: a interface aparece, mas a URL pública da API está errada ou os arquivos enviados não estão em um volume. Recriar o container raramente corrige uma divergência entre URLs, estado e dependências.

Este guia usa um critério concreto de conclusão — criar um projeto, uma tarefa, um anexo e um lembrete, mover a tarefa em um board e verificar o evento no calendário e a notificação. Cada escolha de configuração é avaliada com base nesse critério, e não apenas em um badge verde do container.

Do que o Vikunja depende

Estabeleça três limites ao redor do Vikunja: ingress para a porta 3456, estado durável e requisitos de suporte. O container pode ser substituído, mas os outros dois precisam de responsáveis explícitos. O contrato de rede do Vikunja, para equipes em produção, é Postgres ou MySQL e SMTP. Mantenha os endpoints privados em DNS interno, permita apenas as chamadas de saída necessárias e forneça ao Vikunja uma credencial de serviço com escopo limitado.

O diagrama está completo quando um cliente limpo consegue criar um projeto, uma tarefa, um anexo e um lembrete, mover a tarefa em um board e verificar o evento no calendário e a notificação. Colete dados de tempo e recursos para o tráfego de anexos, queries do banco de dados, jobs em background e e-mails de saída, em vez de observar apenas o pequeno processo da API. Se a transação falhar, o primeiro limite que não se comportar conforme documentado indicará se a investigação deve se concentrar no roteamento, na capacidade local ou em um serviço de suporte.

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

Liste o estado antes de criar o primeiro registro real: banco de dados, arquivos enviados e configuração. Monte /app/vikunja/files antes do bootstrap, grave dados de exemplo inofensivos e substitua o container para comprovar que esse caminho é realmente persistente. Confirme o mount gravando dados inofensivos, substituindo o Vikunja e lendo-os novamente.

Snapshots são valiosos para um rollback rápido, mas é necessário ter um backup independente quando o host ou o volume desaparece. Restaure em um ambiente vazio usando a imagem fixada e verifique se projetos, histórico de tarefas, anexos, lembretes e usuários retornam e se uma notificação agendada ainda é disparada. Use volumes persistentes e snapshots para manter esses dois mecanismos de recuperação distintos.

Proteja a parte valiosa do Vikunja

Depois do primeiro login, analise o que um visitante anônimo, um usuário comum e um administrador podem fazer. O problema do Vikunja que deve ser evitado é usar um secret JWT inalterado ou deixar o cadastro aberto acidentalmente. A política esperada é usar um secret JWT estável, fechar o cadastro quando o período de inclusão terminar e separar membros comuns de administradores de projetos.

Gere VIKUNJA_SERVICE_JWTSECRET como um valor longo e aleatório; a rotação normalmente invalida sessões ou tokens, portanto planeje o impacto para os usuários em vez de tratá-la como uma migração de encryption. Mantenha contas de dependências separadas das contas humanas, bloqueie o egress não utilizado sempre que possível e limite o trabalho influenciado pelo tráfego de anexos, queries do banco de dados, jobs em background e e-mails de saída, em vez de observar apenas o pequeno processo da API.

Transforme o smoke test do Vikunja em uma verificação de release

Um release candidate do Vikunja conquista o direito de receber tráfego ao concluir um cenário fixo: criar um projeto, uma tarefa, um anexo e um lembrete, mover a tarefa em um board e verificar o evento no calendário e a notificação. Registre o digest da imagem, a configuração efetiva sem secrets, a origem pública e os timestamps desse cenário. Os dados de teste devem ser descartáveis, mas realistas o suficiente para exercitar o mesmo caminho usado pelos usuários.

Execute o teste depois de substituir o runtime e, em seguida, reconstrua o serviço a partir do banco de dados, dos arquivos enviados e da configuração. A recuperação é aprovada quando projetos, histórico de tarefas, anexos, lembretes e usuários retornam e uma notificação agendada ainda é disparada. Compare as medições de recursos para o tráfego de anexos, queries do banco de dados, jobs em background e e-mails de saída — em vez de observar apenas o pequeno processo da API — com a release anterior e investigue desvios relevantes antes da promoção.

Por fim, exercite esta falha controlada: negue temporariamente à identidade de teste o acesso ao Postgres ou MySQL e ao SMTP para equipes em produção. Verifique se o Vikunja explica a falha, não danifica o estado existente e retoma a operação quando a condição válida retorna. Salve um trecho de log com dados sensíveis removidos e o tempo de recuperação. Juntas, essas verificações cobrem comportamento, durabilidade e operabilidade, em vez de apenas a disponibilidade do processo.

Crie um container substituível do Vikunja

O comando a seguir torna visível o limite do container sem fingir provisionar todos os serviços externos.

docker run -d \
  --name vikunja \
  --restart unless-stopped \
  -p 127.0.0.1:3456:3456 \
  -v vikunja-data:/app/vikunja/files \
  -e VIKUNJA_SERVICE_JWTSECRET=replace-with-a-long-random-value \
  vikunja/vikunja:latest

Antes de abrir o ingress, inspecione o ambiente resolvido, os mounts e o listener. Adicione as configurações de conexão revisadas para Postgres ou MySQL e SMTP para equipes em produção; use nomes privados para serviços privados. Um launch bem-sucedido termina quando você consegue criar um projeto, uma tarefa, um anexo e um lembrete, mover a tarefa em um board e verificar o evento no calendário e a notificação — não quando docker ps exibe Up.

Faça o roteamento do Vikunja sem mentir sobre HTTPS

Evite origens públicas temporárias e permanentes para o Vikunja. Em vez disso, defina VIKUNJA_SERVICE_PUBLICURL como a origem HTTPS exata, aponte o nome DNS escolhido para a rota da plataforma e faça proxy apenas para a porta 3456.

Execute esta ação de fora do host: crie um projeto, uma tarefa, um anexo e um lembrete, mova a tarefa em um board e verifique o evento no calendário e a notificação. Se o ingress falhar, o guia de troubleshooting de 502 aborda erros de porta e listener. Se o Vikunja receber a requisição, mas a URL pública da API estiver errada ou os arquivos enviados não estiverem em um volume, as evidências agora apontam para além do proxy.

Diagnostique um Vikunja que parece saudável

Para o Vikunja, monitore uma transação em vez de um processo: criar um projeto, uma tarefa, um anexo e um lembrete, mover a tarefa em um board e verificar o evento no calendário e a notificação. Combine a latência e a taxa de erros com o tráfego de anexos, queries do banco de dados, jobs em background e e-mails de saída, em vez de observar apenas o pequeno processo da API, para que um alerta identifique o componente limitado.

O ensaio de upgrade deve cobrir o fato de que as migrações do banco de dados e a compatibilidade entre frontend e API precisam ser testadas antes de alterar as versões do Vikunja. Restaure, migre e execute a transação antes da substituição em produção. Se a URL pública da API estiver errada ou os arquivos enviados não estiverem em um volume, não apague dados para deixar o startup verde; compare versão, variáveis, mounts e alcance das dependências, nessa ordem.

Faça deploy do Vikunja no Dockup sem perder seus limites

O Dockup pode assumir as partes substituíveis da plataforma: rotear o tráfego para a porta 3456, emitir o domínio e o certificado, injetar secrets, anexar armazenamento persistente e conectar o Vikunja a serviços gerenciados ou conectados de forma privada. Isso pode ser feito na infraestrutura do Dockup ou em um servidor que você conectar.

O trabalho de aceitação do Vikunja continua explícito. Depois do deploy com um clique, defina VIKUNJA_SERVICE_PUBLICURL como a origem HTTPS exata, conecte e teste Postgres ou MySQL e SMTP para equipes em produção e execute este cenário: crie um projeto, uma tarefa, um anexo e um lembrete, mova a tarefa em um board e verifique o evento no calendário e a notificação. Essa divisão é intencional: o Dockup elimina a configuração repetitiva de infraestrutura sem fingir que as funções da aplicação, as credenciais do provedor ou a política de restore se escolhem sozinhas.

Perguntas frequentes

O que o Vikunja precisa para um deploy em produção?

Roteie o container do Vikunja na porta 3456 por meio de uma única origem HTTPS. O requisito de rede de suporte é Postgres ou MySQL e SMTP para equipes em produção. Não considere o Vikunja pronto até conseguir criar um projeto, uma tarefa, um anexo e um lembrete, mover a tarefa em um board e verificar o evento no calendário e a notificação.

Quais dados do Vikunja devem fazer parte de um backup?

Torne /app/vikunja/files persistente e inclua o banco de dados, os arquivos enviados e a configuração no mesmo manifesto de recuperação. Um restore limpo do Vikunja só é aprovado quando projetos, histórico de tarefas, anexos, lembretes e usuários retornam e uma notificação agendada ainda é disparada.

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

Use HTTPS para a origem pública do Vikunja e mantenha a porta 3456 na rota interna. Aplique corretamente a configuração do Vikunja: defina VIKUNJA_SERVICE_PUBLICURL como a origem HTTPS exata. Para o Vikunja, 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 um upgrade do Vikunja deve ser testado?

Restaure o estado atual do Vikunja em um deploy isolado, aplique a versão candidata e repita a transação de aceitação. Dê atenção especial ao fato de que as migrações do banco de dados e a compatibilidade entre frontend e API precisam ser testadas antes de alterar as versões do Vikunja. Mantenha a imagem anterior do Vikunja até compreender os limites de migração de dados e rollback.