Activar soporte de shell + Composer en un hosting y instalar paquetes PHP con Core-Admin

soporte.aspl · 2026-05-26 12:38:20 UTC

Introducción

Muchas aplicaciones y librerías PHP modernas (Laravel, Symfony, librerías de facturación electrónica, integraciones con APIs, etc.) se distribuyen como paquetes Composer, el gestor de dependencias estándar de PHP. Para poder instalarlas en un hosting gestionado por Core-Admin necesitas dos cosas:

Acceso a una shell con el usuario propietario del hosting (no como root, para no romper permisos).
Composer disponible y configurado con el motor PHP correcto del hosting.

Core-Admin permite activar ambas cosas con un único comando del módulo Webhosting Management: crad-webhosting-mgr.pyc --enable-php-composer. Una vez activado, el usuario del hosting dispone de un loader que abre una shell con el entorno preparado para usar composer apuntando al PHP correcto del sitio.

En este artículo se explica:

Cómo activar el soporte de shell + Composer para un hosting.
Cómo entrar en la shell del usuario del hosting.
Cómo instalar un paquete Composer cualquiera, usando como ejemplo práctico la librería josemmo/verifactu-php para el sistema Verifactu de la AEAT.

El mismo procedimiento sirve para cualquier otra librería PHP que se instale vía Composer (Stripe, PHPMailer, Guzzle, integraciones de pasarelas de pago, etc.).

Requisitos previos

Core-Admin instalado con el módulo Webhosting Management activo.
Acceso de root al servidor donde está alojado el hosting.
Un hosting ya creado en Core-Admin con su motor PHP asignado (por ejemplo PHP 8.3).
Conexión a internet en el servidor (para descargar el instalador oficial de Composer desde getcomposer.org).

Activación del soporte Composer

Comando

Desde una shell de root, ejecuta:

crad-webhosting-mgr.pyc --enable-php-composer dev.example.com

Sustituye dev.example.com por el nombre del hosting que quieras habilitar.

Qué hace el comando

La operación realiza varias acciones de forma automática:

Descarga el instalador oficial de Composer desde https://getcomposer.org/installer.
Instala Composer en /usr/core-admin/composer/<version>/composer (cacheado para no re-descargar en sucesivas activaciones).
Crea el fichero composer-loader.py dentro del directorio raíz del hosting (/var/webs/<hosting>/).
Crea un alias composer-loader.sh apuntando al .py anterior.
Añade el usuario del hosting al grupo adm2, que es el grupo que permite tener una shell interactiva en el sistema (los usuarios de hosting están bloqueados por defecto).

Ejemplo de salida:

INFO: enable_php_composer: running installer /root/core-admin-XXXXXXXX.sh
INFO: enable_php_composer: status=0 | Composer (version 2.8.12) successfully installed
INFO: enable_php_composer: status=0 |   to: /usr/core-admin/composer/2.8.12/composer
INFO: ensuring [chmod +x /var/webs/dev.example.com/composer-loader.py]
INFO: ensuring [rm -f /var/webs/dev.example.com/composer-loader.sh]
INFO: ensuring [ln -s /var/webs/.../composer-loader.py /var/webs/.../composer-loader.sh]
INFO: ensuring [adduser devexamplecom adm2]
INFO: Operation completed: Composer loader installed at: /var/webs/dev.example.com/composer-loader.py

Nota: el comando es idempotente. Puedes ejecutarlo varias veces sobre el mismo hosting sin efectos secundarios — si Composer ya está instalado, se reutiliza la versión cacheada.

Entrar en la shell del hosting

Una vez activado el soporte, puedes obtener una shell interactiva con el usuario del hosting de dos formas.

Opción A: vía `su -` desde root

su - devexamplecom

El nombre de usuario sigue la convención de Core-Admin: el nombre del hosting sin puntos. Por ejemplo:

Hosting	Usuario del sistema
`cliente.example.com`	`clienteexamplecom`
`dev.example.com`	`devexamplecom`
`tienda.example.com`	`tiendaexamplecom`

Opción B: vía el loader de Composer (recomendado)

Desde root, lanza directamente el loader:

/var/webs/dev.example.com/composer-loader.sh

El loader hace tres cosas:

Cambia al usuario propietario del hosting.
Configura el PATH para que la orden composer apunte al binario instalado en /usr/core-admin/composer/<version>/composer.
Configura el motor PHP correcto del hosting (por ejemplo /usr/core-admin/php/8.3/bin/php) para que Composer lo use al resolver dependencias y ejecutar scripts post-install.
Sitúa la shell en el directorio público del hosting (/var/webs/<hosting>/html).

Ejemplo de salida:

COMPOSER:
COMPOSER: Core-admin helper:
COMPOSER:       Hosting: dev.example.com
COMPOSER:   Root folder: /var/webs/dev.example.com
COMPOSER: Public folder: /var/webs/dev.example.com/html
COMPOSER:       Version: 2.8.12 (/usr/core-admin/composer/2.8.12/composer)
COMPOSER:
COMPOSER: Run:
COMPOSER: >> cd html ; composer --version ; pwd
COMPOSER:
devexamplecom@host:~/html$ composer --version
Composer version 2.8.12 2025-09-19 13:41:59
PHP version 8.3.6 (/usr/bin/php8.3)

Importante: usa el loader (composer-loader.sh) o el su - para entrar como usuario del hosting. No ejecutes composer directamente como root dentro del directorio del hosting — los ficheros quedarían con propietario root:root y el PHP-FPM del sitio no podría escribir en ellos (cachés, logs, autoload, etc.).

Ejemplo práctico: instalar Verifactu PHP

Verifactu PHP es una librería que implementa el sistema Verifactu de la AEAT (Agencia Tributaria) para emisores españoles, exigible para muchos contribuyentes a partir de 2026. La instalamos en el hosting de ejemplo.

Paso 1: entrar en el hosting

Desde root:

/var/webs/dev.example.com/composer-loader.sh

Quedas en /var/webs/dev.example.com/html como usuario devexamplecom.

Paso 2: comprobar que el motor PHP cumple los requisitos

Verifactu PHP requiere PHP 8.1 o superior y las extensiones dom, openssl y soap:

php -v
php -m | grep -iE 'soap|openssl|dom'

Salida esperada:

PHP 8.3.6 (cli) (built: ...)
dom
openssl
soap

Si falta alguna extensión, actívala desde el panel de Core-Admin en Webhosting Management → motor PHP → extensiones, o instálala a nivel de sistema con apt install php8.3-soap (ajusta a la versión que use el hosting).

Paso 3: instalar la librería

composer require josemmo/verifactu-php

Composer descargará el paquete josemmo/verifactu-php y sus dependencias (symfony/validator, josemmo/uxml, etc.) en vendor/, y creará/actualizará los ficheros composer.json y composer.lock en el directorio actual.

Salida resumida:

./composer.json has been updated
Running composer update josemmo/verifactu-php
  - Locking josemmo/verifactu-php (v0.3.4)
  - Locking symfony/validator (v7.4.10)
  - Locking josemmo/uxml (v0.2.0)
Writing lock file
Installing dependencies from lock file
  - Installing josemmo/verifactu-php (v0.3.4): Extracting archive
  ...
Generating optimized autoload files

Paso 4: usar la librería desde tu aplicación

Cualquier script PHP del hosting puede ahora cargar la librería incluyendo el autoload de Composer:

<?php
require_once __DIR__ . '/vendor/autoload.php';

use josemmo\Verifactu\\...;

// ... tu código ...

Paso 5 (opcional): auditoría de seguridad

Composer puede comprobar si alguna dependencia tiene avisos de seguridad publicados:

composer audit

Esto es útil tras cualquier composer require o composer update para confirmar que no se han introducido dependencias con vulnerabilidades conocidas.

Instalar otros paquetes PHP con el mismo flujo

El procedimiento es idéntico para cualquier otro paquete Composer. Solo cambia el nombre del paquete a instalar. Algunos ejemplos comunes en hostings gestionados con Core-Admin:

Paquete	Comando	Uso típico
`phpmailer/phpmailer`	`composer require phpmailer/phpmailer`	Envío de correos con SMTP autenticado
`guzzlehttp/guzzle`	`composer require guzzlehttp/guzzle`	Cliente HTTP para consumir APIs
`stripe/stripe-php`	`composer require stripe/stripe-php`	Integración con Stripe
`phpoffice/phpspreadsheet`	`composer require phpoffice/phpspreadsheet`	Generación de hojas de cálculo
`tecnickcom/tcpdf`	`composer require tecnickcom/tcpdf`	Generación de PDFs
`josemmo/verifactu-php`	`composer require josemmo/verifactu-php`	Verifactu AEAT

El flujo siempre es el mismo:

root activa el soporte: crad-webhosting-mgr.pyc --enable-php-composer <hosting>
root entra al hosting: /var/webs/<hosting>/composer-loader.sh
Como usuario del hosting: composer require <paquete>

Detalles técnicos

Dónde se almacenan los ficheros

Elemento	Ruta
Binario de Composer	`/usr/core-admin/composer/<version>/composer`
Loader del hosting (Python)	`/var/webs/<hosting>/composer-loader.py`
Loader del hosting (alias)	`/var/webs/<hosting>/composer-loader.sh`
`composer.json` y `composer.lock`	Donde el usuario lance `composer require` (normalmente `/var/webs/<hosting>/html/`)
Dependencias instaladas	`<directorio del proyecto>/vendor/`

Grupo `adm2`

Los usuarios de los hostings de Core-Admin tienen, por defecto, una shell de tipo nologin o false para impedir accesos interactivos. El comando --enable-php-composer añade el usuario al grupo adm2, que es el grupo del sistema que tiene asignada una shell real (/bin/bash).

Esto significa que activar el soporte Composer también habilita acceso shell vía su - para ese usuario. Es el comportamiento esperado: para ejecutar Composer hace falta una shell.

Idempotencia y reactivación

El comando --enable-php-composer puede ejecutarse tantas veces como se quiera sobre el mismo hosting. En sucesivas ejecuciones:

Si la versión de Composer en caché está vigente, se reutiliza (no se re-descarga).
El loader se vuelve a generar (sobrescribe los ficheros existentes).
Si el usuario ya pertenece al grupo adm2, adduser simplemente notifica que ya es miembro y no falla.

Actualizar Composer

Para forzar la descarga de una nueva versión de Composer cuando se publica una actualización mayor, basta con volver a ejecutar --enable-php-composer. El instalador descargará la última versión disponible desde getcomposer.org.

Preguntas frecuentes

P: ¿Puedo ejecutar composer directamente como root?
Técnicamente sí, pero no se recomienda. Los ficheros que Composer descarga (carpeta vendor/, composer.lock, cachés) quedarían con propietario root:root, y el PHP-FPM del hosting — que se ejecuta con el usuario del hosting — no podría escribir en ellos. Usa siempre el loader o su - al usuario del hosting.

P: ¿En qué directorio debo lanzar composer require?
Depende de la aplicación. Si estás integrando Composer en una aplicación PHP existente (por ejemplo, un proyecto Laravel ya instalado), lánzalo en el directorio raíz del proyecto, donde está composer.json. Si estás empezando desde cero, lo habitual es lanzarlo en /var/webs/<hosting>/html/ o en un subdirectorio dedicado dentro del hosting.

P: ¿Composer usa el PHP del sistema o el PHP del hosting?
El loader configura el PATH para que composer use el motor PHP asignado al hosting (por ejemplo /usr/core-admin/php/8.3/bin/php). Esto es importante: las versiones de las extensiones, los php.ini, y la versión de PHP detectada por Composer al resolver dependencias serán las del hosting, no las del sistema.

P: ¿Cómo desactivo el soporte Composer en un hosting?
Actualmente no hay un comando --disable-php-composer específico. Si necesitas revocar el acceso, puedes:

Quitar el usuario del grupo adm2: deluser <usuario> adm2
Eliminar el loader: rm /var/webs/<hosting>/composer-loader.py /var/webs/<hosting>/composer-loader.sh

P: ¿El loader funciona si el hosting está suspendido?
No. Si el hosting está suspendido en Core-Admin, el usuario del sistema queda bloqueado y su - fallará. Reactiva el hosting antes de usar Composer.

P: ¿Necesito reiniciar PHP-FPM tras instalar un paquete Composer?
No, salvo que el paquete instale extensiones PHP nativas (lo cual es poco habitual en paquetes Composer puros). El autoload de Composer se carga dinámicamente desde la aplicación, sin necesidad de reiniciar el servicio.

P: ¿Composer descarga los paquetes a través de la red del servidor?
Sí. El servidor necesita poder acceder a repo.packagist.org, getcomposer.org y a los repositorios Git de GitHub/GitLab que los paquetes referencien. Si el servidor está detrás de un proxy, configura las variables de entorno HTTP_PROXY y HTTPS_PROXY antes de ejecutar composer.