Base de Conhecimento

Kimai na VPS: controle de horas no seu servidor

  • kimai, controle de horas, docker, docker compose, caddy, vps
  • Usuários acharam útil: 0

Aprenda a instalar o Kimai na sua VPS com Docker Compose: requisitos, variáveis essenciais, HTTPS com Caddy, primeiro administrador, backup e atualização.

Por Redação Eleven Host · @robson.direitodigital · 4 de novembro de 2026 · 10 min de leitura

Arte da Eleven Host: janela de terminal com o título: Kimai na VPS: controle de horas no seu servidor

Capa da Redação Eleven Host para o guia: Kimai na VPS: controle de horas no seu servidor Arte: Eleven Host

Kimai na VPS: o Kimai é uma aplicação profissional de controle de horas, gratuita e de código aberto. Veja requisitos, instalação com Docker Compose, HTTPS, primeiro administrador, backup e atualização.

Este passo a passo segue a documentação oficial do Kimai. Em 04/11/2026, a versão mais recente no GitHub é a 2.71.0, publicada em 25/10/2026. Se você está começando com servidores, o guia O que é servidor VPS explica o básico da máquina onde o Kimai vai ficar.

O que é o Kimai

O Kimai é uma aplicação web multiusuário de controle de horas, que pode ser instalada no seu servidor (on-premise) ou usada como serviço hospedado. Segundo o README do projeto, ele reúne API JSON, faturas, exportação de dados, relatórios, orçamentos, permissões por papel e equipe e autenticação em dois fatores. O layout é responsivo.

Licença: o Kimai é publicado sob a licença AGPL-3.0 (o arquivo composer.json indica AGPL-3.0-or-later). Os plugins pagos têm licença própria.

Kimai Cloud, plugins e app: o que é pago

Antes de instalar, vale separar o que é gratuito do que é cobrado. A documentação chama o Kimai Cloud de versão hospedada e paga do Kimai. Aqui o assunto é a instalação na sua própria VPS.

Os plugins são vendidos como assinatura, com licença perpétua de reserva: segundo a documentação, as assinaturas ativas incluem atualizações enquanto durarem. Pela loja de plugins do Kimai, em 04/11/2026, são pagos itens como trilha de auditoria, campos personalizados, controle de despesas, modo quiosque, planejamento de tarefas, controle de jornada, férias e feriados. São gratuitos, entre outros, o fluxo de aprovação de planilhas de horas, o portal do cliente, o Easy Backup e o importador de CSV e JSON.

Alguns recursos que aparecem na página de funcionalidades, como despesas, dependem de plugin pago. Já o aplicativo nativo Kimai Mobile é vendido à parte pela empresa Cloudrizon GmbH. O acesso pelo navegador do celular, pela tela inicial, não exige esse aplicativo.

Requisitos do Kimai

A documentação avisa que a instalação própria exige conhecimento técnico e que erros podem causar perda de dados, problemas de segurança e indisponibilidade. Para quem não tem experiência, ela indica a versão em nuvem. O que o Kimai pede:

  • um banco MariaDB ou MySQL (o Compose da documentação usa o mysql:8.3);
  • um subdomínio próprio para o Kimai: a documentação diz que subdiretório não é suportado;
  • nos guias da documentação para Hetzner Cloud e DigitalOcean, o plano de entrada (o tipo CPX11 na Hetzner e um plano básico de CPU compartilhada na DigitalOcean) é considerado suficiente para a maior parte dos níveis de uso;
  • PHP 8.2 ou mais novo, caso você instale por SSH, sem Docker. Com Docker, o PHP vem na imagem.

A instalação por FTP não é suportada. Neste guia usamos uma VPS com Linux, Docker e Docker Compose já instalados. Confira a sua versão com:

docker compose version

Qual tamanho de servidor combina com a sua equipe? VPS a partir de R$ 29,90/mês no Plano Bronze; confira na loja o que cada plano inclui. Ver as VPS

Qual imagem Docker usar

A imagem do Kimai é a kimai/kimai2, no Docker Hub. A documentação recomenda fixar uma versão principal, com a tag kimai/kimai2:2 como exemplo. A tag stable aponta para a última versão estável e, segundo a documentação, pode saltar para uma nova versão principal, então é preciso cuidado. O bloco de instalação da documentação usa stable; neste guia trocamos por :2 para que a atualização não mude de versão principal sem você perceber.

A documentação marca como depreciadas, sem novas atualizações, tags antigas como apache e apache-latest; evite essas duas.

Instalar com Docker Compose

Crie uma pasta para o Kimai e, dentro dela, o arquivo docker-compose.yml. O conteúdo abaixo é o Compose da documentação, com a imagem trocada por kimai/kimai2:2. Mantenha a indentação de dois espaços por nível, porque o YAML depende dela. O domínio kimai.example.com é fictício:

services:

sqldb:

image: mysql:8.3

volumes:

- mysql:/var/lib/mysql

environment:

- MYSQL_DATABASE=kimai

- MYSQL_USER=kimaiuser

- MYSQL_PASSWORD=kimaipassword

- MYSQL_ROOT_PASSWORD=changemeplease

command: --default-storage-engine innodb

restart: unless-stopped

healthcheck:

test: mysqladmin -uroot -p$$MYSQL_ROOT_PASSWORD ping -h 127.0.0.1 --silent

interval: 10s

timeout: 5s

retries: 12

start_period: 30s

kimai:

image: kimai/kimai2:2

depends_on:

sqldb:

condition: service_healthy

restart: true

volumes:

- data:/opt/kimai/var/data

- plugins:/opt/kimai/var/plugins

ports:

- 8001:8001

environment:

- APP_SECRET=

- "TRUSTED_HOSTS=^kimai\.example\.com$"

- ADMINMAIL=admin@example.com

- ADMINPASS=changemeplease

- "DATABASE_URL=mysql://kimaiuser:kimaipassword@sqldb/kimai?charset=utf8mb4&serverVersion=8.3.0"

restart: unless-stopped

volumes:

data:

mysql:

plugins:

A documentação é clara sobre as senhas: por segurança, use valores únicos nas variáveis de ambiente. Antes de subir, troque o domínio e o e-mail de exemplo pelos seus, troque todas as senhas de exemplo (kimaipassword e changemeplease) e preencha o APP_SECRET, que no Compose da documentação vem vazio. A documentação mostra ainda uma alternativa com um arquivo .env, que o Compose referencia com a sintaxe ${NOME}.

Com o arquivo pronto, suba os contêineres:

docker compose up -d

A documentação também avisa que a configuração de teste dela não serve para produção, e o Docker Hub avisa que os dados somem ao remover os contêineres. O Compose acima declara os volumes data, mysql e plugins.

Variáveis essenciais

  • APP_SECRET: a documentação exige que você defina uma string longa e única. Um exemplo de comando para gerar uma: openssl rand -hex 32;
  • TRUSTED_HOSTS: também obrigatória, com o domínio usado para acessar o Kimai. O exemplo da documentação é uma expressão regular, ^kimai\.example\.com$, com o ponto escapado;
  • DATABASE_URL: se a senha do banco tiver caractere especial, ela precisa de URL-encoding, e o serverVersion deve bater com a versão do banco (no exemplo, 8.3.0). Para codificar a senha, a documentação traz este comando:

php -r "echo urlencode('mG0/d1@3aT.Z)s');echo PHP_EOL;"

  • ADMINMAIL e ADMINPASS: e-mail e senha do administrador, criado se ainda não existir;
  • TRUSTED_PROXIES: padrão 127.0.0.1; veja a próxima seção.

HTTPS e proxy reverso

O caminho que a documentação mostra para uma VPS com HTTPS usa o Caddy com Docker Compose, nos guias para Hetzner e DigitalOcean. O domínio precisa apontar para o IP do servidor, e as portas 80 (tráfego sem criptografia) e 443 (tráfego seguro) precisam estar liberadas. O certificado é gerado depois do apontamento, e pode demorar após uma mudança de DNS. Esse é um caminho à parte do Compose acima, com repositório próprio: se for usá-lo, rode antes docker compose down na pasta do Kimai anterior, para não disputar a porta 8001. Os comandos do guia são estes:

git clone https://github.com/kimai/kimai-docker-caddy.git

cd kimai-docker-caddy

docker volume create caddy_data

docker volume create kimai_data

docker volume create kimai_plugins

docker volume create mysql_data

ufw allow 80

ufw allow 443

nano .env

nano docker-compose.yml

nano caddy_config/Caddyfile

docker compose up -d

O Caddyfile do guia:

kimai.<domain>.<suffix> {

reverse_proxy kimai:8001 {

flush_interval -1

}

}

Recomendamos conferir, no docker-compose.yml desse repositório, se APP_SECRET e TRUSTED_HOSTS estão definidos com os seus valores e se a tag da imagem é uma das indicadas acima, antes de rodar o docker compose up -d. Mantenha também o acesso por SSH liberado no ufw.

Quando o Kimai fica atrás de um proxy, a documentação manda enviar os cabeçalhos necessários X-Forwarded-* e definir a variável TRUSTED_PROXIES. Ela aceita endereços IP, sub-redes CIDR e as palavras-chave do Symfony REMOTE_ADDR e PRIVATE_SUBNETS, mas não aceita nomes de host, como localhost ou nginx. O exemplo da documentação é:

TRUSTED_PROXIES=127.0.0.1,PRIVATE_SUBNETS

Sem confiar no proxy, o Kimai pode gerar redirecionamentos para http. Se o proxy roda num contêiner Nginx, a documentação manda incluir o IP do contêiner em TRUSTED_PROXIES. Quem prefere uma interface gráfica para publicar vários sites na mesma VPS pode ver o guia Nginx Proxy Manager.

Primeiro usuário administrador

No Compose acima, as variáveis ADMINMAIL e ADMINPASS criam o administrador. A documentação lista três caminhos: o comando de console, o cadastro na tela de login (o primeiro usuário vira ROLE_SUPER_ADMIN) ou LDAP e SAML. O comando de console, com o nome de contêiner kimai-test do exemplo dela, é:

docker exec -ti kimai-test \

/opt/kimai/bin/console kimai:user:create admin admin@example.com ROLE_SUPER_ADMIN

Troque kimai-test pelo nome do seu contêiner, que você vê com docker ps.

Crie o administrador antes de divulgar o endereço

Recomendamos definir o administrador pelas variáveis do Compose antes de abrir o domínio para outras pessoas. Segundo a documentação, o primeiro usuário cadastrado na tela de login vira ROLE_SUPER_ADMIN. Os avisos de segurança do projeto são publicados no site e no GitHub, com feed Atom.

Atualização

Para uma instalação com Docker Compose, a documentação resume assim: parar, baixar a versão nova e reiniciar. Os comandos são:

docker compose pull

docker compose down

docker compose up -d

A documentação de atualização manda ter um backup funcional do banco antes de começar, e indica ler o guia de atualização (UPGRADING) por causa dos passos manuais de cada versão. Como a imagem do Compose usa a tag :2, o pull baixa a versão mais nova da série 2. A versão 2.71.0, por exemplo, desativou as senhas de API e corrigiu checagens de permissão da API.

Quem instala por SSH, sem Docker, atualiza assim, segundo a documentação:

git checkout -- composer.lock

git fetch --tags

git checkout 2.71.0

composer install --no-dev --optimize-autoloader

bin/console kimai:update

Backup do Kimai

A documentação manda fazer um backup completo do banco de dados do Kimai, sem dividir o banco com outras aplicações, porque as tabelas dependem dos plugins. O comando dela, para uma instalação fora do Docker, é:

mysqldump --single-transaction -u kimai2 -p -h 127.0.0.1 kimai2 > ~/kimai2-`date +%F_%H-%M`.sql

Além do banco, ela lista os arquivos a guardar: .env e .env.local, config/packages/local.yaml e as pastas var/data/, var/export/, var/invoices/, var/packages/ e var/plugins/. Restaurar com uma versão diferente da do backup, sem rodar a atualização do banco, pode dar erro.

Um exemplo de adaptação para o Compose deste guia, que você deve testar numa cópia antes de confiar nele, usando o serviço sqldb e o usuário do exemplo:

docker compose exec -T sqldb sh -c 'exec mysqldump --single-transaction --no-tablespaces -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' > kimai-$(date +%F).sql

Recomendamos guardar também o Compose, o arquivo .env (trate-o como dado sensível) e o conteúdo dos volumes data e plugins, levar tudo para fora da VPS e testar a restauração. Se preferir um plugin, o Easy Backup aparece como gratuito na loja do Kimai.

Outros aplicativos de gestão na mesma VPS

O Kimai cuida do tempo trabalhado. Para faturas e orçamentos, a base de conhecimento tem o guia do Invoice Ninja, e para ERP e CRM da empresa, o do Dolibarr.

Falta escolher o servidor da sua equipe? VPS a partir de R$ 29,90/mês no Plano Bronze; confira na loja o que cada plano inclui. Conhecer as VPS

Perguntas frequentes

O Kimai é gratuito?

O Kimai é publicado sob a licença AGPL-3.0 e é gratuito e de código aberto, segundo o README. Plugins pagos, o Kimai Cloud e o aplicativo nativo Kimai Mobile são cobrados à parte.

Qual versão do Kimai instalar?

Em 04/11/2026, a mais recente no GitHub é a 2.71.0, de 25/10/2026. As versões saem com frequência, então confira a página de releases antes de instalar. A documentação recomenda fixar a versão principal, como na tag kimai/kimai2:2.

O Kimai precisa de um domínio?

A documentação pede um subdomínio próprio para o Kimai, e a variável TRUSTED_HOSTS deve conter o domínio usado no acesso. No guia do Caddy, o domínio também precisa apontar para o IP do servidor para que o certificado seja gerado.

Despesas, férias e jornada de trabalho vêm no Kimai?

Esses recursos são plugins pagos, vendidos como assinatura, e não fazem parte da instalação básica. Pela loja de plugins, em 04/11/2026, o fluxo de aprovação de planilhas e o portal do cliente são gratuitos.

Esta resposta lhe foi útil?

Artigos Relacionados