Как установить и настроить Kimai на VPS

MAATRIX

Если фрилансеры или команда до сих пор считают часы в экселе или в трекере с урезанным бесплатным тарифом на 3 проекта, рано или поздно это упирается в лимиты — либо по людям, либо по функциям, либо по деньгам за место. Kimai — open-source система учёта времени, которую можно поставить на собственный VPS и не платить за каждого сотрудника отдельно. Ниже — рабочая установка через Docker Compose, с HTTPS и базовой защитой, без танцев с бубном.

Что такое Kimai и когда он вам нужен

Kimai — PHP-приложение (Symfony) для учёта рабочего времени: таймер по проектам и активностям, ставки по клиентам, отчёты, экспорт в PDF/Excel/CSV, многопользовательский доступ с ролями, API, мобильные клиенты и браузерные расширения для быстрого старта таймера. Проект живёт с 2006 года, актуальная линейка — Kimai 2.

Кому это реально полезно:

• Фриланс-командам, которым нужен единый учёт часов по нескольким клиентам с раздельными ставками.
• Агентствам, где нужно считать рентабельность проекта (часы × ставка − расходы).
• Компаниям, которым по каким-то причинам нельзя хранить данные о сотрудниках в облаке (NDA, регуляторика, просто паранойя разумной степени).
• Тем, кто уже устал от Toggl/Clockify с их лимитами на бесплатном тарифе и не хочет платить $8-10 за юзера в месяц, когда своя VPS на пару долларов в день тянет команду из 20+ человек.

Минусы тоже стоит проговорить честно: Kimai — не project management система (для этого лучше смотреть в сторону Taiga или Focalboard), интерфейс местами суховат, а разворачивание своими силами означает, что за апдейты и бэкапы отвечаете вы, а не саппорт SaaS.

Что понадобится

• VPS с 1-2 vCPU и 2 ГБ RAM — для команды до 20-30 человек этого достаточно с запасом. Если у вас разово будут сотни одновременных пользователей — берите 4 ГБ.
• Ubuntu 24.04 LTS (команды ниже под неё, для Debian 12 почти всё то же самое).
• Установленный Docker и Docker Compose — если ещё не разворачивали, есть отдельный разбор установки Docker на Ubuntu 24.04.
• Домен или поддомен, направленный A-записью на IP сервера (для нормального HTTPS).
• Открытые порты 80 и 443.

Ориентировочно вся установка с нуля до рабочего логина занимает 20-30 минут, если домен уже прописан и DNS успел разойтись.

Установка через Docker Compose

Официальный образ — kimai/kimai2:apache, там уже собраны PHP, Apache и всё нужное. Базы данных нужна отдельно — берём MariaDB, она официально поддерживается и легче PostgreSQL по требованиям к ресурсам.

Создаём рабочую директорию и файл docker-compose.yml:

mkdir -p /opt/kimai && cd /opt/kimai
nano docker-compose.yml

services:
  mysql:
    image: mariadb:11
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: замените_на_свой_пароль
      MYSQL_DATABASE: kimai
      MYSQL_USER: kimai
      MYSQL_PASSWORD: замените_на_свой_пароль
    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - kimai_net

  kimai:
    image: kimai/kimai2:apache
    restart: unless-stopped
    depends_on:
      - mysql
    environment:
      DATABASE_URL: "mysql://kimai:замените_на_свой_пароль@mysql/kimai?charset=utf8mb4"
      ADMINMAIL: "admin@example.com"
      ADMINPASS: "замените_на_свой_пароль"
      TRUSTED_HOSTS: "kimai.example.com,localhost,127.0.0.1"
      APP_ENV: prod
    volumes:
      - kimai_data:/opt/kimai/var/data
      - kimai_plugins:/opt/kimai/var/plugins
    ports:
      - "127.0.0.1:8001:8001"
    networks:
      - kimai_net

volumes:
  mysql_data:
  kimai_data:
  kimai_plugins:

networks:
  kimai_net:

Важные моменты:

• Пароли в MYSQL_PASSWORD и DATABASE_URL должны совпадать — это частая причина, почему контейнер Kimai падает при первом старте.
• Порт публикуем только на 127.0.0.1, наружу пускать будем через reverse proxy — так безопаснее и проще подключить HTTPS.
• TRUSTED_HOSTS обязательно должен включать реальный домен, иначе Kimai будет отдавать 400 Bad Request при заходе через браузер.

Запускаем:

docker compose up -d
docker compose logs -f kimai

Первый старт создаёт схему БД и админ-аккаунт — это может занять минуту-две. В логах должно появиться что-то вроде Kimai is ready. Проверить, что всё поднялось:

docker compose ps
curl -I http://127.0.0.1:8001

Если ждёте 200 OK (или редирект на /en/login) — контейнер жив, идём дальше к proxy.

Настройка HTTPS через reverse proxy

Публиковать порт напрямую без TLS — плохая идея: логины и данные о клиентах будут ходить открытым текстом. Проще всего поставить Caddy (автоматический SSL от Let's Encrypt без лишней возни) или Nginx с certbot. Если у вас уже есть Traefik для других контейнеров на этом сервере — логичнее повесить Kimai на него как ещё один сервис. Разница между подходами разобрана в статье про выбор между Caddy и Nginx.

Вариант с Caddy — минимум конфига. Ставим:

apt update && apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
apt update && apt install -y caddy

Конфиг /etc/caddy/Caddyfile:

kimai.example.com {
    reverse_proxy 127.0.0.1:8001
}

systemctl reload caddy

Caddy сам выпустит и продлит сертификат Let's Encrypt при первом обращении к домену — никаких дополнительных команд не нужно. Если предпочитаете ручной контроль над сертификатами — сравнение подходов есть в статье Certbot или acme.sh.

После этого заходите на https://kimai.example.com, логинитесь под ADMINMAIL/ADMINPASS из compose-файла и сразу меняете пароль в профиле — значение в переменной окружения используется только при первой инициализации.

Базовая настройка после установки

Сразу после первого входа стоит пройтись по нескольким пунктам:

1. Сменить пароль администратора и включить 2FA (Профиль → Security) — особенно если система смотрит в интернет напрямую.
2. Создать клиентов и проекты — структура в Kimai трёхуровневая: Клиент → Проект → Активность (задача). Именно на уровне активности задаются ставки, если они отличаются от базовой ставки проекта.
3. Настроить временную зону и формат даты в System Settings → Configuration — по умолчанию может стоять UTC, что путает при просмотре отчётов.
4. Добавить пользователей через Administration → Users, назначить роли (Standard User, Team Lead, Administrator). Ролевая модель гибкая — можно давать доступ только к своим проектам.
5. Настроить бюджеты и алерты, если считаете рентабельность — Kimai умеет подсвечивать проекты, где потрачено времени больше бюджета.

Отдельно стоит зайти в System Settings → Plugins/Bundles — часть функциональности (например, расширенная отчётность) идёт как бандлы, которые можно включать по необходимости, не раздувая интерфейс лишним.

Резервное копирование

Данные Kimai — это MySQL-база плюс каталог var/data (загруженные файлы, аватары, логотипы для PDF-инвойсов). Backup стоит гнать по обоим направлениям.

Дамп базы данных по крону:

#!/bin/bash
cd /opt/kimai
docker compose exec -T mysql mysqldump -u kimai -pзамените_на_свой_пароль kimai | gzip > /opt/backups/kimai-db-$(date +%F).sql.gz
find /opt/backups -name "kimai-db-*.sql.gz" -mtime +14 -delete

Плюс архив данных:

docker run --rm -v kimai_kimai_data:/data -v /opt/backups:/backup alpine \
  tar czf /backup/kimai-data-$(date +%F).tar.gz -C /data .

Как оформить это регулярной задачей и на что обратить внимание с правами и логами — подробно в разборе cron-задач на сервере. Если хочется более серьёзной схемы с версионированием и восстановлением по snapshot — присмотритесь к BorgBackup, он умеет дедупликацию и экономит место на бэкапах, которые копятся годами.

Проверяйте восстановление хотя бы раз в квартал на тестовом окружении — бэкап, который ни разу не разворачивали, по факту не бэкап, а файл, в существование которого вы верите на слово.

Обновление и обслуживание

Kimai обновляется довольно часто — патчи безопасности и новые фичи. С Docker-версией обновление сводится к смене тега образа:

cd /opt/kimai
docker compose pull kimai
docker compose up -d kimai

Перед мажорным обновлением (например, между релизными ветками) обязательно сделайте свежий дамп базы — миграции схемы необратимы без бэкапа. В release notes на GitHub-репозитории Kimai обычно явно пишут, если апдейт требует ручных шагов помимо стандартной миграции — стоит проверять перед pull, а не после.

Для мониторинга, что сервис вообще жив (пусть даже без сложного стека алертинга), достаточно простого проверочного скрипта на curl -I с уведомлением в Telegram при неответе — расписывать полноценный Prometheus/Grafana ради одного сервиса обычно избыточно, если у вас не десяток таких контейнеров на сервере.

Частые вопросы