Instalación con Nginx y Docker

Este documento describe la instalación de Histrix con Nginx y MySQL usando Docker y Docker Compose. Es el procedimiento recomendado para instalaciones nuevas.

Primeros pasos

Instalación de Docker

Para instalar Docker puedes seguir los pasos de la documentación oficial. En este caso, se instalará Docker en Ubuntu 24.04 usando apt.

# Actualizar el índice de paquetes:
sudo apt-get update

# Instalar paquetes para permitir a apt usar un repositorio sobre HTTPS:
sudo apt-get install ca-certificates curl

# Agregar la clave GPG oficial de Docker:
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Agregar el repositorio de Docker a las fuentes de APT:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

# Instalar Docker:
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Verificar la instalación:
sudo docker --version

Rotación de logs de los contenedores

Sin límite de tamaño, los logs de los contenedores crecen hasta llenar el disco del servidor. El límite se declara en el docker-compose.yml, en cada servicio, y así queda versionado junto con el resto de la definición:

logging:
  driver: json-file
  options:
    max-size: "10m"
    max-file: "5"

Con eso cada contenedor guarda como máximo 5 archivos de 10 MB. El archivo completo del apartado Docker Compose de Histrix ya lo trae aplicado a los tres servicios mediante un bloque reutilizable.

Precaución

Poner log-driver y log-opts en /etc/docker/daemon.json no alcanza. Ese archivo fija únicamente el valor por omisión del daemon: solo afecta a los contenedores creados después del cambio —los que ya existen conservan su configuración aunque se reinicien— y cualquier bloque logging del compose lo sobrescribe. Declararlo en el compose es lo que efectivamente limita el tamaño.

Consejo

Para más información sobre el driver de logs, consultar la documentación oficial.

Configurar usuario del servicio

Como usario root, crear un usuario para el servicio de Histrix:

sudo adduser automata

le damos permisos de sudo:

sudo usermod -aG sudo automata

Le damos permisos de docker:

sudo usermod -aG docker automata

Instalación de Histrix

Para inicar tiene que entrar como usuario automata:

su - automata

Dentro del home del usuario automata tienes que generar la siguiente estructura de carpetas:

mkdir -p ~/[Nombre del cliente]/{modules,database}

Para continuar tienes que crear una api key de bitbucket con permisos de lectura y escritura de repositorios. En el siguiente enlace puedes crear una api key.

Teniendo la api key te mueves a la carpeta modules y clonas los modulos de histrix:

cd ~/[Nombre del cliente]/modules
git clone --depth 4 https://[nombre-usuario]:[api-key]@bitbucket.org/mundo-it/erp-full.git erp-full
git clone --depth 4 https://[nombre-usuario]:[api-key]@bitbucket.org/mundo-it/htxcore.git histrix

En la carpeta database tienes que clonar el repositorio de los xmls del cliente:

cd ~/[Nombre del cliente]/database
git clone --depth 4 https://[nombre-usuario]:[api-key]@bitbucket.org/mundo-it/[nombre-repositorio-xml].git

Configuración de Histrix

Histrix su configuracion va en la carpeta database con un archivo llamado config.xml que tiene la siguiente estructura:

<?xml version="1.0" encoding="UTF-8"?>
<sistema>
  <empresa>
    <img_fondo>histrix_back.jpg</img_fondo>
    <lang>es</lang>
  </empresa>
  <conexiones>
    <base id="[Nombre del ciente]" tipo="mysql" xmlPath="[Nombre de los xml del ciente]/">
      <descripcion>[Nombre del ciente]</descripcion>
      <base>[nombre de la base de dato]</base>
      <driver>mysql</driver>
      <user>[Usuario de la base de dato]</user>
      <password>[Contraseña de la base de dato]</password>
      <host>[url del servidor base de dato]</host>
      <empresa>
        <nombre>[Nombre del ciente]</nombre>
        <direccion>[Direccion del ciente]</direccion>
        <cuit>[Cuit del cliente]</cuit>
        <telefonos/>
        <logo_pdf_1 posx="6" width="30">logo.jpg</logo_pdf_1>
        <logo_ini>logo.png</logo_ini>
        <modulos>|clientes|proveedores|stock|iva|contabilidad|packs|vendedores|transportistas</modulos>
        <img_fondo/>
      </empresa>
    </base>
  </conexiones>
</sistema>

El atributo xmlPath de cada <base> define el directorio de sus XML (database/{xmlPath}/xml/) y, junto con el parámetro CONFIG::baseModule de la tabla HTXOPTIONS, determina cómo se resuelve cada archivo. Ver Arquitectura.

Actualización de una instalación anterior a mayo de 2026

Migrar una instalación previa exige dos cambios de schema que no se pueden aplicar desde la interfaz:

• HTXPROFILES.realm — sin esa columna el login devuelve 500 para todos los usuarios, incluido el administrador.
• HTXMENU.web_version = 1 — sin ese valor el menú aparece vacío y sin ningún error.

Con el sistema de migraciones instalado, ambos cambios se aplican con php histrix migrate --all-databases. Ver Migraciones de base.

Docker Compose de Histrix

Se crea un archivo docker-compose.yml en la raíz del usuario automata con el siguiente contenido:

# Política de logs compartida por los tres servicios
x-logging: &default-logging
  driver: json-file
  options:
    max-size: "10m"
    max-file: "5"

services:
  redis:
    image: redis:6.0.3-buster
    restart: unless-stopped
    container_name: redis
    logging: *default-logging
    expose:
      - "6379"
    command: "redis-server --appendonly yes"
    networks:
      - backend
  db:
    image: mysql:8.3.0
    command: --default-authentication-plugin=mysql_native_password --sql-mode="NO_ZERO_IN_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION"
    container_name: db
    volumes:
      - mysql-data:/var/lib/mysql
    restart: unless-stopped
    logging: *default-logging
    networks:
      - backend
    expose:
      - "3306"
    environment:
      MYSQL_ROOT_PASSWORD: [Contraseña de la base de dato]
      MYSQL_ROOT_HOST: '%'
      MYSQL_DATABASE: [nombre de la base de dato]
      TZ: America/Argentina/Buenos_Aires
  php:
    image: mundoit/histrix-runtime:nginx-06
    restart: unless-stopped
    container_name: histrix
    logging: *default-logging
    volumes:
      - "/home/automata/[nombre-cliente]/database:/var/www/html/database"
      - "/home/automata/[nombre-cliente]/modules:/var/www/html/modules"
    ports:
      - "80:80"
      # Solo si se va a usar el servidor de notificaciones:
      # - "8888:8888"
    depends_on:
      - redis
      - db
    environment:
      - REDIS_SERVER_HOST=redis
      - GIT_EMAIL=[Correo electronico del usuario de bitbucket]
      - GIT_NAME=[Nombre del usuario de bitbucket]
      - GIT_PERSONAL_TOKEN=[Api key de bitbucket]
      - GIT_USERNAME=[Nombre de usuario de bitbucket]
      - GIT_REPO=bitbucket.org/mundo-it/histrix.git
      - GIT_BRANCH=nginx-fpm
      - PGID=[ID del grupo de automata]
      - PUID=[ID del usuario de automata]
      - WEBROOT=/var/www/html
      - RUN_SCRIPTS=1
      - PHP_MEM_LIMIT=1024M
      - PHP_POST_MAX_SIZE=1024M
      - PHP_UPLOAD_MAX_FILESIZE=1024M
      - PHP_ERRORS_STDERR=1
      - SKIP_COMPOSER=1
      - REMOVE_FILES=0
      - ERRORS=0
    networks:
      - backend
      - frontend
    links:
      - db
volumes:
  mysql-data: # Donde se guarda la base de datos
networks:
  backend:
  frontend:

Nota

El compose necesita el ID del usuario y del grupo de automata:

id automata

# Salida
# uid=1000(automata) gid=1000(automata) groups=1000(automata),27(sudo),100(users),987(docker)

Puerto 8888

El 8888 es el puerto del servidor de notificaciones por WebSocket. Solo hay que exponerlo si se va a levantar el push server; en una instalación que no usa notificaciones en tiempo real, publicarlo no aporta nada y amplía la superficie expuesta. Ver Servidor de notificaciones.

Iniciar Histrix

docker compose up -d

Histrix queda escuchando en el puerto 80 de la máquina.

Precaución

Los cambios de logging en el compose se aplican al crear el contenedor, no al reiniciarlo. En una instalación que ya está corriendo hay que recrear los contenedores:

docker compose up -d --force-recreate

Para verificar que quedó aplicado:

docker inspect -f '{{.HostConfig.LogConfig}}' histrix

Consejo

Para más información sobre Docker Compose, consultar la documentación oficial.

Comandos útiles

Pull de cambios de Histrix

Para hacer un pull de los cambios de Histrix, se debe ejecutar el siguiente comando:

sudo docker exec -t -i histrix /usr/bin/pull

Pull de cambios de los modulos

Para hacer un pull de los cambios de los modulos de Histrix, se debe ejecutar el siguiente comando:

cd ~/[Nombre del cliente]/modules/erp-full
git pull
cd ~/[Nombre del cliente]/modules/histrix
git pull

Pull de cambios de los xmls

Para hacer un pull de los cambios de los xmls del cliente, se debe ejecutar el siguiente comando:

cd ~/[Nombre del cliente]/database/[nombre-repositorio-xml]
git pull

Ver logs de Histrix

Los logs se organizan por año y mes dentro del directorio de la base:

cd ~/[Nombre del cliente]/database/[nombre-repositorio-xml]/log/[año]/[mes]

# Consultas
tail -f sql_select.log

# Inserciones y actualizaciones
tail -f sql_update.log

El directorio del mes se crea al vuelo, así que necesita permiso de escritura para el proceso de PHP. Ver Problemas frecuentes.

Regenerar el mapa de clases

Necesario después de crear, mover o renombrar una clase de dataSource:

docker exec -it histrix composer dumpautoload

Aplicar migraciones

docker exec -it histrix php histrix migrate:status --all-databases
docker exec -it histrix php histrix migrate --all-databases

Limpiar el caché de assets

Cuando los bundles de JavaScript o CSS quedan con contenido inválido:

docker exec histrix sh -c 'rm -rf /tmp/histrix/*'

Los cambios en los XML no requieren limpiar nada: el motor los reparsea en cada request y se ven recargando la página.

Correr los tests

docker exec -it histrix vendor/bin/phpunit