Hospedar o Vikunja em um VPS gerenciado é guardar as tarefas e os projetos de sua equipe em uma máquina própria, que nossas equipes mantêm atualizada e supervisionam dia e noite. O Vikunja é um software livre sob a licença AGPL-3.0. Este guia segue a documentação oficial dele: a escolha do banco de dados, a instalação com Docker Compose, a URL pública e o segredo, as contas, o HTTPS, as configurações próprias do Vikunja, o e-mail, os backups e as atualizações.
Por Simon Vasconcelos Lee
Publicado em 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 reverso em HTTPS.service.publicurl, o endereço HTTPS de sua instância, e service.secret, que assina as sessões.files juntos, antes de cada atualização; as migrações do banco rodam sozinhas na inicialização.O Vikunja é um gerenciador de tarefas e de projetos de código aberto e auto-hospedado, que o repositório dele apresenta como “o gerenciador de tarefas que é realmente seu”. A API, escrita em Go, e a interface web vêm em um único binário, ou em uma única imagem Docker: há uma só coisa a instalar.
O Vikunja é publicado sob a GNU AGPL versão 3 ou posterior, exceto a pasta desktop/ do repositório dele, o aplicativo de desktop, que está sob a GPL versão 3 ou posterior. Você pode usá-lo, inclusive em uma empresa, para sua equipe e também para seus clientes, sem licença a comprar. Resta o custo do servidor em que ele roda.
A seção 13 acrescenta uma condição própria da AGPL: se você modificar o programa, sua versão deve oferecer de forma destacada a todas as pessoas que interagem com ela remotamente, por uma rede, a possibilidade de obter o código-fonte dela, sem custo. Se você distribuir cópias, as obrigações da licença sobre o compartilhamento do código-fonte também se aplicam. Rodar o Vikunja sem modificá-lo não aciona essa seçã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 registro do tempo gasto e logs de auditoria.
O Vikunja funciona com SQLite, PostgreSQL, MySQL ou MariaDB. A documentação não dá nenhum número de memória nem de CPU; ela orienta a escolha do banco de dados pelo número de usuários:
| Banco de dados | O que diz a documentação | Versão testada na integração contínua |
|---|---|---|
| SQLite | Incluído no binário e na imagem Docker, nada a instalar. Acima de alguns poucos usuários, a documentação recomenda o MySQL ou o PostgreSQL. | O incluído |
| PostgreSQL | O banco dos exemplos Docker da documentação. Desde a 2.8.0, a busca ignora os acentos com a extensão unaccent. | 18 |
| MySQL, MariaDB | MySQL 8.0 no mínimo, já que a 5.7 não é suportada. Para os caracteres não latinos, o banco precisa usar utf8mb4. | MySQL 8, MariaDB 12 |
A documentação recomenda uma versão do banco de dados que ainda tenha manutenção. O Redis pode servir de cache, mas ela observa que você provavelmente não vai precisar dele enquanto a instância tiver apenas alguns poucos usuários: este guia dispensa o Redis.
O espaço em disco acompanha sobretudo seus anexos e os fundos de projeto, guardados na pasta files, com no máximo 20 MB por arquivo por padrão. Em um VPS gerenciado, conte para nós como é sua equipe, o número de usuários e o quanto ela usa anexos, e recomendamos o tamanho certo.
A documentação instala o Vikunja e o PostgreSQL com Docker Compose. Em um servidor com o Docker instalado, crie uma pasta e gere primeiro o segredo da instância, um valor aleatório que você vai colar no arquivo:
openssl rand -hex 32
Coloque então na pasta este docker-compose.yml, tirado do exemplo PostgreSQL da documentação. Substitua tasks.example.com por seu nome de domínio, paste-your-secret-here pelo valor gerado e changeme por uma senha forte, a mesma nos dois lugares:
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 roda com o usuário 1000: crie a pasta files e passe a propriedade dela para esse usuário antes da primeira inicialização, como pede a documentação, e então inicie os serviços:
mkdir files
sudo chown 1000 files
docker compose up -d
docker compose logs vikunja
Na primeira inicialização, o Vikunja cria o banco de dados e executa todas as migrações. A linha http server started on [::]:3456 nos logs indica que ele está pronto, e curl http://127.0.0.1:3456/api/v1/info, executado no servidor, devolve a versão e as configurações públicas dele.
127.0.0.1: é aqui que nos afastamos dos exemplos da documentação, que publicam a porta em todos os endereços. A lista de reforço de segurança dela pede que só o proxy reverso consiga chegar ao Vikunja: a interface então abre por meio dele, em HTTPS.VIKUNJA_SERVICE_PUBLICURL: o endereço HTTPS que seus usuários abrem, com a barra final. O Vikunja o usa para montar os links dele, nos e-mails por exemplo, e como origem CORS autorizada, ativa por padrão: essa configuração é, portanto, obrigatória. Um endereço errado, sem a porta por exemplo, aparece como um erro “unauthorized” na criação da primeira conta.VIKUNJA_SERVICE_SECRET assina os tokens de sessão. Deixado vazio, ele é sorteado a cada inicialização, e cada reinício desconecta então todos os usuários.2.8.0 fixa a versão, como recomenda a documentação, para que as atualizações aconteçam quando você 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 entram no backup.scratch. Um docker exec para um shell não funciona, e as variáveis PUID e PGID de outras imagens não têm efeito nela. Os erros são lidos com docker compose logs vikunja.Para alguns poucos usuários, a documentação propõe o SQLite: remova 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 o vikunja.db. Crie essa pasta e passe a propriedade dela para o usuário 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 chave GPG dele:
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 SQLite por padrão, e um serviço systemd habilitado mas ainda não iniciado. Ele também grava um segredo aleatório em uma seção service do /etc/vikunja/config.yml: complete essa mesma seção e então inicie 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 padrão. Com o HTTPS configurado, abra https://tasks.example.com/ e cadastre-se: essa é sua primeira conta. O cadastro fica aberto por padrão a qualquer pessoa que chegue ao endereço; quando as contas de sua equipe já existirem, a documentação sugere fechá-lo. Adicione esta linha às variáveis do serviço vikunja e execute docker compose up -d de novo:
VIKUNJA_SERVICE_ENABLEREGISTRATION: "false"
As contas seguintes são gerenciadas pela linha de comando. Como a imagem não tem shell, você chama o binário dela diretamente:
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 senha quando a opção -p não a informa, o que a mantém fora do histórico de seu terminal.user reset-password envia por e-mail um link de redefinição, ou substitui a senha diretamente com --direct, a partir do ID que user list mostra.user change-status desativa ou reativa uma conta, com --disable ou --enable.doctor verifica a configuração, a URL pública, o segredo, o banco de dados, o acesso de escrita a files e, quando ativado, o servidor SMTP.VIKUNJA_SERVICE_TIMEZONE vale GMT por padrão e espera um nome da base tz, Europe/Paris por exemplo, nunca um deslocamento UTC. Ele serve de fuso horário padrão dos usuários e define, portanto, o horário dos lembretes deles.O Vikunja serve HTTP sem criptografia. A documentação encerra o HTTPS em um proxy reverso, para que senhas e tokens nunca trafeguem sem criptografia: ele escuta nas portas 80 e 443, obtém o certificado e repassa ao Vikunja em 127.0.0.1:3456.
Atrás de um proxy, o Vikunja vê por padrão o endereço do proxy em cada requisição: os logs e os limites de taxa atingem então todo mundo de uma vez. A configuração VIKUNJA_SERVICE_IPEXTRACTIONMETHOD: xff, já presente no arquivo Compose, faz com que ele leia o cabeçalho X-Forwarded-For. Ele só confia nesse cabeçalho nas requisições que vêm de endereços de loopback e de rede privada, incluindo a rede do Docker: com a porta publicada em 127.0.0.1, só seu proxy chega lá.
Este é o Caddyfile da documentação. O Caddy obtém sozinho um certificado Let’s Encrypt para o nome informado, repassa o cabeçalho X-Forwarded-For e deixa passar as conexões WebSocket:
tasks.example.com {
reverse_proxy 127.0.0.1:3456
}
O bloco da documentação se resume a uma linha proxy_pass e a um tamanho de upload. 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 conexão WebSocket em /api/v2/ws para as atualizações ao vivo; quando ela falha, as notificações passam a ser consultadas a cada 10 segundos. Adicione primeiro este bloco map à seção http do /etc/nginx/nginx.conf:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
Depois, este bloco de servidor, na porta 80 para que o Certbot possa configurar 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 arquivo no Vikunja, 20 MB por padrão. Se você aumentá-lo com VIKUNJA_FILES_MAXSIZE, a documentação pede que aumente também esta linha.
Quase todas as chaves do arquivo config.yml têm sua variável de ambiente: service.enablecaldav vira VIKUNJA_SERVICE_ENABLECALDAV. Quando uma opção é definida nos dois lugares, a variável prevalece. A lista de reforço de segurança da documentação passa em revista as funções a desativar se você não as usa:
| Chave | Padrão | Desativar para |
|---|---|---|
service.enablelinksharing | true | Impedir o compartilhamento de projetos por links públicos |
service.enablecaldav | true | Retirar o endpoint CalDAV, que aceita a autenticação HTTP básica |
webhooks.enabled | true | Impedir que o Vikunja envie requisições para endereços escolhidos pelos usuários |
service.enabletaskattachments | true | Impedir o envio de arquivos para as tarefas |
service.enableuserdeletion | true | Impedir que os usuários excluam a própria conta |
plugins.enabled | false | Já desativado: manter código de terceiros fora do Vikunja |
Desde a 2.8.0, a busca ignora os acentos no PostgreSQL quando a extensão unaccent está ativa: “cafe” também encontra “café”. A imagem oficial do PostgreSQL traz essa extensão; ative-a no banco do Vikunja e depois reinicie o Vikunja. O log 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 usuário importa as tarefas na aba “Import” das configurações dele, onde também pode exportar todos os seus dados em um arquivo zip. As importações de arquivo, arquivo do Vikunja, CSV, TickTick e WeKan, assim como a importação a partir de uma instância Planka, estão sempre disponíveis. Todoist, Trello e Microsoft To Do passam pelo OAuth: eles vêm desativados por padrão e são ativados na seção migration da configuração, com as credenciais do aplicativo criado em cada serviço. O redirecionamento OAuth acontece no navegador: a instância não precisa estar acessível para esses serviços, mas service.publicurl precisa estar correta.
O CalDAV sincroniza as tarefas com seus aplicativos, usando os dados de conexão da aba CalDAV das configurações. A documentação apresenta essa integração como uma versão alfa que funciona bem com alguns clientes: teste seu antes de torná-lo a ferramenta de toda a equipe. No iPhone e no iPad, cada projeto vira uma lista no aplicativo Lembretes. Uma conta com autenticação em dois fatores se conecta com um token CalDAV dedicado.
O Vikunja envia e-mails para os lembretes de tarefas, a confirmação de uma nova conta e a redefinição de senhas. O envio vem desativado por padrão: as contas ficam então ativas assim que são criadas, e a redefinição de senha por e-mail não é possível. Com o envio ativado, cada nova conta local confirma o endereço dela antes do uso.
A partir de um VPS Simafri, configure um servidor SMTP autenticado, na porta 587 ou 465: o de seu serviço de envio ou de seu provedor de e-mail. Adicione 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 conexão e recusa as conexões sem criptografia.plain por padrão, login ou cram-md5 com VIKUNJA_MAILER_AUTHTYPE, conforme seu servidor.Execute docker compose up -d de novo e depois envie uma mensagem de teste. O comando verifica a conexã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 salvar, juntas: o banco de dados e a pasta dos anexos. Desde a 2.8.0, as tarefas e os projetos excluídos passam primeiro 30 dias na lixeira; passado esse prazo ou esvaziada a lixeira, só um backup os traz de volta.
| Item | O que ele guarda | Como copiá-lo |
|---|---|---|
| O banco de dados PostgreSQL | As contas, os projetos, as tarefas, os comentários e as configurações | pg_dump, sem parar o Vikunja |
files | Os anexos, os avatares e os fundos de projeto | Uma cópia da pasta |
Com SQLite, db/vikunja.db | Todo o banco de dados | Uma cópia do arquivo, com o Vikunja parado |
docker-compose.yml | O segredo, a URL pública e as senhas | 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 backups criptografados e guardados fora do servidor, e restaurações testadas regularmente: em uma instância separada, faça login e abra uma tarefa com um anexo. Deixados no disco do servidor, esses arquivos também entram nos backups noturnos dele.
O comando vikunja dump reúne a configuração, o banco de dados e todos os arquivos em um arquivo zip, e vikunja restore o carrega de volta. O arquivo contém o arquivo de configuração e todas as variáveis VIKUNJA_* em texto claro: criptografe-o e proteja-o como o próprio banco de dados.
Em uma instalação nova, com o mesmo docker-compose.yml, carregue a exportação no banco ainda vazio antes da primeira inicialização do Vikunja e depois coloque a pasta files de volta no lugar:
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 do banco de dados quando uma nova versão inicia. Por isso a documentação pede um backup antes de cada atualização, para poder voltar ao estado anterior, e a leitura das notas de versão, que sinalizam eventuais etapas 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 voltar atrás: espere de preferência a próxima versão estável.
As correções de segurança são publicadas como avisos de segurança do GitHub e anunciadas nas notas de versão. A versão 2.8.0, de 5 de novembro de 2026, corrige dezenove delas, e o anúncio pede que você atualize assim que puder. Para ser avisado, acompanhe os releases do repositório no GitHub ou o feed RSS do changelog.
A auto-hospedagem exige cuidar do servidor além da aplicação. Em um VPS gerenciado, nossas equipes assumem o servidor e acompanham sua instância de forma proativa; o Vikunja continua sendo seu software, com as configurações dele, seus projetos e suas tarefas.
| Assunto | Nossas equipes | Você |
|---|---|---|
| O servidor | Atualizações do sistema e de segurança, com intervenções no servidor incluídas | O momento que convém a sua atividade |
| A supervisão | Servidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar sua ligação | A leitura dos logs de sua instância |
| Vikunja | Acompanhamento proativo: erros, lentidões e espaço em disco identificados, correção recomendada | A instalação, as atualizações e as configurações dele, que você aplica, por conta própria ou com seu assistente de IA |
| As contas e os projetos | O servidor que os sustenta, monitorado e com backup | As contas de sua equipe, o cadastro, os compartilhamentos e as permissões |
| O e-mail | Um servidor que chega a seu servidor SMTP na porta 587 ou 465 | Seu serviço de envio e as credenciais dele |
| Os backups | Toda noite, criptografados e guardados fora da máquina; restauração incluída | Suas exportações do banco de dados e da pasta files, e o pedido de restauração, quando você precisar |
| A migração | Seu servidor atual migrado, grátis | O momento da virada |
Se você preferir que nossas equipes intervenham na própria aplicação, esse serviço é cobrado por hora ou por valor fechado, com o orçamento informado antes da intervenção.
Com um VPS gerenciado Simafri, nossas equipes mantêm atualizado o servidor de sua instância Vikunja, monitoram-no dia e noite e intervêm sem esperar sua ligação; elas também acompanham sua instância de forma proativa e recomendam as correções úteis, que você aplica por conta própria ou com seu assistente de IA. Os backups são criptografados todas as noites e guardados fora da máquina, a restauração está incluída, e a migração de seu servidor atual é grátis.
Sim. O Vikunja está sob a licença AGPL-3.0: você pode usá-lo em uma empresa sem licença a comprar. Se você o modificar, seus usuários remotos devem poder obter o código-fonte de sua versão. Resta o custo do servidor em que ele roda.
O SQLite, incluído na imagem, basta para alguns poucos usuários. Acima disso, a documentação recomenda o PostgreSQL ou o MySQL. O PostgreSQL é o banco dos exemplos Docker dela, e desde a 2.8.0 a busca dele 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 usuário 1000, a URL pública e o segredo, e execute docker compose up -d. Coloque então na frente da porta 3456 um proxy reverso em HTTPS.
service.publicurl é o endereço HTTPS de sua instância: o Vikunja monta a partir dele os links e a origem CORS, daí um erro unauthorized quando ele está errado. service.secret assina as sessões; deixado vazio, ele muda a cada inicialização e desconecta todos os usuários.
O Vikunja não tem nenhuma conta padrão: cadastre-se em sua instância. Depois feche o cadastro definindo VIKUNJA_SERVICE_ENABLEREGISTRATION como false, e crie as contas seguintes com o comando vikunja user create, executado dentro do contêiner.
Ative o envio com VIKUNJA_MAILER_ENABLED e informe o host, a porta 587 ou 465, o usuário, a senha e o endereço do remetente de seu servidor SMTP. Sem e-mail, as contas ficam ativas assim que são criadas e as senhas são redefinidas pela linha de comando.
Faça backup do banco de dados, com pg_dump para o PostgreSQL, e da pasta files dos anexos, juntos. Guarde as cópias criptografadas e fora do servidor, faça uma antes de cada atualização e teste a restauração delas regularmente.
Um VPS gerenciado cobre o servidor: sistema, segurança, supervisão e backups. Nossas equipes também acompanham sua instância de forma proativa e recomendam as correções úteis, que você aplica. Uma intervenção na aplicação é cobrada por hora ou por valor fechado.
Simafri
Vamos falar de seu site
Conte para a gente sobre seu projeto em poucas palavras: responderemos rapidamente.
Obrigado! O seu pedido foi enviado. Responderemos em breve.
Prefere o e-mail? Escreva para a gente em support@simafri.com.