Hospedar Vikunja em um VPS gerenciado: suas tarefas e projetos em seu servidor

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.

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

Todos os guias

O essencial

  1. A licença AGPL-3.0 permite usar o Vikunja 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.
  2. Instale-o com 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 reverso em HTTPS.
  3. Duas configurações precisam estar no lugar desde o início: service.publicurl, o endereço HTTPS de sua instância, e service.secret, que assina as sessões.
  4. O Vikunja não tem nenhuma conta padrão: crie a sua, depois feche o cadastro e adicione as contas seguintes pela linha de comando.
  5. Faça backup do banco de dados e da pasta files juntos, antes de cada atualização; as migrações do banco rodam sozinhas na inicialização.

O que o Vikunja faz

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 que a licença AGPL-3.0 permite

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.

Os recursos e o banco de dados

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 dadosO que diz a documentaçãoVersão testada na integração contínua
SQLiteIncluí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
PostgreSQLO banco dos exemplos Docker da documentação. Desde a 2.8.0, a busca ignora os acentos com a extensão unaccent.18
MySQL, MariaDBMySQL 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 instalação com Docker Compose

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:

Terminal
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:

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 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:

Terminal, na pasta do docker-compose.yml
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.

Com o SQLite

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:

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 chave GPG dele:

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 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.

/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 cadastro

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:

docker-compose.yml, em environment
      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:

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 reverso

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á.

Com o Caddy

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:

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

Com o Nginx

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:

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

Depois, este bloco de servidor, na porta 80 para que o Certbot possa configurar o HTTPS:

Bloco do 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 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.

As configurações próprias do Vikunja

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:

ChavePadrãoDesativar para
service.enablelinksharingtrueImpedir o compartilhamento de projetos por links públicos
service.enablecaldavtrueRetirar o endpoint CalDAV, que aceita a autenticação HTTP básica
webhooks.enabledtrueImpedir que o Vikunja envie requisições para endereços escolhidos pelos usuários
service.enabletaskattachmentstrueImpedir o envio de arquivos para as tarefas
service.enableuserdeletiontrueImpedir que os usuários excluam a própria conta
plugins.enabledfalseJá desativado: manter código de terceiros fora do Vikunja

A busca sem acentos no PostgreSQL

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.

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 suas tarefas

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.

CalDAV

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 e-mail: lembretes, confirmações e senhas

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:

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

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.

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

Os backups

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.

ItemO que ele guardaComo copiá-lo
O banco de dados PostgreSQLAs contas, os projetos, as tarefas, os comentários e as configuraçõespg_dump, sem parar o Vikunja
filesOs anexos, os avatares e os fundos de projetoUma cópia da pasta
Com SQLite, db/vikunja.dbTodo o banco de dadosUma cópia do arquivo, com o Vikunja parado
docker-compose.ymlO segredo, a URL pública e as senhasGuardado à 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 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.

Restaurar

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:

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 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.

  1. Leia as notas da nova versão.
  2. Exporte o banco de dados e copie a pasta files.
  3. Mude a tag da imagem no docker-compose.yml, por exemplo de 2.8.0 para a versão seguinte.
  4. Baixe 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 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.

Quem faz o quê em um VPS gerenciado

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.

AssuntoNossas equipesVocê
O servidorAtualizações do sistema e de segurança, com intervenções no servidor incluídasO momento que convém a sua atividade
A supervisãoServidor acompanhado 24 horas por dia, 7 dias por semana, com intervenção sem esperar sua ligaçãoA leitura dos logs de sua instância
VikunjaAcompanhamento proativo: erros, lentidões e espaço em disco identificados, correção recomendadaA 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 projetosO servidor que os sustenta, monitorado e com backupAs contas de sua equipe, o cadastro, os compartilhamentos e as permissões
O e-mailUm servidor que chega a seu servidor SMTP na porta 587 ou 465Seu serviço de envio e as credenciais dele
Os backupsToda noite, criptografados e guardados fora da máquina; restauração incluídaSuas exportações do banco de dados e da pasta files, e o pedido de restauração, quando você precisar
A migraçãoSeu servidor atual migrado, grátisO 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.

Vikunja, em um servidor cuidado por nós

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.

Conhecer os VPS gerenciados

Perguntas frequentes

O Vikunja é gratuito para uma empresa?

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.

Qual banco de dados escolher para o Vikunja?

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.

Como instalar o Vikunja com 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 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.

Para que servem service.publicurl e service.secret?

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.

Como criar a primeira conta do Vikunja?

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.

Como configurar o e-mail no Vikunja?

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.

Como fazer backup do Vikunja?

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 Vikunja?

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.

Fontes e documentação oficial

Entre em contato