Alojar Kimai en VPS: seguimiento de tiempo open source

¿Por qué alojar Kimai tú mismo?

• Licencia MIT — sin tarifas de licencia ni límite de usuarios impuesto por el proveedor.
• Facturación integrada — las facturas se generan directamente desde los partes de horas, sin módulos externos.
• API REST documentada — conecta tus herramientas internas (tickets, RR. HH., paneles) a tus propios datos.
• Soberanía de datos — horas, tarifas y fichas de clientes se quedan en tu base MySQL.
• Stack ligero — un contenedor de aplicación y una base MySQL, holgado en un VPS de entrada.

Arquitectura: qué se ejecuta en el VPS

Las piezas del stack

• Contenedor kimai — Apache y PHP, la aplicación Symfony en /opt/kimai, puerto 8001 publicado solo en 127.0.0.1.
• Contenedor db — MySQL 8.0 con un healthcheck mysqladmin ping: Kimai solo arranca cuando la base está lista.
• Volumen kimai_db — los ficheros de datos de MySQL, es decir, todos tus partes de horas.
• Volumen kimai_data — /opt/kimai/var/data, los ficheros subidos a la aplicación (plantillas de factura, documentos).
• Volumen kimai_public — /opt/kimai/public/avatars, los avatares de los usuarios.
• Proxy inverso — Nginx, Caddy o Traefik termina el HTTPS y reenvía las peticiones al puerto local 8001.

Desplegar Kimai en ServOrbit

1. 01

   Lanzar el despliegue

   En tu área de cliente: Marketplace → ERP y Gestión → Kimai → Desplegar. ServOrbit crea el VPS, instala Docker y arranca el stack (MySQL 8 + Apache/PHP) automáticamente.

2. 02

   Recuperar las credenciales

   Espera unos 60 segundos. La tarjeta de la app muestra tus credenciales: usuario [email protected] y contraseña generada.

3. 03

   Conectarse sin dominio

   Abre un túnel SSH: ssh -L 8080:127.0.0.1:8001 root@<ip> y luego http://localhost:8080. Añade un dominio desde el panel cuando lo tengas listo.

4. 04

   Crear cliente y proyecto

   Crea tu primer cliente, luego un proyecto vinculado y al menos una actividad. Fija una tarifa horaria o un presupuesto.

5. 05

   Registrar las primeras horas

   Haz clic en ▶ para iniciar el temporizador y elige proyecto y actividad: Kimai registra tus horas en tiempo real.

Instalación manual con Docker Compose

services:
  db:
    image: mysql:8.0
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: kimai
      MYSQL_USER: kimai
      MYSQL_PASSWORD: ${DB_PASSWORD}
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
    volumes:
      - kimai_db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "127.0.0.1", "--silent"]
      interval: 10s
      retries: 12

  kimai:
    image: kimai/kimai2:apache-latest
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:8001:8001"
    environment:
      DATABASE_URL: "mysql://kimai:${DB_PASSWORD}@db/kimai?charset=utf8mb4&serverVersion=8.0.34"
      APP_SECRET: ${APP_SECRET}
      ADMINMAIL: [email protected]
      ADMINPASS: ${ADMIN_PASSWORD}
      TRUSTED_HOSTS: "localhost,127.0.0.1,kimai.your-domain.com"
    volumes:
      - kimai_data:/opt/kimai/var/data
      - kimai_plugins:/opt/kimai/var/plugins
      - kimai_public:/opt/kimai/public/avatars

volumes:
  kimai_db:
  kimai_data:
  kimai_plugins:
  kimai_public:

cat > .env <<EOF
DB_PASSWORD=$(openssl rand -hex 16)
DB_ROOT_PASSWORD=$(openssl rand -hex 16)
APP_SECRET=$(openssl rand -hex 32)
ADMIN_PASSWORD=$(openssl rand -hex 12)
EOF
chmod 600 .env
docker compose up -d
docker compose logs -f kimai

Variables de entorno que conviene conocer

• DATABASE_URL — cadena de conexión de Doctrine: usuario, contraseña, host db, nombre de la base, charset=utf8mb4 y serverVersion. Como la contraseña va dentro de una URL, evita @, / o :; un secreto hexadecimal resuelve el problema.
• APP_SECRET — clave de Symfony con la que se firman sesiones y tokens. Un valor aleatorio largo, generado una vez y sin tocarlo después: cambiarlo cierra la sesión de todos.
• ADMINMAIL y ADMINPASS — la cuenta de superadministrador creada en el primer arranque. Con la instancia en marcha, gestiona las cuentas desde la interfaz o la consola.
• TRUSTED_HOSTS — lista de nombres de host aceptados, separados por comas. Debe incluir tu dominio público; si no, Symfony rechaza las peticiones.
• MAILER_URL — transporte de correo. La plantilla de ServOrbit lo fija en null://localhost, así que no se envía ningún correo. Indica un servidor SMTP para activar la recuperación de contraseña y las notificaciones.

Publicar Kimai en un dominio con HTTPS

1. 06

   Apuntar el DNS

   Crea un registro A para kimai.your-domain.com hacia la IP pública del VPS y comprueba la propagación con dig +short kimai.your-domain.com.

2. 07

   Configurar el proxy inverso

   El puerto 8001 solo escucha en 127.0.0.1, así que únicamente el proxy local puede alcanzarlo. Ejemplo de bloque Nginx:

   server {
       listen 80;
       server_name kimai.your-domain.com;
   
       location / {
           proxy_pass http://127.0.0.1:8001;
           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;
       }
   }

3. 08

   Obtener el certificado

   Con certbot y su plugin de Nginx, se emite el certificado de Let's Encrypt y el bloque server se completa para el puerto 443:

   apt install -y certbot python3-certbot-nginx
   certbot --nginx -d kimai.your-domain.com

4. 09

   Declarar el dominio en Kimai

   Añade kimai.your-domain.com a TRUSTED_HOSTS y ejecuta docker compose up -d para recrear el contenedor. Si los enlaces generados siguen en http://, consulta la documentación de Kimai sobre proxies inversos: las cabeceras X-Forwarded-* solo se tienen en cuenta si vienen de un proxy de confianza.

5. 10

   Cerrar lo que sobra

   En el cortafuegos abre solo los puertos 22, 80 y 443. MySQL no publica ningún puerto y no debe hacerlo.

Crear usuarios desde la línea de comandos

docker compose exec kimai /opt/kimai/bin/console kimai:user:create alice [email protected] ROLE_TEAMLEAD

El modelo de datos: clientes, proyectos, actividades

Tarifas y presupuestos

• Tarifa horaria — se define en el cliente, el proyecto, la actividad o el usuario; se aplica el nivel más específico a cada entrada.
• Tarifa fija — un importe cerrado por entrada, útil para un servicio facturado a precio fijo sea cual sea su duración.
• Tarifa interna — lo que realmente te cuesta una hora, separado del precio facturado, para medir la rentabilidad de cada proyecto.
• Presupuesto en tiempo o en dinero — en un cliente, proyecto o actividad, con un indicador visual de consumo.
• Presupuesto mensual o total — una bolsa de mantenimiento mensual se controla de forma distinta a un proyecto cerrado durante toda su vida.
• Sobrepasos — los paneles muestran cuánto presupuesto se ha consumido y un ajuste de configuración permite autorizar o bloquear las entradas que lo superen.

Roles, equipos y permisos

• ROLE_USER — registra y consulta sus propias horas en los proyectos a los que tiene acceso.
• ROLE_TEAMLEAD — ve y modifica las horas de los miembros de sus equipos y consulta sus informes.
• ROLE_ADMIN — gestiona clientes, proyectos, actividades, facturas y usuarios.
• ROLE_SUPER_ADMIN — acceso completo, incluida la configuración del sistema y los permisos.

Facturar a partir de los partes de horas

Preparar tu primera plantilla de factura

1. 11

   Crear la plantilla

   En Facturas → Plantillas, indica el emisor, la dirección, los datos bancarios, el plazo de pago y el texto del pie.

2. 12

   Elegir el formato de salida

   Selecciona un formato PDF o HTML para un documento listo para enviar, o un formato ofimático si terminas la factura en otra herramienta.

3. 13

   Definir la numeración

   Configura el formato del número de factura (prefijo, año, contador) para obtener una secuencia continua acorde con tu contabilidad.

4. 14

   Configurar el impuesto

   Introduce el tipo impositivo aplicable en la plantilla; crea una plantilla por régimen si facturas a clientes con tipos distintos.

API REST e integraciones

curl -s -H "Authorization: Bearer TU_TOKEN" \
  https://kimai.your-domain.com/api/timesheets

Ampliar Kimai con plugins

docker compose cp NombreDelPluginBundle kimai:/opt/kimai/var/plugins/
docker compose exec kimai /opt/kimai/bin/console kimai:reload --env=prod

Copia de seguridad y restauración

docker compose exec -T db sh -c 'exec mysqldump --single-transaction -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' > kimai-$(date +%F).sql
docker run --rm -v kimai_kimai_data:/data -v "$PWD":/backup alpine tar czf /backup/kimai_data-$(date +%F).tgz -C /data .

docker compose exec -T db sh -c 'exec mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < kimai-AAAA-MM-DD.sql

Actualizaciones sin sorpresas

• Primero, la copia — un volcado justo antes de actualizar permite volver atrás si falla una migración.
• Actualizar la imagen — docker compose pull kimai && docker compose up -d kimai, y después sigue docker compose logs -f kimai. Al arrancar, el contenedor aplica las migraciones de base de datos automáticamente.
• Fijar una versión — en producción, sustituye apache-latest por una etiqueta versionada de la imagen para decidir cuándo subir de versión.
• Leer las notas de versión — algunas versiones mayores cambian requisitos o el comportamiento de los plugins.
• Exportar con regularidad — la exportación CSV o XLSX de los partes de horas es una copia legible, útil para una auditoría o una migración.

Resolución de problemas habituales

• «Untrusted Host» o error 400 tras añadir un dominio — falta el nombre de host en TRUSTED_HOSTS. Añádelo y recrea el contenedor.
• Error 500 y «Permission denied» en var/ — suele aparecer tras un comando de consola ejecutado con un usuario distinto al del servidor web. Restablece la propiedad con docker compose exec kimai chown -R www-data:www-data /opt/kimai/var y después kimai:reload.
• Un cambio de configuración no surte efecto — la caché de Symfony sirve la versión anterior: docker compose exec kimai /opt/kimai/bin/console kimai:reload --env=prod.
• Kimai se reinicia en bucle en el primer arranque — la base no está lista o DATABASE_URL es incorrecta. Revisa el healthcheck de db y las credenciales del .env.
• Enlaces en http:// detrás del proxy HTTPS — las cabeceras X-Forwarded-Proto no se envían o no se consideran de confianza; revisa la configuración del proxy.
• Contraseña olvidada sin correo configurado — MAILER_URL apunta a null://: restablece la contraseña desde una cuenta de administrador o crea un nuevo administrador por consola.

Kimai frente a Toggl Track, Clockify y Harvest

Desplace la tabla

Dimensionar el VPS