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.
Por Simon Vasconcelos Lee
Publicado a 19 de novembro de 2026Leitura: 13 minutos
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.service.publicurl, o endereço HTTPS da sua instância, e service.secret, que assina as sessões.files em conjunto, antes de cada atualização; as migrações da base de dados correm sozinhas no arranque.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 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.
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 dados | O que diz a documentação | Versão testada na integração contínua |
|---|---|---|
| SQLite | Incluí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 |
| PostgreSQL | A 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, MariaDB | MySQL 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 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:
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:
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:
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.
127.0.0.1: é aqui que nos afastamos dos exemplos da documentação, que publicam a porta em todos os endereços. A sua lista de reforço da segurança pede que só o proxy inverso consiga chegar ao Vikunja: a interface abre-se então através dele, em HTTPS.VIKUNJA_SERVICE_PUBLICURL: o endereço HTTPS que os seus utilizadores abrem, com a barra final. O Vikunja usa-o para construir as suas ligações, nos e-mails por exemplo, e como origem CORS autorizada, ativa por predefinição: esta definição é, por isso, obrigatória. Um endereço errado, sem a porta por exemplo, manifesta-se com um erro «unauthorized» ao criar a primeira conta.VIKUNJA_SERVICE_SECRET assina os tokens de sessão. Deixado vazio, é gerado ao acaso em cada arranque, e cada reinício termina então a sessão de todos os utilizadores.2.8.0 fixa a versão, como recomenda a documentação, para que as atualizações aconteçam quando decidir. latest segue a última versão estável, e unstable as compilações de desenvolvimento.files e db guardam no servidor os anexos e os dados do PostgreSQL: são elas que se copiam.scratch. Um docker exec para uma shell não funciona, e as variáveis PUID e PGID de outras imagens não têm efeito sobre ela. Os erros leem-se com docker compose logs vikunja.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:
volumes:
- ./files:/app/vikunja/files
- ./db:/db
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:
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.
service:
secret: "the value written by the package"
publicurl: "https://tasks.example.com/"
interface: "127.0.0.1:3456"
ipextractionmethod: "xff"
sudo systemctl start vikunja
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:
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:
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
user create pede a palavra-passe quando a opção -p não a indica, o que a mantém fora do histórico do seu terminal.user reset-password envia por e-mail uma ligação de reposição, ou substitui diretamente a palavra-passe com --direct, a partir do identificador que user list mostra.user change-status desativa ou reativa uma conta, com --disable ou --enable.doctor verifica a configuração, o URL público, o segredo, a base de dados, o acesso de escrita a files e, se estiver ativado, o servidor SMTP.VIKUNJA_SERVICE_TIMEZONE vale GMT por predefinição e espera um nome da base tz, Europe/Paris por exemplo, nunca um desvio UTC. Serve de fuso horário predefinido dos utilizadores e fixa, por isso, a hora dos seus lembretes.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.
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:
tasks.example.com {
reverse_proxy 127.0.0.1:3456
}
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:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
Depois, este bloco de site, na porta 80 para que o Certbot possa instalar o HTTPS:
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;
}
}
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.
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:
| Chave | Predefinição | Desativá-la para |
|---|---|---|
service.enablelinksharing | true | Impedir a partilha de projetos através de links públicos |
service.enablecaldav | true | Retirar o ponto de acesso CalDAV, que aceita a autenticação HTTP básica |
webhooks.enabled | true | Impedir o Vikunja de enviar pedidos para endereços escolhidos pelos utilizadores |
service.enabletaskattachments | true | Impedir o envio de ficheiros para as tarefas |
service.enableuserdeletion | true | Impedir os utilizadores de eliminarem a sua própria conta |
plugins.enabled | false | Já desativada: manter o código de terceiros fora do Vikunja |
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.
docker compose exec db psql -U vikunja -d vikunja -c 'CREATE EXTENSION IF NOT EXISTS unaccent;'
docker compose restart vikunja
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.
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 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:
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
VIKUNJA_MAILER_FORCESSL: "true", que impõe o TLS desde o início da ligação e recusa as ligações sem cifra.plain por predefinição, login ou cram-md5 com VIKUNJA_MAILER_AUTHTYPE, consoante o seu servidor.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.
docker compose exec vikunja /app/vikunja/vikunja testmail you@example.com
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.
| Elemento | O que guarda | Como copiá-lo |
|---|---|---|
| A base de dados PostgreSQL | As contas, os projetos, as tarefas, os comentários e as definições | pg_dump, sem parar o Vikunja |
files | Os anexos, os avatares e os fundos de projeto | Uma cópia da pasta |
Com o SQLite, db/vikunja.db | Toda a base de dados | Uma cópia do ficheiro, com o Vikunja parado |
docker-compose.yml | O segredo, o URL público e as palavras-passe | Guardado à parte, como um segredo |
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.
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:
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
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.
files.docker-compose.yml, por exemplo de 2.8.0 para a versão seguinte.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.
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.
| Assunto | As nossas equipas | Você |
|---|---|---|
| O servidor | Atualizações do sistema e de segurança, intervenções no servidor incluídas | O momento que convém à sua atividade |
| A supervisão | Servidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar pela sua chamada | A leitura dos registos da sua instância |
| Vikunja | Acompanhamento proativo: erros, lentidão e espaço em disco identificados, correção recomendada | A 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 projetos | O servidor que os suporta, vigiado e com cópias de segurança | As contas da sua equipa, o registo, as partilhas e as permissões |
| O e-mail | Um servidor que chega ao seu servidor SMTP na porta 587 ou 465 | O seu serviço de envio e as respetivas credenciais |
| As cópias de segurança | Todas as noites, cifradas e guardadas fora da máquina; restauro incluído | As suas exportações da base de dados e da pasta files, e o pedido de restauro, quando precisar |
| A migração | O seu servidor atual migrado, oferecido | O 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.
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.
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.
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.
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.
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.
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.
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.
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 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.
Simafri
Vamos falar do seu projeto
Diga-nos em poucas palavras o que precisa: respondemos-lhe rapidamente.
Obrigado! O seu pedido foi enviado. Responderemos em breve.
Prefere o email? Escreva-nos para support@simafri.com.