Kimai na VPS: controle de horas no seu servidor
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

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 oserverVersiondeve 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;"
ADMINMAILeADMINPASS: e-mail e senha do administrador, criado se ainda não existir;TRUSTED_PROXIES: padrão127.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.