Instalación, configuración y uso de Kimai2, herramienta web open source de organización de tareas y rastreo del tiempo

Desde Montera34 estamos ayudando a montar el Banco del tiempo de Wikitoki. Wikitoki es el espacio en el que trabaja Pablo en Bilbao. Hemos elegido el software Kimai2 para que cada persona que participa en las tareas comunes del espacio registre sus horas. Para elegir Kimai2 hemos hecho un análisis comparativo de unas cuantas herramientas, que cuando tenga un rato publicaré. De momento publico un pequeño manual para poner en marcha Kimai2.

Kimai es una herramienta para organizar tareas y los equipos que las trabajan, y registrar el tiempo (time tracker) que se dedica a cada una de ellas. También dispone de algunas herramientas básicas (estadísticas, algún diagrama de barras) para evaluar la dedicación de cada persona del equipo. Se utiliza usando una interfaz web disponible a través de cualquier navegador. No tiene aplicación móvil pero su interfaz está adaptada para usarse en cualquier dispositivo.

El desarrollo está liderado por Kevin Papst, aunque no siempre ha sido así. Kevin Papst rescribió prácticamente todo el código y liberó Kimai2. Actualmente tiene una comunidad de desarrolladores considerable detrás: 24 personas contribuyen a su desarrollo, según su repositorio de Github. El software está liberado bajo licencia MIT, así que es open source.

Requisitos

Kimai2 está escrita en PHP y usa el framework Symphony. Está bien documentada y es fácil de instalar y actualizar. No tiene muchos requerimientos: Kimai2 en el momento de escribir esta entrada necesita PHP 7.2 o una versión más reciente. Los siguientes módulos de PHP tienen que estar activos: xml, mbstring, gd, intl, zip and PDO con el modo pdo_sqlite o pdo_mysql habilitado. Además necesita una base de datos y no mucho más.

Instalación y configuración inicial

La documentación recomienda instalar kimai usando la línea de comandos. Si se tiene acceso SSH a la máquina en la que se quiere instalar Kimai2 la instalación es cuestión de ejecutar dos comandos: unos para descargar el repositorio, otro para realizar la instalación con composer.

Si la máquina no tiene instalados composer y git, hay que instalarlos:

user@server:~$ sudo apt install composer git

También hay que crear una base de datos para Kimai2. Y tener en cuenta los requisitos de Symphony a la hora de preparar el servidor. Luego hay que clonar el repositorio y ejecutar composer:

user@server:/var/www$ git clone -b 1.7 --depth 1 https://github.com/kevinpapst/kimai2.git
user@server:/var/www$ cd kimai2/
user@server:/var/www/kimai2$ composer install --no-dev --optimize-autoloader

1.7 es la última versión de Kimai2 en el momento de escribir esta entrada. Recomiendo consultar la documentación de instalación de Kimai2 para saber qué versión instalar. Hay que asegurarse que los permisos de la carpeta que contiene los archivos de kimai están bien configurados. Cada entorno tiene una configuración diferente así que no hay una regla fija aquí. La documentación de Symphony cubre la mayoría de los casos.

Las variables fundamentales de configuración están en el archivo .env, que es una copia de la plantilla que contiene el archivo .env.dist. Este archivo está bien auto-documentado. Es importante configurar la dirección de correo y el servidor desde la que se enviarán las notificaciones, y la base de datos:

# Notificaciones
MAILER_FROM=mail@example.org
# Para bases de datos MySQL:
DATABASE_URL=mysql://db_user:db_password@127.0.0.1:3306/db_name
# Para base de datos SQLite:
# DATABASE_URL=sqlite:///%kernel.project_dir%/var/data/kimai.sqlite
MAILER_URL=smtp://username:password@smtp.server:port

Luego se puede ejecutar el instalador de Kimai2:

user@server:/var/www/kimai2$ bin/console kimai:install -n

En la página dedicada a la configuración de la documentación de Kimai2 se encuentran los principales archivos de configuración:

• .env. Configuraciones generales del entorno de Kimai2. Es la copia editable de .env.dist.
• config/packages/kimai.yaml. Configuración específica de Kimai2. Para sobrescribir cualquiera de las opciones de este archivo hay que crear una copia en config/packages/local.yaml.
• config/packages/admin_lte.yaml. Theme por omisión de Kimai2.
• config/packages/fos_user.yaml. Opciones para la gestión de usuarios y las notificaciones que se les envían.
• config/packages/local.yaml. Contiene las opciones de config/packages/kimai.yaml que se quieran sobrescribir. Este archivo no existe en una instalación nueva de Kimai2, hay que crearlo.

Creación de usuarios

Los usuarios en Kimai2 se pueden crear también desde la línea de comandos:

user@server:/var/www/kimai2$ bin/console kimai:create-user username admin@example.com ROLE_SUPER_ADMIN

Los roles posibles para los usuarios son:

• ROLE_SUPER_ADMIN. Tiene todos los privilegios.
• ROLE_ADMIN. Tiene todos los privilegios sobre todos los tipos de contenido: hojas de tiempo, clientes, proyectos, actividades, tags, equipos de usuarios. No puede crear usuarios ni modificar la configuración de la instancia.
• ROLE_TEAMLEAD. Puede administrar equipos de usuarios.

Instalar plugins de Kimai2

Actualmente no hay muchos plugins dispones para Kimai2. En cualquier caso instalarlos es sencillo. Para instalar, por ejemplo, el plugin Custom CSS Bundle, para poder incluir reglas de CSS adicionales desde el panel de control de Kimai2:

user@server:/var/www/kimai2$ cd var/plugins
git clone https://github.com/Keleo/CustomCSSBundle.git

Tras instalar un nuevo plugin hay que limpiar el cache de Kimai2:

user@server:/var/www/kimai2$ bin/console cache:clear
bin/console cache:warmup

Actualizar Kimai2

En la documentación oficial se pueden consultar los pasos generales para actualizar Kimai2, aunque algunas versiones pueden requerir pasos adicionales).

Antes de empezar la actualización conviene hacer una copia de seguridad de los archivos y la base de datos:

user@server:/var/www/kimai2$ cd ..
user@server:/var/www$ tar zcvf kimai2.backup.tar.gz kimai2/
user@server:/var/www$ mysqldump -u db_user -p db_name > kimai2.backup.sql

Luego se puede actualizar de la siguiente manera:

user@server:/var/www$ cd kimai2
user@server:/var/www$ git fetch --tags
user@server:/var/www$ git checkout 1.7
user@server:/var/www$ composer install --no-dev --optimize-autoloader
user@server:/var/www$ bin/console kimai:update
Loading composer repositories with package information
Installing dependencies from lock file

Prefetching 112 packages 🎶 💨
...

De nuevo, la rama 1.7 es un ejemplo, cambiará en función de la versión a la que se quiere actualizar. La última versión se puede consultar en la documentación oficial.