Vikunja Self-Hosted: Tutorial de Instalação em VPS Linux

Introdução ao Gerenciamento de Projetos Self-Hosted

No cenário atual de DevOps e desenvolvimento de software, a gestão eficiente de tarefas é tão crítica quanto a infraestrutura que sustenta as aplicações. Embora ferramentas como Jira e Trello sejam populares, elas muitas vezes apresentam barreiras de custo, complexidade excessiva ou preocupações com privacidade de dados ao armazenar informações sensíveis em nuvens públicas. Para profissionais que valorizam o controle total sobre seus dados e desejam uma solução leve, rápida e personalizável, a abordagem self-hosted (hospedagem própria) surge como a alternativa mais robusta.

O Vikunja destaca-se neste ecossistema como uma ferramenta open-source moderna, construída com Go no backend e Vue.js no frontend. Diferente de alternativas mais antigas que podem parecer datadas visualmente ou lentas na interação, o Vikunja oferece uma experiência de usuário fluida, suportando visualizações em Kanban, Lista e Calendário, além de uma API RESTful completa para automações. Este tutorial técnico guiará você através do processo completo de instalação do Vikunja self-hosted em uma VPS Linux, utilizando Docker e Docker Compose para garantir isolamento, facilidade de atualização e persistência de dados.

Pré-requisitos e Preparação do Ambiente

Antes de iniciar a instalação, é fundamental garantir que o ambiente esteja preparado corretamente. Recomendamos o uso de um sistema operacional moderno e estável, como Ubuntu 22.04 LTS ou Debian 12, rodando em uma VPS com pelo menos 1GB de RAM para garantir boa performance na renderização do frontend e processamento de consultas ao banco de dados.

Primeiramente, atualize o sistema operacional e instale as dependências básicas necessárias para o gerenciamento de pacotes e a compilação futura de extensões, se necessário.

sudo apt update
sudo apt upgrade -y
sudo apt install curl wget git ufw -y

Com o sistema atualizado, vamos garantir que as regras de firewall permitam apenas o tráfego essencial. Para este tutorial, assumiremos que você acessará a interface web através de um domínio ou subdomínio (ex: kanban.seudominio.com). Portanto, precisamos liberar as portas 80 (HTTP) e 443 (HTTPS), além da porta SSH (geralmente 22).

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

Verifique o status do firewall para confirmar que as regras foram aplicadas corretamente:

sudo ufw status

Instalação do Docker e Docker Compose

O Docker é a tecnologia central deste tutorial. Ele nos permite empacotar o Vikunja, seu banco de dados (PostgreSQL) e até mesmo o servidor web (Nginx) em contêineres isolados. Isso facilita drasticamente o backup, a migração e a atualização do sistema.

A instalação do Docker pode ser feita através dos repositórios oficiais para garantir que você tenha sempre a versão mais recente e segura. Execute os seguintes comandos no seu terminal:

sudo apt install ca-certificates curl gnupg lsb-release -y
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Após a instalação, adicione seu usuário atual ao grupo docker para que você não precise usar sudo para cada comando do Docker (embora seja recomendado manter o sudo por segurança em scripts de produção):

sudo usermod -aG docker $USER

Para aplicar as mudanças de grupo sem reiniciar a sessão, execute:

newgrp docker

Estruturação do Projeto e Configuração do Docker Compose

Agora que o motor está pronto, vamos criar a estrutura de diretórios para o nosso projeto Vikunja. Criar uma pasta dedicada ajuda a manter a organização, especialmente se você planeja adicionar outras ferramentas no futuro.

sudo mkdir -p /opt/vikunja
cd /opt/vikunja

Dentro desta pasta, criaremos um arquivo docker-compose.yml. Este arquivo define como os contêineres serão orquestrados. Abaixo está uma configuração robusta que inclui o serviço principal do Vikunja e um banco de dados PostgreSQL dedicado para melhor desempenho e confiabilidade.

Crie o arquivo usando seu editor de texto preferido (como nano):

sudo nano docker-compose.yml

Insira o seguinte conteúdo. Preste atenção especial às variáveis de ambiente, pois elas definem as credenciais de acesso e a URL pública da aplicação.

version: '3'
services:
  db:
    image: postgres:15-alpine
    restart: unless-stopped
    volumes:
      - db-data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: vikunja
      POSTGRES_USER: vikunja
      POSTGRES_PASSWORD: senha_segura_aqui_123 # Altere para uma senha forte

  app:
    image: Vikunja/vikunja
    restart: unless-stopped
    ports:
      - "3456:3456"
    volumes:
      - ./files:/srv/vikunja/files
    environment:
      VIKUNJA_SERVICE_PUBLICURL: http://localhost:3456/
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_PASSWORD: senha_segura_aqui_123 # Deve ser a mesma do serviço db
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_DATABASE: vikunja
      VIKUNJA_SERVICE_JWTSECRET: segredo_jwt_aleatorio_seguro # Gere um hash aleatório
    depends_on:
      - db

volumes:
  db-data:

Nota Importante de Segurança: O campo VIKUNJA_SERVICE_JWTSECRET é crucial para a segurança da sessão. Você deve gerar uma string aleatória longa para este valor. Você pode gerar uma usando o comando no terminal: openssl rand -hex 32. Copie a saída e substitua o texto placeholder no arquivo YAML.

Além disso, altere senha_segura_aqui_123 para uma senha forte e única que você criou. A variável VIKUNJA_SERVICE_PUBLICURL deve refletir a URL onde o serviço será acessado externamente (ex: https://kanban.seudominio.com). Por enquanto, manteremos como localhost para testar a conexão interna, mas atualizaremos isso após configurar o Nginx.

Salve o arquivo (Ctrl+O, Enter) e saia do editor (Ctrl+X).

Inicialização dos Contêineres e Verificação

Com o arquivo de configuração salvo, podemos iniciar os serviços. O Docker Compose baixará as imagens necessárias (Vikunja e PostgreSQL) se elas não estiverem presentes em sua máquina.

sudo docker compose up -d

O sinalizador -d executa os contêineres em segundo plano (modo detached). Para verificar se tudo está funcionando corretamente, liste os contêineres em execução:

sudo docker ps

Você deve ver dois contêineres: um rotulado como vikunja_app e outro como vikunja_db, ambos com o status "Up". Se houver algum erro, verifique os logs do contêiner da aplicação:

sudo docker logs vikunja_app_1

Acesse agora o endereço IP público da sua VPS seguido da porta 3456 (ex: http://SEU_IP_VPS:3456). Você deverá ver a tela de login do Vikunja. O usuário padrão é admin e a senha é também admin. Faça login e altere a senha imediatamente nas configurações da conta.

Configuração do Nginx como Reverse Proxy

Acessar via IP e porta não é ideal para produção. Precisamos configurar um servidor web (Nginx) para atuar como um Reverse Proxy, redirecionando as requisições de HTTPS para o contêiner Docker que roda na porta 3456. Isso também nos permite instalar certificados SSL gratuitos via Let's Encrypt.

Instale o Nginx e o Certbot (ferramenta para gerenciamento de certificados):

sudo apt install nginx certbot python3-certbot-nginx -y

Crie um arquivo de configuração de servidor no Nginx:

sudo nano /etc/nginx/sites-available/vikunja

Insira a seguinte configuração, substituindo kanban.seudominio.com pelo seu domínio real:

server {
    listen 80;
    server_name kanban.seudominio.com;

    location / {
        proxy_pass http://localhost:3456;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support for real-time updates
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Ative a configuração criando um link simbólico para a pasta sites-enabled e teste a sintaxe do Nginx:

sudo ln -s /etc/nginx/sites-available/vikunja /etc/nginx/sites-enabled/
sudo nginx -t

Se o teste for bem-sucedido, reinicie o Nginx:

sudo systemctl restart nginx

Habilitando HTTPS com Let's Encrypt

Agora que o domínio aponta para o servidor e o Nginx está configurado, vamos solicitar um certificado SSL. Certifique-se de que o registro DNS do seu domínio aponta corretamente para o IP da VPS antes de prosseguir.

sudo certbot --nginx -d kanban.seudominio.com

O Certbot fará perguntas interativas. Aceite os termos de serviço, insira seu e-mail e escolha se deseja redirecionar todo o tráfego HTTP para HTTPS (recomendado). Após a conclusão, o certificado será instalado e o Nginx será configurado automaticamente para usar HTTPS.

Agora, volte ao arquivo docker-compose.yml e atualize a variável VIKUNJA_SERVICE_PUBLICURL para refletir o novo endereço HTTPS:

VIKUNJA_SERVICE_PUBLICURL: https://kanban.seudominio.com/

Reinicie os contêineres para aplicar a nova configuração:

sudo docker compose down
sudo docker compose up -d

Mantendo o Sistema Atualizado e Seguro

Uma das grandes vantagens de usar Docker para vikunja tutorial vps é a simplicidade das atualizações. Quando uma nova versão do Vikunja for lançada, você só precisa executar dois comandos:

sudo docker compose pull
sudo docker compose up -d

O Docker baixará a nova imagem e recriará o contêiner com ela, mantendo seus dados persistentes nos volumes mapeados. Isso minimiza drasticamente o tempo de inatividade.

Para backups, recomendamos criar uma rotina via cron para compactar os diretórios de dados. No caso do Vikunja, os arquivos enviados ficam em /opt/vikunja/files e o banco de dados pode ser backupado via comandos SQL dump ou volume snapshot. Um script simples de backup poderia ser:

sudo docker exec vikunja_db_1 pg_dump -U vikunja vikunja > /backup/vikunja-db-$(date +%F).sql
tar czvf /backup/vikunja-files-$(date +%F).tar.gz /opt/vikunja/files

Conclusão e Próximos Passos

Você acabou de concluir a instalação de uma ferramenta completa de gerenciamento de projetos em sua própria infraestrutura. O Vikunja self-hosted oferece flexibilidade total, sem taxas por usuário e com controle absoluto sobre seus dados. Ao utilizar Docker e Nginx, você adotou práticas modernas de DevOps, facilitando a manutenção e a escalabilidade.

Explore as funcionalidades avançadas do Vikunja, como integrações via API, notificações por email e sincronização com clientes de desktop e mobile. Para equipes que buscam uma kanban alternativa ao Kanboard ou Trello, sem comprometer a privacidade, o Vikunja é uma escolha sólida e madura no ecossistema de ferramentas open source para devops.

Lembre-se sempre de monitorar os logs do sistema e manter suas atualizações em dia. Com este setup, você tem uma base robusta para gerenciar seus projetos com eficiência e segurança.