Alojar Vikunja num VPS gerido: as suas tarefas e projetos no seu servidor

Alojar Vikunja num VPS gerido é guardar as tarefas e os projetos da sua equipa numa máquina sua, que as nossas equipas mantêm atualizada e supervisionam dia e noite. O Vikunja é um software livre sob licença AGPL-3.0. Este guia segue a sua documentação oficial: a escolha da base de dados, a instalação com o Docker Compose, o URL público e o segredo, as contas, o HTTPS, as definições próprias do Vikunja, o e-mail, as cópias de segurança e as atualizações.

Simon Vasconcelos Lee Por Publicado a 19 de novembro de 2026Leitura: 13 minutos

Todos os guias

O essencial

  1. A licença AGPL-3.0 permite utilizar o Vikunja numa empresa sem licença para comprar; se o modificar, os seus utilizadores à distância devem poder obter o código-fonte da sua versão.
  2. Instale-o com o Docker Compose: a imagem vikunja/vikunja:2.8.0 e o PostgreSQL, com a porta 3456 publicada em 127.0.0.1 atrás de um proxy inverso em HTTPS.
  3. Duas definições devem estar no lugar desde o início: service.publicurl, o endereço HTTPS da sua instância, e service.secret, que assina as sessões.
  4. O Vikunja não tem nenhuma conta predefinida: crie a sua, feche depois o registo e acrescente as contas seguintes pela linha de comandos.
  5. Faça a cópia da base de dados e da pasta files em conjunto, antes de cada atualização; as migrações da base de dados correm sozinhas no arranque.

O que faz o Vikunja

O Vikunja é um gestor de tarefas e de projetos de código aberto e autoalojado, que o seu repositório apresenta como «o gestor de tarefas que é verdadeiramente seu». A API, escrita em Go, e a interface web vêm num único binário, ou numa única imagem Docker: há apenas uma coisa a instalar.

O que permite a licença AGPL-3.0

O Vikunja é publicado sob a GNU AGPL versão 3 ou posterior, exceto a pasta desktop/ do seu repositório, a aplicação de computador, que está sob a GPL versão 3 ou posterior. Pode utilizá-lo, incluindo numa empresa, para a sua equipa como para os seus clientes, sem licença para comprar. Resta o custo do servidor que o faz funcionar.

A secção 13 acrescenta uma condição própria da AGPL: se modificar o programa, a sua versão deve oferecer de forma visível a todas as pessoas que interagem com ela à distância, através de uma rede, a possibilidade de obter o seu código-fonte, gratuitamente. Se distribuir cópias, aplicam-se também as obrigações da licença sobre a partilha do código-fonte. Utilizar o Vikunja sem o modificar não ativa esta secção.

Este guia instala essa edição de código aberto, que a documentação apresenta como plenamente funcional por si só. O Vikunja Pro, uma licença opcional, acrescenta para as organizações um painel de administração, o registo do tempo despendido e registos de auditoria.

Os recursos e a base de dados

O Vikunja funciona com SQLite, PostgreSQL, MySQL ou MariaDB. A documentação não dá nenhum valor de memória nem de processador; orienta a escolha da base de dados pelo número de utilizadores:

Base de dadosO que diz a documentaçãoVersão testada na integração contínua
SQLiteIncluída no binário e na imagem Docker, nada a instalar. Para além de alguns utilizadores, a documentação recomenda o MySQL ou o PostgreSQL.A incluída
PostgreSQLA base de dados dos exemplos Docker da documentação. Desde a 2.8.0, a pesquisa ignora os acentos com a extensão unaccent.18
MySQL, MariaDBMySQL 8.0 no mínimo, uma vez que a 5.7 não é suportada. Para os carateres não latinos, a base de dados deve utilizar utf8mb4.MySQL 8, MariaDB 12

A documentação recomenda uma versão da base de dados que continue a ter manutenção. O Redis pode servir de cache, mas a documentação nota que provavelmente não precisará dele enquanto a instância tiver apenas alguns utilizadores: este guia dispensa-o.

O espaço em disco depende sobretudo dos seus anexos e dos fundos de projeto, guardados na pasta files, com 20 MB por ficheiro no máximo por predefinição. Num VPS gerido, fale-nos da sua equipa, do seu número de utilizadores e do uso que faz dos anexos, e recomendamos-lhe a dimensão adequada.

A instalação com o Docker Compose

A documentação instala o Vikunja e o PostgreSQL com o Docker Compose. Num servidor com o Docker instalado, crie uma pasta e gere primeiro o segredo da instância, um valor aleatório que vai colar no ficheiro:

Terminal
openssl rand -hex 32

Coloque depois na pasta este docker-compose.yml, retirado do exemplo PostgreSQL da documentação. Substitua tasks.example.com pelo seu nome de domínio, paste-your-secret-here pelo valor gerado e changeme por uma palavra-passe robusta, a mesma nos dois sítios:

docker-compose.yml
services:
  vikunja:
    image: vikunja/vikunja:2.8.0
    environment:
      VIKUNJA_SERVICE_PUBLICURL: https://tasks.example.com/
      VIKUNJA_SERVICE_SECRET: paste-your-secret-here
      VIKUNJA_SERVICE_IPEXTRACTIONMETHOD: xff
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_PASSWORD: changeme
      VIKUNJA_DATABASE_DATABASE: vikunja
    ports:
      - "127.0.0.1:3456:3456"
    volumes:
      - ./files:/app/vikunja/files
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
  db:
    image: postgres:18
    environment:
      POSTGRES_USER: vikunja
      POSTGRES_PASSWORD: changeme
    volumes:
      - ./db:/var/lib/postgresql
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h localhost -U $$POSTGRES_USER"]
      interval: 30s
      start_period: 15s
      start_interval: 5s

O Vikunja corre com o utilizador 1000: crie a pasta files e entregue-lha antes do primeiro arranque, como pede a documentação, e arranque depois os serviços:

Terminal, na pasta do docker-compose.yml
mkdir files
sudo chown 1000 files
docker compose up -d
docker compose logs vikunja

No primeiro arranque, o Vikunja cria a sua base de dados e executa todas as suas migrações. A linha http server started on [::]:3456 nos registos indica que está pronto, e curl http://127.0.0.1:3456/api/v1/info, executado no servidor, devolve a sua versão e as suas definições públicas.

Com o SQLite

Para alguns utilizadores, a documentação propõe o SQLite: retire o serviço db, o bloco depends_on e as variáveis VIKUNJA_DATABASE_*, e monte uma pasta em /db, onde a imagem já guarda vikunja.db. Crie-a e entregue-a ao utilizador 1000, como files:

docker-compose.yml, serviço vikunja
    volumes:
      - ./files:/app/vikunja/files
      - ./db:/db

Sem Docker: o pacote Debian

Desde a versão 2.4.0, o Vikunja publica um repositório de pacotes para Debian e Ubuntu, para amd64, arm64 e armhf, assinado com a sua chave GPG:

Terminal
curl -fsSL https://dl.vikunja.io/repos/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/vikunja.gpg
echo "deb [signed-by=/usr/share/keyrings/vikunja.gpg] https://dl.vikunja.io/repos/apt stable main" | sudo tee /etc/apt/sources.list.d/vikunja.list
sudo apt update && sudo apt install vikunja

O pacote instala o Vikunja em /opt/vikunja, com o SQLite por predefinição, e um serviço systemd ativado mas ainda não arrancado. Escreve também um segredo aleatório numa secção service de /etc/vikunja/config.yml: complete essa mesma secção e arranque depois o serviço.

/etc/vikunja/config.yml
service:
  secret: "the value written by the package"
  publicurl: "https://tasks.example.com/"
  interface: "127.0.0.1:3456"
  ipextractionmethod: "xff"
Terminal
sudo systemctl start vikunja

A primeira conta e o registo

O Vikunja não cria nenhuma conta por predefinição. Com o HTTPS instalado, abra https://tasks.example.com/ e registe-se: é a sua primeira conta. O registo está aberto por predefinição a qualquer pessoa que chegue ao endereço; quando as contas da sua equipa existirem, a documentação sugere fechá-lo. Acrescente esta linha às variáveis do serviço vikunja e volte a executar docker compose up -d:

docker-compose.yml, em environment
      VIKUNJA_SERVICE_ENABLEREGISTRATION: "false"

As contas seguintes gerem-se pela linha de comandos. Como a imagem não tem shell, chama-se diretamente o seu binário:

Terminal, na pasta do docker-compose.yml
docker compose exec vikunja /app/vikunja/vikunja user create -u marie -e marie@example.com
docker compose exec vikunja /app/vikunja/vikunja user list
docker compose exec vikunja /app/vikunja/vikunja user reset-password 2 --direct

A segurança das contas

HTTPS: o proxy inverso

O Vikunja serve HTTP sem cifra. A documentação termina o HTTPS num proxy inverso, para que as palavras-passe e os tokens nunca circulem sem cifra: escuta nas portas 80 e 443, obtém o certificado e transmite ao Vikunja em 127.0.0.1:3456.

Atrás de um proxy, o Vikunja vê por predefinição o endereço do proxy em cada pedido: os registos e os limites de frequência visam então toda a gente ao mesmo tempo. A definição VIKUNJA_SERVICE_IPEXTRACTIONMETHOD: xff, já presente no ficheiro Compose, fá-lo ler o cabeçalho X-Forwarded-For. Só confia nesse cabeçalho nos pedidos que chegam dos endereços de loopback e de rede privada, incluindo a rede do Docker: com a porta publicada em 127.0.0.1, só o seu proxy lá chega.

Com o Caddy

Eis o Caddyfile da documentação. O Caddy obtém sozinho um certificado Let’s Encrypt para o nome indicado, transmite o cabeçalho X-Forwarded-For e deixa passar as ligações WebSocket:

Caddyfile
tasks.example.com {
    reverse_proxy 127.0.0.1:3456
}

Com o Nginx

O bloco da documentação resume-se a uma linha proxy_pass e a um tamanho de envio. Este bloco parte dele e acrescenta duas coisas: o cabeçalho X-Forwarded-For, que o Vikunja lê, e os cabeçalhos WebSocket. A interface da versão 2.8.0 abre uma ligação WebSocket em /api/v2/ws para as suas atualizações em tempo real; se esta falhar, as suas notificações passam a ser consultadas a cada 10 segundos. Acrescente primeiro este bloco map à secção http de /etc/nginx/nginx.conf:

nginx.conf, dentro de http
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Depois, este bloco de site, na porta 80 para que o Certbot possa instalar o HTTPS:

Bloco Nginx
server {
    listen 80;
    listen [::]:80;
    server_name tasks.example.com;

    location / {
        proxy_pass http://127.0.0.1:3456;
        client_max_body_size 20M;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}
Terminal
sudo nginx -t
sudo certbot --nginx

client_max_body_size 20M corresponde ao tamanho máximo de ficheiro no Vikunja, 20 MB por predefinição. Se o aumentar com VIKUNJA_FILES_MAXSIZE, a documentação pede que aumente também esta linha.

As definições próprias do Vikunja

Quase todas as chaves do ficheiro config.yml têm a sua variável de ambiente: service.enablecaldav passa a VIKUNJA_SERVICE_ENABLECALDAV. Quando uma opção está definida nos dois sítios, prevalece a variável. A lista de reforço da segurança da documentação passa em revista as funções a desativar se não lhes der uso:

ChavePredefiniçãoDesativá-la para
service.enablelinksharingtrueImpedir a partilha de projetos através de links públicos
service.enablecaldavtrueRetirar o ponto de acesso CalDAV, que aceita a autenticação HTTP básica
webhooks.enabledtrueImpedir o Vikunja de enviar pedidos para endereços escolhidos pelos utilizadores
service.enabletaskattachmentstrueImpedir o envio de ficheiros para as tarefas
service.enableuserdeletiontrueImpedir os utilizadores de eliminarem a sua própria conta
plugins.enabledfalseJá desativada: manter o código de terceiros fora do Vikunja

A pesquisa sem acentos no PostgreSQL

Desde a 2.8.0, a pesquisa ignora os acentos no PostgreSQL quando a extensão unaccent está ativa: «cafe» encontra também «café». A imagem oficial do PostgreSQL inclui-a; ative-a na base de dados do Vikunja e reinicie depois o Vikunja. O registo mostra então unaccent extension detected, search is accent-insensitive.

Terminal, na pasta do docker-compose.yml
docker compose exec db psql -U vikunja -d vikunja -c 'CREATE EXTENSION IF NOT EXISTS unaccent;'
docker compose restart vikunja

Importar as suas tarefas

Cada utilizador importa as suas tarefas a partir do separador «Import» das suas definições, onde pode também exportar todos os seus dados num arquivo zip. As importações de ficheiros, arquivo Vikunja, CSV, TickTick e WeKan, tal como a importação a partir de uma instância Planka, estão sempre disponíveis. O Todoist, o Trello e o Microsoft To Do passam pelo OAuth: estão desativados por predefinição e ativam-se na secção migration da configuração, com as credenciais da aplicação criada em cada serviço. O redirecionamento OAuth acontece no navegador: a instância não precisa de estar acessível a esses serviços, mas service.publicurl tem de estar correto.

CalDAV

O CalDAV sincroniza as tarefas com as suas aplicações, com os dados de ligação do separador CalDAV das definições. A documentação apresenta esta integração como uma versão alfa que funciona bem com alguns clientes: experimente o seu antes de fazer dele a ferramenta de toda a equipa. No iPhone e no iPad, cada projeto passa a ser uma lista na aplicação Lembretes. Uma conta com autenticação de dois fatores liga-se com um token CalDAV dedicado.

O e-mail: lembretes, confirmações e palavras-passe

O Vikunja envia e-mails para os lembretes de tarefas, a confirmação de uma conta nova e a reposição de palavras-passe. O envio está desativado por predefinição: as contas ficam então ativas assim que são criadas, e a reposição da palavra-passe por e-mail não é possível. Com o envio ativado, cada nova conta local confirma o seu endereço antes de ser utilizada.

A partir de um VPS Simafri, configure um servidor SMTP autenticado, na porta 587 ou 465: o do seu serviço de envio ou do seu fornecedor de e-mail. Acrescente estas variáveis ao serviço vikunja:

docker-compose.yml, em environment
      VIKUNJA_MAILER_ENABLED: "true"
      VIKUNJA_MAILER_HOST: smtp.example.com
      VIKUNJA_MAILER_PORT: 587
      VIKUNJA_MAILER_USERNAME: tasks@example.com
      VIKUNJA_MAILER_PASSWORD: your-smtp-password
      VIKUNJA_MAILER_FROMEMAIL: tasks@example.com

Volte a executar docker compose up -d e envie depois uma mensagem de teste. O comando verifica a ligação com um comando SMTP NOOP, que alguns relays mínimos não suportam: prefira um servidor SMTP completo.

Terminal
docker compose exec vikunja /app/vikunja/vikunja testmail you@example.com

As cópias de segurança

A documentação conta duas partes a copiar, em conjunto: a base de dados e a pasta dos anexos. Desde a 2.8.0, as tarefas e os projetos eliminados passam primeiro 30 dias no caixote do lixo; passado esse prazo ou esvaziado o caixote do lixo, só uma cópia de segurança os recupera.

ElementoO que guardaComo copiá-lo
A base de dados PostgreSQLAs contas, os projetos, as tarefas, os comentários e as definiçõespg_dump, sem parar o Vikunja
filesOs anexos, os avatares e os fundos de projetoUma cópia da pasta
Com o SQLite, db/vikunja.dbToda a base de dadosUma cópia do ficheiro, com o Vikunja parado
docker-compose.ymlO segredo, o URL público e as palavras-passeGuardado à parte, como um segredo
Terminal, na pasta do docker-compose.yml
docker compose exec -T db pg_dump -U vikunja vikunja > vikunja-$(date +%F).sql
tar -czf vikunja-files-$(date +%F).tar.gz files

A documentação pede cópias cifradas e guardadas fora do servidor, e restauros testados com regularidade: numa instância à parte, inicie sessão e abra uma tarefa com um anexo. Colocados no disco do servidor, estes arquivos entram também nas suas cópias de segurança noturnas.

O comando vikunja dump reúne a configuração, a base de dados e todos os ficheiros num arquivo zip, e vikunja restore volta a carregá-lo. O arquivo contém o ficheiro de configuração e todas as variáveis VIKUNJA_* em claro: cifre-o e proteja-o como a própria base de dados.

Restaurar

Numa instalação nova, com o mesmo docker-compose.yml, carregue a exportação na base de dados ainda vazia antes do primeiro arranque do Vikunja e volte a colocar depois a pasta files:

Terminal
docker compose up -d db
docker compose exec -T db psql -U vikunja vikunja < vikunja-2026-11-19.sql
tar -xzf vikunja-files-2026-11-19.tar.gz
docker compose up -d

As atualizações

O Vikunja executa sozinho as migrações da sua base de dados quando uma nova versão arranca. Por isso a documentação pede uma cópia de segurança antes de cada atualização, para poder voltar ao estado anterior, e a leitura das notas da versão, que assinalam eventuais passos manuais.

  1. Leia as notas da nova versão.
  2. Exporte a base de dados e copie a pasta files.
  3. Mude a etiqueta da imagem em docker-compose.yml, por exemplo de 2.8.0 para a versão seguinte.
  4. Descarregue a nova imagem e reinicie o serviço.
Terminal
docker compose pull
docker compose up -d

Com o pacote Debian, sudo apt update && sudo apt upgrade substitui o binário e reinicia o serviço. Passar de uma versão estável para as compilações unstable funciona, mas a documentação desaconselha o regresso: espere antes pela versão estável seguinte.

As correções de segurança são publicadas como avisos de segurança do GitHub e anunciadas nas notas da versão. A versão 2.8.0 de 5 de novembro de 2026 corrige dezanove, e o seu anúncio pede que atualize assim que puder. Para ser avisado, siga as versões do repositório GitHub ou o feed RSS do registo de alterações.

Quem faz o quê num VPS gerido

O autoalojamento exige cuidar do servidor para além da aplicação. Num VPS gerido, as nossas equipas assumem o servidor e acompanham a sua instância de forma proativa; o Vikunja continua a ser o seu software, com as suas definições, os seus projetos e as suas tarefas.

AssuntoAs nossas equipasVocê
O servidorAtualizações do sistema e de segurança, intervenções no servidor incluídasO momento que convém à sua atividade
A supervisãoServidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar pela sua chamadaA leitura dos registos da sua instância
VikunjaAcompanhamento proativo: erros, lentidão e espaço em disco identificados, correção recomendadaA sua instalação, as suas atualizações e as suas definições, que aplica diretamente ou com o seu assistente de IA
As contas e os projetosO servidor que os suporta, vigiado e com cópias de segurançaAs contas da sua equipa, o registo, as partilhas e as permissões
O e-mailUm servidor que chega ao seu servidor SMTP na porta 587 ou 465O seu serviço de envio e as respetivas credenciais
As cópias de segurançaTodas as noites, cifradas e guardadas fora da máquina; restauro incluídoAs suas exportações da base de dados e da pasta files, e o pedido de restauro, quando precisar
A migraçãoO seu servidor atual migrado, oferecidoO momento da mudança

Se preferir que as nossas equipas intervenham na própria aplicação, este serviço é faturado à hora ou por pacote, com um orçamento comunicado antes da intervenção.

O Vikunja, num servidor mantido por si

Com um VPS gerido da Simafri, as nossas equipas mantêm atualizado o servidor da sua instância Vikunja, vigiam-no dia e noite e intervêm sem esperar pela sua chamada; acompanham também a sua instância de forma proativa e recomendam-lhe as correções úteis, que aplica diretamente ou com o seu assistente de IA. As cópias de segurança são cifradas todas as noites e guardadas fora da máquina, o seu restauro está incluído, e a migração do seu servidor atual é oferecida.

Descobrir os VPS geridos

Perguntas frequentes

O Vikunja é gratuito para uma empresa?

Sim. O Vikunja está sob licença AGPL-3.0: pode utilizá-lo numa empresa sem licença para comprar. Se o modificar, os seus utilizadores à distância devem poder obter o código-fonte da sua versão. Resta o custo do servidor que o faz funcionar.

Que base de dados escolher para o Vikunja?

O SQLite, incluído na imagem, chega para alguns utilizadores. Para além disso, a documentação recomenda o PostgreSQL ou o MySQL. O PostgreSQL é a base de dados dos seus exemplos Docker, e desde a 2.8.0 a sua pesquisa ignora os acentos com a extensão unaccent.

Como instalar o Vikunja com o Docker Compose?

Crie um docker-compose.yml com as imagens vikunja/vikunja:2.8.0 e postgres:18, a porta 3456 publicada em 127.0.0.1, uma pasta files entregue ao utilizador 1000, o URL público e o segredo, e execute docker compose up -d. Coloque depois à frente da porta 3456 um proxy inverso em HTTPS.

Para que servem service.publicurl e service.secret?

service.publicurl é o endereço HTTPS da sua instância: o Vikunja constrói a partir dele as suas ligações e a sua origem CORS, daí um erro unauthorized quando está errado. service.secret assina as sessões; deixado vazio, muda em cada arranque e termina a sessão de todos os utilizadores.

Como criar a primeira conta do Vikunja?

O Vikunja não tem nenhuma conta predefinida: registe-se na sua instância. Feche depois o registo pondo VIKUNJA_SERVICE_ENABLEREGISTRATION a false, e crie as contas seguintes com o comando vikunja user create, executado dentro do contentor.

Como configurar o e-mail no Vikunja?

Ative o envio com VIKUNJA_MAILER_ENABLED e indique depois o anfitrião, a porta 587 ou 465, o utilizador, a palavra-passe e o endereço do remetente do seu servidor SMTP. Sem e-mail, as contas ficam ativas assim que são criadas e as palavras-passe repõem-se pela linha de comandos.

Como fazer a cópia de segurança do Vikunja?

Copie em conjunto a base de dados, com pg_dump para o PostgreSQL, e a pasta files dos anexos. Guarde as cópias cifradas e fora do servidor, faça uma antes de cada atualização e teste o seu restauro com regularidade.

Um VPS gerido cobre o Vikunja?

Um VPS gerido cobre o servidor: sistema, segurança, supervisão e cópias de segurança. As nossas equipas acompanham também a sua instância de forma proativa e recomendam-lhe as correções úteis, que aplica. Uma intervenção na aplicação é faturada à hora ou por pacote.

Fontes e documentação oficial

Contacte-nos