Hướng dẫn Kimai

Kimai: Hướng dẫn Time Tracking & Quản lý Thời gian

I. Giới thiệu Kimai

Kimai là phần mềm theo dõi thời gian (time tracking) mã nguồn mở, giúp quản lý thời gian làm việc của nhân viên và dự án. Điều này rất hữu ích khi:

Bạn cần theo dõi thời gian làm việc của team
Muốn tính toán chi phí dự án dựa trên giờ làm
Cần báo cáo thời gian cho khách hàng (billable hours)
Quản lý timesheet & attendance
Muốn công cụ miễn phí thay vì Toggl/Harvest

Chức năng chính Kimai:

Time Tracking: Theo dõi thời gian theo dự án & activity
Projects & Activities: Quản lý dự án & công việc
Invoices: Tạo hóa đơn từ timesheet
Reports & Export: Báo cáo chi tiết (Excel, PDF)
Multi-user: Quản lý nhiều users & teams
Calendar View: Xem timesheet dạng lịch
Mobile Responsive: Sử dụng trên mobile
Plugins: Mở rộng tính năng

So sánh Kimai với các tool khác:

Tính năng	Kimai	Toggl	Harvest
Giá	Miễn phí (open source)	Trả phí ($monthly)	Trả phí ($monthly)
Self-hosted	Có	Không	Không
Invoicing	Có (plugins)	Có (paid)	Có
Reports	Có	Có (advanced)	Có
Ease of use	Dễ	Rất dễ	Dễ

II. Chuẩn bị Database

1. Tạo Database cho Kimai

Kết nối vào MySQL và tạo database:

mysql -h 127.0.0.1 -P 3366 -u root -p

-- Tạo database
CREATE DATABASE kimai CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- Tạo user
CREATE USER 'kimai'@'%' IDENTIFIED BY 'kimaipass';

-- Cấp quyền
GRANT ALL PRIVILEGES ON kimai.* TO 'kimai'@'%';

-- Reload
FLUSH PRIVILEGES;

2. Xác định Database URL

DATABASE_URL format:

mysql://username:password@host:port/database?charset=utf8mb4&serverVersion=8.3.0

Ví dụ:

Host trong cùng network: mysql://kimai:kimaipass@mysql_aio:3306/kimai?...
Host khác máy: mysql://kimai:[email protected]:3366/kimai?...

III. Triển khai Kimai với Docker

1. Docker Compose

version: "3.8"
services:
  kimai:
    image: kimai/kimai2:apache
    container_name: kimai_app
    ports:
      - "8081:8001"
    environment:
      - [email protected]
      - ADMINPASS=secure_admin_pass
      - DATABASE_URL=mysql://kimai:kimaipass@mysql_aio:3306/kimai?charset=utf8mb4&serverVersion=8.3.0
      - TIMEZONE=Asia/Ho_Chi_Minh
      - LOCALE=vi
    volumes:
      - /root/kimai/data:/opt/kimai/var/data
      - /root/kimai/plugins:/opt/kimai/var/plugins
    mem_limit: 1024m
    cpus: 0.2
    restart: unless-stopped
    networks:
      - docker-net
networks:
  docker-net:
    external: true

Giải thích cấu hình:

image: kimai/kimai2:apache (official image)
ports: 8081 (host) → 8001 (container)
ADMINMAIL: Email admin mặc định
ADMINPASS: Mật khẩu admin (đổi ngay!)
DATABASE_URL: Connection string tới MySQL
TIMEZONE: Asia/Ho_Chi_Minh
LOCALE: vi (Tiếng Việt)
volumes: Lưu data & plugins
networks: Sử dụng docker-net

2. Deploy qua Portainer

SSH vào server & tạo thư mục:

mkdir -p /root/kimai/data
mkdir -p /root/kimai/plugins

Vào Portainer Dashboard
Chọn Stacks → Add stack
Đặt tên Stack: kimai
Copy/paste docker-compose vào Web editor
Thay đổi:

ADMINPASS: Đặt password mạnh
DATABASE_URL: Điều chỉnh theo MySQL của bạn

Chọn network: docker-net
Click Deploy the stack

3. Kiểm tra hoạt động

Vào Portainer → Stacks → kimai → Container → kimai_app → Logs.

Bạn sẽ thấy dòng như:

Apache/2.4.xx (Unix) configured -- resuming normal operations
Kimai is ready!

Truy cập http://your-ip:8081 để vào Kimai.

4. Đăng nhập lần đầu

Đăng nhập với credentials:

Email: [email protected] (hoặc email bạn set)
Password: secure_admin_pass (password từ config)

LƯU Ý: Đổi password ngay sau khi đăng nhập!

IV. Sử dụng Kimai cơ bản

1. Tạo Users (Nhân viên)

Để thêm users vào hệ thống:

Vào Users → Create new user
Điền thông tin:

Username: john_doe
Email: [email protected]
Role: User / Teamlead / Admin
Password: (auto-generate hoặc tự đặt)

Click Create

2. Tạo Customers (Khách hàng)

Để quản lý khách hàng:

Vào Customers → Create customer
Điền:

Name: ABC Company
Number: CUST-001
Country: Vietnam
Timezone: Asia/Ho_Chi_Minh

Click Create

3. Tạo Projects (Dự án)

Để tạo dự án:

Vào Projects → Create project
Điền:

Name: Website Redesign
Customer: Chọn khách hàng
Budget: 100.000.000 VND
Hourly rate: 500.000 VND

Click Create

4. Tạo Activities (Hoạt động)

Để tạo loại công việc:

Vào Activities → Create activity
Điền:

Name: Development
Project: Chọn dự án

Hoặc tạo global activities (không thuộc dự án nào)

5. Track Time (Ghi nhận giờ làm)

Để bắt đầu tracking:

Vào Timesheet → Click Start
Chọn:

Project: Website Redesign
Activity: Development
Description: Implement login page

Click Start (timer bắt đầu)
Khi xong, click Stop

6. Xem Reports

Để xem báo cáo:

Vào Reporting
Chọn loại report:

Monthly: Báo cáo theo tháng
Project: Báo cáo theo dự án
User: Báo cáo theo nhân viên

Filter theo ngày, dự án, user
Export: Excel / PDF

V. Cấu hình Advanced

1. Proxy qua Nginx Proxy Manager

Để expose Kimai qua domain:

Vào Nginx Proxy Manager → Hosts → Proxy Hosts
Click Add Proxy Host
Điền:

Domain Names: time.yourdomain.com
Scheme: http
Forward Hostname/IP: kimai_app
Forward Port: 8001

Tab SSL: Request Let's Encrypt
Click Save

Truy cập https://time.yourdomain.com

2. Email Notifications

Để gửi email notifications:

Vào System → Configuration → Email
Cấu hình SMTP:

Transport: SMTP
Host: smtp.gmail.com
Port: 587
Username: [email protected]
Password: app-password

Click Test → Save

3. Plugins

Kimai hỗ trợ plugins để mở rộng tính năng:

Các plugins phổ biến:

Invoice Plugin: Tạo hóa đơn từ timesheet
Export Plugin: Export dữ liệu nhiều format
Custom Fields: Thêm trường tùy chỉnh
Approval Plugin: Phê duyệt timesheet

Cài plugins:

Download plugin từ Kimai marketplace
Extract vào /root/kimai/plugins/
Restart container Kimai
Vào Plugins → Enable plugin

4. Permissions & Roles

Phân quyền cho users:

Vào Users → Chọn user → Permissions
Cấu hình:

View timesheet: Xem timesheet của ai
Edit timesheet: Sửa timesheet
Create projects: Tạo dự án
Manage users: Quản lý users

5. Invoice Generation

Tạo hóa đơn từ timesheet:

Vào Invoice → Create invoice
Chọn:

Customer: ABC Company
Date range: 01/01/2024 - 31/01/2024
Project: Website Redesign

Preview → Generate PDF

VI. Backup & Management

1. Backup Kimai Data

Script backup:

#!/bin/bash
BACKUP_DIR=/root/backups
DATE=$(date +%Y%m%d_%H%M%S)

# Backup Kimai files
tar -czf $BACKUP_DIR/kimai_files_$DATE.tar.gz /root/kimai

# Backup database
docker exec mysql_aio mysqldump -u kimai -p"kimaipass" kimai > $BACKUP_DIR/kimai_db_$DATE.sql
gzip $BACKUP_DIR/kimai_db_$DATE.sql

# Keep 7 days
find $BACKUP_DIR -name "kimai_*" -mtime +7 -delete

2. Export Timesheet

Export timesheet dạng Excel/PDF:

Vào Reporting → Chọn report type
Filter dữ liệu
Click Export → Chọn format (XLSX, PDF)

VII. Troubleshooting

Kimai không kết nối database

Kiểm tra DATABASE_URL format đúng chưa
Test connection: docker exec kimai_app mysql -h mysql_aio -u kimai -p kimai
Kiểm tra MySQL container chạy chưa
Xem logs: docker logs kimai_app

Timezone không đúng

Kiểm tra TIMEZONE=Asia/Ho_Chi_Minh trong config
Restart container
Xem System → Configuration → Timezone

Performance chậm

Tăng mem_limit: 2048m
Kiểm tra database indexes
Archive old timesheets
Disable unused plugins

Không thể login

Kiểm tra ADMINMAIL & ADMINPASS trong config
Reset password qua database hoặc CLI
Xem logs để tìm error

VIII. Lưu ý quan trọng

Đổi mật khẩu admin: Sau lần đăng nhập đầu
Backup dữ liệu: Backup /root/kimai & database định kỳ
SSL/TLS: Sử dụng HTTPS qua Nginx Proxy Manager
Database URL: Format phải chính xác (serverVersion=8.3.0)
Timezone: Cấu hình đúng để timesheet chính xác
Permissions: Phân quyền users đúng roles
Plugins: Chỉ cài từ sources tin cậy
Invoice backup: Export invoices ra PDF định kỳ

IX. Best Practice

Tạo projects & activities rõ ràng
Yêu cầu users ghi description khi track time
Review timesheets định kỳ (weekly/monthly)
Sử dụng hourly rates để tính chi phí chính xác
Export reports hàng tháng cho accounting
Cấu hình email notifications cho managers
Archive completed projects để giảm load
Sử dụng approval workflow cho timesheets
Backup invoices sau khi generate
Monitor Kimai availability qua Uptime Kuma

X. Tích hợp với các tool khác

1. Monitor qua Uptime Kuma

Vào Uptime Kuma → Add Monitor
Type: HTTP(s)
URL: https://time.yourdomain.com
Interval: 300

2. Backup tự động qua Cron

Chạy backup script hàng ngày 2AM:

0 2 * * * /bin/bash /root/scripts/backup-kimai.sh

3. Alert qua Telegram/Slack

Gửi thông báo khi có timesheet mới cần approval.

4. Integration với n8n

Tự động hóa workflow:

Export timesheet hàng tuần qua email
Tạo invoice tự động vào cuối tháng
Sync dữ liệu với Google Sheets

XI. Use Cases thực tế

1. Software Development Team

Track thời gian theo features & sprints:

Projects: Sprint 1, Sprint 2, ...
Activities: Development, Testing, Code Review
Reports: Billable hours per sprint

2. Agency với Multiple Clients

Quản lý nhiều khách hàng & dự án:

Customers: Client A, Client B, ...
Projects per customer
Generate invoices monthly

3. Freelancer

Track thời gian & tính chi phí:

Track time per project
Export timesheet cho khách hàng
Calculate earnings

Vậy là bạn đã hoàn thành cấu hình Kimai để quản lý thời gian làm việc & tạo hóa đơn!

Docker Homelab Series - Phần 14: Kimai: Hướng dẫn Time Tracking & Quản lý Thời gian