Kimai en un VPS: instalación, configuración y mantenimiento

La instalación de Kimai en un VPS implica el despliegue de contenedores Docker con la aplicación y la base de datos, la configuración de un proxy inverso para el acceso por nombre de dominio con soporte HTTPS, así como la planificación de copias de seguridad y actualizaciones regulares para garantizar el funcionamiento estable del autoalojamiento. Esto le permite obtener un sistema completo de seguimiento del tiempo, totalmente bajo su control.

Kimai es una aplicación web de código abierto potente y flexible, diseñada para el seguimiento del tiempo, la monitorización de proyectos y la gestión de clientes. Es ideal para freelancers, pequeñas y medianas empresas, así como para equipos que requieren un control detallado sobre el tiempo invertido y la facturación. Al desplegar Kimai en su propio VPS, obtiene control total sobre los datos, la seguridad y el rendimiento, evitando las limitaciones y las tarifas de suscripción de los servicios en la nube. En este artículo, desglosaremos en detalle cómo realizar la instalación de Kimai en su servidor virtual, utilizando Docker para una máxima simplicidad y portabilidad.

¿Qué es Kimai y por qué lo necesita en un VPS?

Kimai es una solución moderna y multiplataforma para el seguimiento del tiempo que ayuda a gestionar eficazmente las horas de trabajo. Permite registrar las horas dedicadas a diferentes proyectos y tareas, generar informes, emitir facturas y mucho más. La principal ventaja de Kimai radica en su flexibilidad y la posibilidad de tenerlo kimai self-hosted en su propio servidor, lo que garantiza la independencia de proveedores externos y la soberanía total sobre sus datos.

Características clave y ventajas de Kimai

• Seguimiento de tiempo flexible: Registre el tiempo manualmente o use el cronómetro incorporado. Posibilidad de vincular el tiempo a clientes, proyectos y tareas.
• Gestión de clientes y proyectos: Cree y gestione un número ilimitado de clientes y proyectos, asigne tarifas para cada uno de ellos.
• Informes detallados: Genere informes personalizables sobre tiempo, gastos, ganancias, expórtelos en varios formatos (CSV, PDF, XLSX).
• Facturación: Funciones integradas para crear facturas basadas en el tiempo registrado.
• Soporte multiusuario: Agregue usuarios con diferentes roles y permisos (administrador, gerente, usuario).
• Código abierto: Transparencia total y posibilidad de personalización según sus necesidades.
• API: RESTful API para la integración con otros sistemas.
• Plugins y extensiones: Amplias posibilidades para extender la funcionalidad.

¿Por qué un VPS para Kimai?

La elección de un hosting VPS para Kimai en el servidor se debe a varios factores importantes. Un servidor privado virtual proporciona un equilibrio ideal entre costo, rendimiento y control. A diferencia del hosting compartido tradicional, un VPS le otorga acceso root, lo que le permite instalar cualquier software necesario (por ejemplo, Docker), configurar parámetros del sistema y garantizar la seguridad al nivel deseado. Esto es crucial para el despliegue de aplicaciones como Kimai, que requieren un entorno de servidor específico.

Alojar kimai vps también garantiza que sus datos se almacenarán en el centro de datos de su elección, cumpliendo con los requisitos de privacidad locales o corporativos. Se libra de los riesgos asociados con las políticas de uso de datos de servicios de terceros y puede estar seguro de su seguridad. Además, obtiene un rendimiento predecible, independiente de los "vecinos" del servidor, lo que a menudo es un problema en los hostings compartidos. Esto es especialmente importante para la escalabilidad, a medida que aumente el número de usuarios y datos en Kimai.

Requisitos del sistema de Kimai: ¿qué necesita saber?

Antes de proceder con la instalación de Kimai, es importante comprender qué recursos necesitará su servidor virtual. Kimai es relativamente poco exigente en cuanto a recursos para equipos pequeños, pero a medida que crece el número de usuarios y el volumen de datos, los requisitos aumentan. El uso de Docker simplifica la gestión de dependencias, pero no elimina la necesidad de una cantidad suficiente de CPU, RAM y espacio en disco.

Configuraciones mínimas y recomendadas para Kimai self-hosted

Kimai funciona con PHP (versión 8.1 o superior) y requiere una base de datos (MySQL 8.0+, MariaDB 10.5+ o PostgreSQL 13+). Para trabajar con Docker, también necesitará suficiente espacio para las imágenes y los contenedores.

• Requisitos mínimos (hasta 5 usuarios, pocos proyectos):
  • CPU: 1 vCore
  • RAM: 1 GB (mínimo 512 MB para Kimai + 512 MB para el SO y Docker)
  • Disco: 20 GB NVMe (para el SO, imágenes Docker y datos)
  • Sistema operativo: Ubuntu 22.04+, Debian 11+
• Requisitos recomendados (hasta 20 usuarios, uso activo, informes):
  • CPU: 2 vCores
  • RAM: 2 GB
  • Disco: 40 GB NVMe
  • Sistema operativo: Ubuntu 22.04+, Debian 11+
• Para equipos grandes (más de 20 usuarios, trabajo intensivo, integraciones API):
  • CPU: 4+ vCores
  • RAM: 4+ GB
  • Disco: 80+ GB NVMe
  • Sistema operativo: Ubuntu 22.04+, Debian 11+

Es importante recordar que los discos NVMe aceleran significativamente el rendimiento de la base de datos y de la aplicación en general, por lo que son preferibles para kimai self-hosted.

Elección del sistema operativo

Para el despliegue de Kimai en un VPS a través de Docker, la opción más óptima son las distribuciones de Linux, como Ubuntu Server (22.04 LTS y superior) o Debian (11 y superior). Estos sistemas operativos están bien documentados, cuentan con un amplio soporte de la comunidad y funcionan de manera estable con Docker. Ubuntu a menudo se elige por su facilidad de uso y sus paquetes actualizados, Debian por su estabilidad y minimalismo. En este artículo, todos los comandos se presentarán para sistemas basados en Debian/Ubuntu.

Preparación del VPS para la instalación de Kimai Docker

Antes de proceder con la instalación de Kimai, es necesario preparar su servidor virtual. Esto incluye la actualización del sistema, la instalación de Docker y Docker Compose, así como la configuración del nombre de dominio.

Actualización del sistema e instalación de Docker/Docker Compose

Conéctese a su VPS por SSH. Primero, actualice los paquetes del sistema para asegurarse de que tiene las versiones de software y los parches de seguridad más recientes:

sudo apt update && sudo apt upgrade -y

A continuación, instale Docker. Se recomienda utilizar el repositorio oficial de Docker para obtener la versión más reciente. Ejecute los siguientes comandos:

# Instalación de paquetes necesarios
sudo apt install ca-certificates curl gnupg lsb-release -y

# Añadir la clave GPG de Docker
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Añadir el repositorio de Docker
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Actualizar el índice de paquetes e instalar Docker Engine
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Verifique que Docker esté instalado y en ejecución:

sudo systemctl status docker

Verá el estado "active (running)". Agregue su usuario al grupo docker para no tener que usar sudo para cada comando de Docker:

sudo usermod -aG docker $USER
newgrp docker

Ahora puede verificar la instalación de Docker ejecutando:

docker run hello-world

Y asegúrese de que el plugin de Docker Compose funciona:

docker compose version

Configuración del nombre de dominio y DNS

Para acceder a Kimai en el servidor a través del navegador con un nombre bonito, en lugar de una dirección IP, necesitará un nombre de dominio. Registre un dominio con cualquier registrador y configure un registro A que apunte a la dirección IP de su VPS. Por ejemplo, si su dominio es yourdomain.com, puede crear un subdominio kimai.yourdomain.com y dirigirlo a la IP de su servidor. Asegúrese de que los registros DNS se hayan actualizado (esto puede tardar varias horas).

Instalación paso a paso de Kimai en un VPS con Docker Compose

Ahora que su VPS está listo, puede proceder con la instalación de Kimai Docker. Utilizaremos Docker Compose para definir y ejecutar todos los servicios necesarios (Kimai, base de datos).

Creación del archivo docker-compose.yml

Cree un directorio para sus archivos de Kimai y navegue hasta él:

mkdir -p ~/kimai
cd ~/kimai

Cree el archivo docker-compose.yml usando un editor de texto (por ejemplo, nano):

nano docker-compose.yml

Pegue el siguiente contenido. Esta es una configuración estándar para kimai self-hosted utilizando MySQL/MariaDB. Reemplace YOUR_DOMAIN.COM, YOUR_DB_PASSWORD, YOUR_DB_USER, YOUR_DB_NAME con sus propios valores.

version: '3.8'

services:
  database:
    image: mariadb:10.11
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - database_data:/var/lib/mysql
    networks:
      - kimai-network

  kimai:
    image: kimai/kimai2:latest
    restart: unless-stopped
    env_file:
      - .env
    depends_on:
      - database
    ports:
      - "8001:8000" # Kimai por defecto escucha en el puerto 8000 dentro del contenedor
    networks:
      - kimai-network

volumes:
  database_data:

networks:
  kimai-network:
    driver: bridge

Ahora cree el archivo .env en el mismo directorio. Este archivo contendrá las variables de entorno para la base de datos y Kimai. Reemplace YOUR_DB_PASSWORD, YOUR_DB_USER, YOUR_DB_NAME con sus propios valores. Asegúrese de que la contraseña sea lo suficientemente compleja.

nano .env

# Database configuration
DATABASE_URL=mysql://YOUR_DB_USER:YOUR_DB_PASSWORD@database:3306/YOUR_DB_NAME?serverVersion=10.11&charset=utf8mb4

# Kimai configuration
APP_ENV=prod
APP_SECRET=your_secret_key_here # Genere una clave única, por ejemplo, "openssl rand -base64 32"
TRUSTED_HOSTS=^localhost$,^127\.0\.0\.1$,^YOUR_DOMAIN\.COM$ # Reemplace con su dominio
MAILER_URL=smtp://user:[email protected]:587 # Opcional: para el envío de correo de Kimai

Para APP_SECRET, genere una clave única, por ejemplo, con el comando openssl rand -base64 32. TRUSTED_HOSTS debe incluir su dominio a través del cual accederá a Kimai. Por ejemplo, si usa kimai.yourdomain.com, la línea será TRUSTED_HOSTS=^localhost$,^127\.0\.0\.1$,^kimai\.yourdomain\.com$. Si usa varios dominios o subdominios, sepárelos con comas.

Inicio de Kimai y configuración inicial

Después de crear los archivos docker-compose.yml y .env, puede iniciar Kimai:

docker compose up -d

La opción -d inicia los contenedores en segundo plano. Docker descargará las imágenes necesarias (MariaDB y Kimai), creará los contenedores y los iniciará. Esto puede tardar varios minutos la primera vez que se ejecuta.

Verifique el estado de los contenedores en ejecución:

docker compose ps

Debería ver que ambos contenedores (kimai-database-1 y kimai-kimai-1) están en estado "running".

Ahora Kimai está disponible en la dirección IP de su VPS y el puerto 8001 (por ejemplo, http://SU_DIRECCION_IP:8001). Abra esta dirección en su navegador. Debería ver la página de inicio de sesión de Kimai.

Las credenciales de administrador predeterminadas para el primer inicio de sesión son:

• Nombre de usuario: admin
• Contraseña: kimai

¡Asegúrese de cambiar estas credenciales inmediatamente después del primer inicio de sesión!

En este punto, la instalación de Kimai está completa. Sin embargo, para un acceso seguro y conveniente por nombre de dominio con HTTPS, será necesario configurar un proxy inverso.

Configuración de Reverse Proxy y HTTPS para Kimai en el servidor

El acceso directo a Kimai por dirección IP y puerto no estándar (8001) no es la solución ideal. Para un despliegue profesional de Kimai en el servidor, se recomienda utilizar un proxy inverso (por ejemplo, Nginx o Caddy) para enrutar el tráfico al contenedor de Kimai y proporcionar cifrado HTTPS utilizando Let's Encrypt.

Uso de Nginx como Reverse Proxy

Nginx es un servidor web de alto rendimiento que es excelente para el rol de proxy inverso. Si Nginx aún no está instalado en su VPS, instálelo:

sudo apt install nginx -y

Cree un nuevo archivo de configuración para su dominio Kimai:

sudo nano /etc/nginx/sites-available/kimai.conf

Pegue la siguiente configuración, reemplazando kimai.yourdomain.com con su dominio real:

server {
    listen 80;
    listen [::]:80;
    server_name kimai.yourdomain.com;

    # Redirección HTTP a HTTPS (se configurará más tarde con Certbot)
    # return 301 https://$host$request_uri;

    location / {
        proxy_pass http://localhost:8001; # Puerto en el que Kimai escucha dentro del contenedor
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_http_version 1.1;
        proxy_read_timeout 900s;
        proxy_send_timeout 900s;
        proxy_connect_timeout 900s;
        proxy_redirect off;
    }
}

Guarde el archivo y cree un enlace simbólico a él en sites-enabled:

sudo ln -s /etc/nginx/sites-available/kimai.conf /etc/nginx/sites-enabled/

Verifique la configuración de Nginx en busca de errores y reinícielo:

sudo nginx -t
sudo systemctl restart nginx

Ahora puede acceder a Kimai a través de su nombre de dominio (por ejemplo, http://kimai.yourdomain.com). El siguiente paso es asegurar HTTPS.

Automatización de HTTPS con Let's Encrypt a través de Certbot

Let's Encrypt proporciona certificados SSL/TLS gratuitos, y Certbot automatiza el proceso de obtención e instalación. Instale Certbot y el plugin para Nginx:

sudo apt install certbot python3-certbot-nginx -y

Ejecute Certbot para su dominio. Encontrará automáticamente la configuración de Nginx y configurará HTTPS:

sudo certbot --nginx -d kimai.yourdomain.com

Certbot le hará algunas preguntas (correo electrónico, aceptación de los términos). Después de una ejecución exitosa, actualizará automáticamente la configuración de Nginx, agregando HTTPS y la redirección de HTTP a HTTPS. Verifique que la renovación automática de certificados funcione:

sudo systemctl status certbot.timer

Ahora su kimai vps está disponible a través de una conexión HTTPS segura (https://kimai.yourdomain.com).

Alternativa: Caddy para mayor simplicidad

Para aquellos que buscan una solución más sencilla para el proxy inverso y HTTPS, Caddy es una excelente opción. Caddy obtiene y renueva automáticamente los certificados Let's Encrypt para todos los dominios configurados "de fábrica".

Instale Caddy (las instrucciones pueden variar ligeramente según el SO, pero para Debian/Ubuntu suele ser así):

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

Cree el archivo de configuración Caddyfile:

sudo nano /etc/caddy/Caddyfile

Reemplace el contenido con lo siguiente, especificando su dominio:

kimai.yourdomain.com {
    reverse_proxy localhost:8001
}

Reinicie Caddy:

sudo systemctl restart caddy

Caddy configurará automáticamente HTTPS para su dominio. Esto es significativamente más sencillo que la configuración manual de Nginx y Certbot, pero Nginx ofrece más opciones para una configuración fina.

Mantenimiento de Kimai en un VPS: copias de seguridad y actualizaciones

Mantener Kimai self-hosted en funcionamiento requiere un mantenimiento regular, que incluye la copia de seguridad de los datos y las actualizaciones oportunas. Estos pasos son cruciales para garantizar la estabilidad, seguridad y disponibilidad de su aplicación.

Estrategias de copia de seguridad para Kimai self-hosted

La copia de seguridad es el aspecto más importante del mantenimiento de cualquier servidor. Para Kimai, es necesario realizar copias de seguridad regularmente de dos componentes principales:

1. Base de datos: Contiene todos los registros de tiempo, clientes, proyectos, usuarios y configuraciones.
2. Datos de Kimai: Incluyen archivos de configuración, archivos subidos (si Kimai los utiliza) y otros datos específicos de la aplicación. En nuestro caso, dado que Kimai se ejecuta en Docker, los archivos modificables principales son los que se almacenan en los volúmenes.

Para una base de datos MariaDB/MySQL que se ejecuta en Docker, puede usar el comando mysqldump desde dentro del contenedor:

# Obtener el nombre del contenedor de la base de datos
DB_CONTAINER_NAME=$(docker compose ps -q database)

# Realizar la copia de seguridad de la base de datos
docker exec $DB_CONTAINER_NAME sh -c 'exec mysqldump -u YOUR_DB_USER -pYOUR_DB_PASSWORD YOUR_DB_NAME' > ~/kimai_backup/kimai_db_$(date +%F).sql

Reemplace YOUR_DB_USER, YOUR_DB_PASSWORD, YOUR_DB_NAME con los valores actuales de su archivo .env.

Para la copia de seguridad de los volúmenes de Docker donde se almacenan los datos de Kimai (si montó volúmenes adicionales para archivos, además de la base de datos):

# Crear un archivo de la carpeta con los datos de Kimai, si contiene archivos importantes
# Por ejemplo, si utiliza un volumen local para configuraciones o archivos subidos
tar -czvf ~/kimai_backup/kimai_files_$(date +%F).tar.gz ~/kimai/

Se recomienda automatizar este proceso utilizando tareas Cron. Por ejemplo, para una copia de seguridad diaria de la base de datos:

crontab -e

Agregue la línea (reemplace la ruta al script y las credenciales):

0 3 * * * /bin/bash -c "DB_CONTAINER_NAME=$(docker compose ps -q database) && docker exec $DB_CONTAINER_NAME sh -c 'exec mysqldump -u YOUR_DB_USER -pYOUR_DB_PASSWORD YOUR_DB_NAME' > /path/to/your/kimai_backup/kimai_db_$(date +\%F).sql"

Para un enfoque más completo de las copias de seguridad en un VPS, incluyendo copias de seguridad incrementales y almacenamiento en repositorios remotos, considere herramientas como Restic. Esto garantizará un almacenamiento fiable y una recuperación rápida en caso de fallos.

Proceso de actualización de Kimai Docker

Actualizar Kimai, desplegado a través de Docker Compose, es un proceso relativamente sencillo. Las actualizaciones regulares son importantes para obtener nuevas funciones, correcciones de errores y parches de seguridad.

¡Antes de actualizar, siempre haga una copia de seguridad de la base de datos!

# Vaya al directorio con docker-compose.yml
cd ~/kimai

# Detenga los contenedores actuales
docker compose down

# Elimine las imágenes antiguas (opcional, pero recomendado para limpieza)
docker compose rm -f

# Descargue las nuevas imágenes e inicie los contenedores
docker compose pull
docker compose up -d

Después de iniciar los nuevos contenedores, Kimai realizará automáticamente las migraciones de base de datos necesarias en el primer arranque de la nueva imagen. Si encuentra problemas después de la actualización, revise los logs del contenedor de Kimai:

docker compose logs kimai

Si Kimai requiere comandos adicionales para la migración de la base de datos o la limpieza de la caché después de una actualización, esto generalmente se indica en la documentación oficial de Kimai. Por ejemplo, a veces es necesario ejecutar:

docker compose exec kimai bin/console doctrine:migrations:migrate --no-interaction
docker compose exec kimai bin/console cache:clear

Sin embargo, para la mayoría de las actualizaciones menores, un simple docker compose pull && docker compose up -d es suficiente.

Elección de la configuración de VPS para Kimai: escenarios reales

La elección de la configuración correcta de kimai vps afecta directamente el rendimiento y el costo. Para kimai self-hosted, es importante encontrar un equilibrio entre recursos suficientes para un trabajo cómodo y costos razonables. Valebyte ofrece varios planes de tarifas que pueden adaptarse a Kimai para diferentes escenarios de carga.

Tabla comparativa de VPS para Kimai bajo diferentes cargas

A continuación, se presenta una tabla con recomendaciones de configuraciones de VPS para Kimai, basadas en el número de usuarios y la intensidad de uso. Los precios son orientativos y pueden variar.

Escenario de uso	Usuarios	vCPU	RAM	Disco (NVMe)	Ejemplo de plan Valebyte*	Precio estimado/mes*
Personal / Pruebas	1-3	1	1 GB	20 GB	VPS-1 Core	$5 - $7
Equipo pequeño / Freelance	4-10	2	2 GB	40 GB	VPS-2 Core	$10 - $15
Equipo mediano / Uso activo	11-25	2-4	4 GB	80 GB	VPS-4 Core	$20 - $30
Equipo grande / Corporativo	25+	4-8	8+ GB	160+ GB	VPS-8 Core	$40+

*Los precios y nombres de los planes son ejemplos y pueden diferir de la oferta actual de Valebyte. Siempre verifique las tarifas actuales en el sitio web del proveedor.

Es importante recordar que los discos NVMe aumentan significativamente la velocidad de la base de datos, lo cual es crucial para el rendimiento de Kimai, especialmente al generar informes y con un gran número de registros.

Recomendaciones para la escalabilidad

A medida que su equipo y el volumen de datos en Kimai crezcan, es posible que necesite escalar su VPS. Aquí tiene algunos consejos:

1. Monitorización de recursos: Supervise regularmente la carga de CPU, el uso de RAM y el espacio en disco en su VPS. Herramientas como htop, glances o Prometheus/Grafana le ayudarán a comprender qué recursos son el cuello de botella.
2. Escalado de RAM: A menudo, el primer cuello de botella es la memoria RAM, especialmente para la base de datos. Aumentar la RAM suele proporcionar un aumento notable del rendimiento.
3. Escalado de CPU: Si los usuarios experimentan con frecuencia retrasos al ejecutar consultas complejas o generar informes, aumentar el número de núcleos de CPU puede ayudar.
4. Optimización de la base de datos: Asegúrese de que su base de datos esté configurada de manera óptima. Para MariaDB/MySQL, esto puede incluir la configuración de innodb_buffer_pool_size y otros parámetros en my.cnf.
5. Elección de un VPS más potente: Si el VPS actual no es suficiente, considere la posibilidad de actualizar a un plan de tarifas más potente. La flexibilidad del hosting VPS permite actualizar fácilmente los recursos sin reinstalar. Muchas otras aplicaciones para aumentar la productividad, como Kanboard o Invoice Ninja, también pueden requerir un enfoque similar para la escalabilidad de recursos.
6. Limpieza de datos antiguos: Si Kimai se ha utilizado durante mucho tiempo y no necesita los datos antiguos, considere archivarlos o eliminarlos para mantener el rendimiento de la base de datos.

Conclusiones

La instalación y configuración de Kimai en un VPS a través de Docker Compose es una forma eficaz de obtener un potente sistema de seguimiento del tiempo con control total sobre los datos. Es importante no solo desplegar correctamente la aplicación, sino también garantizar su seguridad, copias de seguridad regulares y actualizaciones oportunas. Al elegir un VPS de Valebyte con discos NVMe, obtendrá una base fiable para el funcionamiento estable y rápido de su solución Kimai self-hosted, capaz de escalar según las crecientes necesidades de su equipo.