Ir al contenido
JoeCMS Descargar 3.1.5
Manual · 14

Entornos, instalación y despliegue

Dónde están las configuraciones, qué cambia entre desarrollo y producción, cómo se pone en línea un cambio y cómo se empaqueta una versión.

1. Requisitos de funcionamiento

  • PHP ≥ 8.1 con mysqli, mbstring, json, curl, openssl (críticos) y gd (recomendada)
  • MySQL 8 / MariaDB, también con el sql_mode strict por defecto (ver 07). Puerto no estándar (Aiven, bases de datos gestionadas): FF_DATABASE_PORT en la config, que el asistente escribe solo, o bien host:porta en FF_DATABASE_HOST
  • Apache con mod_rewrite — el .htaccess es parte integrante de la arquitectura, no un accesorio: sin él, el front controller no recibe nada
  • permisos de escritura en themes/site/conf/, uploads/, cache/ y en la docroot (para el .htaccess)
  • exec() y shell_exec() no son necesarios: en los hostings que los incluyen en disable_functions (muchos compartidos, todos los gratuitos) el sitio funciona igualmente, porque la sintaxis de las cachés y de los jobs se comprueba con el analizador interno de PHP (vendor/wolfgan/filemanager/services/fs_php.php, vendor/hcore/jobs/Jobs.php). Sin ellos, solo faltan los programas externos: la vista previa de PDFs (convert de ImageMagick, sustituido por el icono genérico) y los optimizadores externos de imágenes, CSS y JS que ffMedia::optimize() usa si los encuentra (jpegoptim, optipng, cssnano, uglifyjs…). La protección está en ambas copias de ffMedia y ffThumb: los sitios instalados por el asistente cargan las de vendor/phpformsframework/, no ff/classes/
  • si hacen falta jobs: un programador (cron del panel, vía curl) — ver 05
  • si hace falta un worker: acceso shell y systemd — no todos los hostings compartidos lo permiten

2. Los dos archivos de configuración de entorno

themes/site/conf/config.local.php     desarrollo  (host que termina en .local)
themes/site/conf/config.remote.php    producción  (escrito por el instalador, chmod 0640)

Es HTTP_HOST quien decide cuál se carga. Ninguno de los dos está rastreado en git: en el repo solo están los .dist. Es aquí donde están los secretos — credenciales de BD, SMTP, JC_APP_SECRET, JC_AUTH_SALT, SENTRY_DSN, claves de los proveedores. Ver IGIENE_SEGRETI.md.

⚠️ JC_APP_SECRET y JC_AUTH_SALT son únicos por instalación (64 hex de random_bytes). Regenerar config.remote.php invalida las sesiones y hace ilegible todo lo que se ha cifrado con ese secreto. El archivo va en el backup, y no se regenera.

Constantes que un proyecto toca a menudo:

ConstanteEfecto
JC_SITE_DOMAINel dominio de la instalación, del que hook.php deriva DOMAIN_PROD y WWW_LINK (ver el recuadro en §3). Lo escribe el instalador
AREA_SEO_SHOW_MODIFY, AREA_PUBLISHING_SHOW_PREVIEW, MOD_SEC_PROFILING, MAX_UPLOADvalores que hook.php fija solo si el config no los ha definido ya (08 §4)
JC_REGISTRATION_ENABLEenciende/apaga el registro
JC_USER_AREA_PATHruta del área personal (/area-utente es solo un fallback)
ADMIN_TOOLBAR_HIDDENbarra de edición en el front-end (por defecto true = oculta)
AI_MD_ENABLEDversión Markdown de los contenidos para los LLM
MOD_AUTH_COOKIE_SECURE, MOD_AUTH_COOKIE_SAMESITEcookie de sesión (08 §6)
SENTRY_DSNseguimiento de errores (13 §4)
AUTH_2FAsegundo factor en el login: '' apagado, email o sms (08 §5bis). El instalador la escribe vacía
DEBUG_MODE, DISABLE_CACHE, CACHE_LAST_VERSIONcaché de los recursos (12)

3. Primera instalación: el asistente

La guarda está en config.php: si el host no termina en .local y falta config.remote.php, incluye install/index.php y sale. La sola presencia del config desactiva el asistente.

Diez pasos: requirements → database → application → billing → localization → admin → registration → layout → services → done. El detalle está en PANORAMICA_JOECMS.md §7 y en INSTALLER_PIANO.md.

Las partes que cuentan en la práctica:

  • Interfaz en cuatro idiomas (IT, EN, ES, FR). Todos los textos del asistente, mensajes de error incluidos, están en el diccionario de install/i18n.php y se leen con jc_t('chiave', …) (marcadores sprintf); también install/lib.php, install/icons.php e install/cleanup.php pasan por ahí. En la primera visita el idioma viene de Accept-Language (el soportado con la q más alta; inglés si no hay ninguno), y luego se queda en la sesión y en la cookie jc_install_lang. El selector de arriba a la derecha abre ?step=<step>&lang=xx: el controlador guarda la elección y redirige sin el parámetro, así los POST siguientes no repiten el cambio (los datos no enviados del formulario actual se pierden). El idioma del instalador es el idioma predeterminado del sitio: hasta que se envía el paso localization es también el único activo; después, cambiar de idioma mueve el predeterminado y lo añade a los elegidos. El paso localization tiene la última palabra. El idioma también es el valor por defecto de la zona horaria y el país. Una cadena nueva se añade al diccionario en los cuatro idiomas, con los mismos marcadores.
  • CREATE DATABASE con fallback elegante: si el hosting lo deniega, el asistente dice "créala desde el panel" y reintenta solo la conexión. Degrada, no se bloquea.
  • Envío de email de prueba durante la instalación: el correo se verifica antes de terminar. El Cifrado se elige en pareja con el puerto — SSL/TLS con 465, STARTTLS con 587, ninguno con 25 — y es el mismo valor que acaba en A_SMTP_SECURE: una pareja equivocada da un timeout, y el error sugiere la correcta. La contraseña dejada vacía conserva la ya introducida.
  • Paso services: consentimiento de cookies, Sentry y las credenciales de los proveedores de notificación — JoeSMTP y Twilio para los SMS (con el remitente, sin el cual no salen), OneSignal para el push. Acaban en el área Servicios, no en el config; se pueden dejar vacías e introducir después (06 §4).
  • .htaccess generado a partir del dominio del asistente (jc_write_htaccess()), con el dominio introducido en todas las condiciones HTTP_HOST (puntos escapados, www. y desnudo, subdominios media./static., CORS, caché estática), ancladas por ambos lados para que las del host principal no valgan también para media. (11 §5). Sin dominio conocido → ningún vínculo HTTP_HOST, así el sitio sigue siendo alcanzable.
  • Archivos internos cerrados al navegador: justo después de la redirección HTTPS el .htaccess responde 404 a los PHP (y a .sql, .log, .sh, .ini, .lock…) de library/, vendor/, ff/, conf/, applets/, contents/, cache/, uploads/, migrations/, a todo cache/logs/ y, en la raíz, a database.sql y a los .md. Apache sirve por su cuenta cada archivo que existe (index.php entra en juego solo para los demás): hasta la 3.1.0 cualquiera descargaba los logs del CMS y el dump, y ejecutaba los PHP que el CMS solo incluye. Siguen abiertos los archivos estáticos (CKEditor está en vendor/), cm/ (showfiles.php, static.php, error.php son direcciones reales), themes/ (kcfinder) y modules/: cada módulo se protege por sí mismo, porque el Package Manager abre /modules/<id>/installer/wizard.php. La condición sobre REDIRECT_STATUS deja pasar las reescrituras internas (/static → cm/static.php, el ErrorDocument).
  • Endurecimiento: install.lock, chmod 0640 en el config, install/cleanup.php (solo POST, solo si el config existe) que borra recursivamente /install.

⚠️ El .htaccess no viaja en el ZIP. El archivo rastreado en git contenía los dominios de desarrollo, y la guarda "no sobrescribo si existe" lo dejaba intacto → sitio muerto. Lo genera el instalador.

⚠️ Las constantes del dominio se leen siempre con defined(). hook.php define WWW_LINK, WWW_LINK_ABSOLUTE, DOMAIN_PROD y LOCAL_DOMAIN en toda condición, con la comparación del host tolerante con el prefijo www. y el puerto. Las instalaciones viejas las definían dentro de un switch ($_SERVER["HTTP_HOST"]): servido en un host distinto del listado no definían nada, y en PHP 8 leer una constante inexistente es un Error fatal — página en blanco, ya no el warning con fallback al nombre de PHP 7. Como en un sitio hook.php puede ser más viejo que el código que lo lee, el CMS nunca lo da por supuesto: library/gallery/common/set_header_page.php pasa por set_header_page_is_canonical_host() y por la guarda defined("DOMAIN_PROD"). La misma regla vale para los applets y para el código del sitio.

⚠️ El dominio está en el config, no en hook.php. El instalador escribe define('JC_SITE_DOMAIN', 'esempio.it') en config.remote.php, y hook.php lo lee de allí; sin él, se asume producción y los enlaces se construyen a partir del host de la petición (en un staging, sin noindex). Hasta la 3.0.3 el instalador lo escribía dentro de hook.php en lugar del marcador [DOMINIO], y cada actualización, que sustituye hook.php, lo borraba. hook.php es ahora todo de la plataforma: lo que es del sitio está en el config (valores) y en hook.local.php (código), que la actualización no toca (10 §1). Con un deploy manual, la línea JC_SITE_DOMAIN se añade al config antes de subir el nuevo hook.php.

4. Despliegue: poner en línea la rama activa

Regenerar el paquete en cada corrección es demasiado lento, y la subida de archivos sueltos desde el cliente FTP es la forma más eficaz de romper un sitio en producción: en producción queda una mezcla de versiones — hook.php viejo con un módulo nuevo da Fatal error — y esa combinación no existe en ningún commit, así que no se reproduce en local.

El CMS trae la herramienta que evita todo esto: bin/deploy.sh, que sube por SSH el HEAD de la rama git en la que estás, y solo los archivos cambiados desde el último despliegue.

cp bin/deploy.conf.example bin/deploy.conf    # una vez por instalación
./bin/deploy.sh controlla                     # quién soy en el servidor, dónde está la docroot, en qué commit
./bin/deploy.sh                               # prueba en vacío: lista lo que subiría
./bin/deploy.sh --vai                         # sube de verdad

La primera vuelta, en un sitio nacido del asistente o de subidas manuales, debe hacerse completa — no corresponde a ningún commit, y el incremental no sabría desde dónde partir:

./bin/deploy.sh --vai --completo --svuota-cache

Si la shell responde permission denied: ./bin/deploy.sh, el archivo ha perdido el permiso de ejecución (ocurre al copiarlo a mano, desde un cliente FTP, desde Windows o en un repositorio con core.fileMode=false, o en un proyecto nuevo nacido copiando los archivos de cms). Se lanza una vez con bash: el script se da cuenta de que ha perdido el bit, lo vuelve a poner en disco y en el índice de git, y a partir de ahí basta un commit para que no se pierda más en el próximo checkout:

bash bin/deploy.sh controlla
git commit -m "bin/deploy.sh ejecutable" bin/deploy.sh

Cómo sabe desde dónde retomar

Al final del despliegue escribe el commit en el servidor en $HOME/.joecms-deploy-rev-<sitio>: en la home del usuario SSH, no en la docroot, porque no debe ser accesible desde la web. El sufijo con el nombre del sitio sirve cuando en el mismo servidor, con el mismo usuario (a menudo root), hay varias instalaciones: con un solo archivo cada despliegue retomaría desde el commit de otro sitio.

Se despliega siempre el HEAD: los archivos modificados y sin commit no salen, y tampoco los nunca añadidos a git — el script los lista antes de moverse, y si has pedido --vai con el working tree sucio se detiene.

Configuración

Está en bin/deploy.conf, que está fuera de git: es por instalación y por máquina. En el repo solo está bin/deploy.conf.example.

Un sitio con varios entornos (producción, staging) tiene un archivo para cada uno, bin/deploy.<entorno>.conf, y lo elige con --ambiente:

./bin/deploy.sh --vai                         # bin/deploy.conf
./bin/deploy.sh --ambiente produzione --vai   # bin/deploy.produzione.conf

Con --ambiente el archivo debe existir: el script no recurre a bin/deploy.conf, lo que significaría desplegar en el entorno equivocado. Conviene que el archivo por defecto sea el staging, así a la producción se llega solo pidiéndola por su nombre.

ClavePara qué sirve
DEPLOY_HOST, DEPLOY_USER, DEPLOY_PORTconexión SSH; host y usuario obligatorios
DEPLOY_ROOTdocroot vista desde SSH — el mismo valor que FF_DISK_PATH en config.remote.php
DEPLOY_CHOWN'usuario:grupo' del sitio, obligatoria si entras como root
DEPLOY_PHPel PHP CLI del contenedor del sitio, para el control de versión final
DEPLOY_URL, DEPLOY_SMOKEsmoke test HTTP de fin de despliegue; en un sitio multilingüe, una página por idioma

⚠️ Despliegue como root sin DEPLOY_CHOWN: los archivos subidos quedan de root y con suexec o suPHP el sitio responde 500 a todo. El script se niega a arrancar, y el aviso no se puede eludir con --forza. ./bin/deploy.sh controlla muestra el propietario correcto.

Las opciones

OpciónEfecto
controlladiagnóstico: usuario, docroot encontrada sola, binarios PHP con mysqli/mbstring, permisos de cache/ y uploads/, commit registrado
(ninguna)prueba en vacío — no toca el servidor
--vaiejecuta
--completotodos los archivos versionados del HEAD (primer despliegue, o realineación)
--rimuoviborra del servidor los archivos eliminados del repo (sin ella, se quedan donde están)
--svuota-cachevacía cache/ en el servidor, conservando cache/logs/ y cache/.thumbs/
--da <sha>parte de un commit indicado a mano en lugar del registrado
--solo <path>limita a un subárbol
--forzacontinúa con el working tree sucio
--niente-smokesalta la verificación HTTP final

Qué no viaja, y por qué

ExcluidoPor qué
themes/*/conf/config.remote.php, config.local.phpcredenciales de BD y JC_APP_SECRET: se tocan a mano en el servidor
.htaccess de la raízen producción es el generado por el instalador con el dominio real; sobrescribirlo con el de desarrollo apaga el sitio
install/el instalador ya ha sido eliminado por install/cleanup.php: volver a ponerlo en línea es solo superficie de más
database.sqlel esquema nunca se aplica copiando archivos
cache/contenido generado por el sitio
docs/, tests/, *.md de trabajo, .idea/, .claude/, .githooks/material de desarrollo; docs/sql publicado sería una invitación a leerse las migraciones
modules/*/tests/las pruebas de los módulos: destructivas con la base de datos que se les pasa, y en el servidor no sirven

Cuando una de estas cosas cambia y la modificación debe llegar de todos modos a producción, el script lo dice en lugar de subirla a escondidas: lista las migraciones de docs/sql/ recordando que hay que aplicarlas antes del código (el código nuevo sobre esquema viejo hace SHOW COLUMNS y se apaga solo; el código viejo sobre esquema nuevo no), las define() nuevas aparecidas en config.remote.php.dist, y los cambios al .htaccess.

La caché

Plantillas, contenidos y recursos pasan por la caché en disco: recién subidos, el sitio sigue sirviendo la versión vieja. Si el despliegue toca applets/, contents/ o themes/<tema>/{layouts,contents,css,javascript} el script lo señala y se añade --svuota-cache, que limpia cache/ dejando cache/logs/ (el diario de errores, lo primero que mirar si algo se ha roto) y sin volver a crear la carpeta, así los permisos siguen siendo los buenos. Deja también cache/.thumbs/, las copias de las imágenes que media.<dominio> sirve tal cual: borrarlas todas a la vez es una oleada de regeneraciones, y con un .htaccess que manda a index.php también las peticiones de media. son 500 en cada imagen (11 §5). En un sitio multilingüe aquí está también cache/locale.php, la instantánea de los idiomas activos.

⚠️ Con opcache.revalidate_freq alto en el servidor la caché se vacía después, no enseguida. PHP vuelve a comprobar la fecha de un archivo ya compilado como mucho cada revalidate_freq segundos (por defecto 2): con un valor como 60, en el primer minuto tras la subida puede seguir ejecutando la versión vieja de un archivo usado hace poco, mientras que las plantillas ya las lee nuevas del disco. Las páginas regeneradas en ese minuto — también por la verificación final del script — salen con el código viejo, o con la plantilla nueva y el PHP viejo, y la caché de página las guarda durante horas. Con un valor alto se vacía cache/ a mano cuando ha pasado ese tiempo (el script, si no hay nada que subir, termina sin tocarla), o se reinicia el PHP-FPM del sitio antes de vaciarla.

Las correcciones al .htaccess generado (por el asistente, jc_write_htaccess() en install/lib.php, o por la plantilla del antiguo instalador, conf/gallery/install/.htaccess-cms.tpl) no llegan a los sitios ya instalados, porque ese archivo no viaja: hay que llevarlas a mano, como para el subdominio media. (11 §5). Después de la 3.1.0 son dos: el bloque de los archivos internos (§3) y ExpiresByType text/html "access plus 0 seconds" (12); las líneas exactas están en jc_write_htaccess() y jc_htaccess_static_tail(), y desde la 3.1.1 también en las tres plantillas conf/gallery/install/.htaccess-*.tpl del antiguo instalador.

La verificación final

El smoke test se ejecuta desde tu ordenador, no desde el servidor: llama a las rutas por HTTP como haría un navegador, y es el control que intercepta el archivo olvidado. Con DEPLOY_SMOKE se listan las rutas; en un sitio multilingüe se pone una por idioma, y así es como se descubre el idioma que se ha quedado atrás. Si el proyecto tiene tests/run.php con tests/smoke.config.php, el script usa esa suite en lugar de las llamadas curl.

Lo que queda a mano

Migraciones SQL, constantes nuevas en config.remote.php, .htaccess, cron del panel.

Una instalación con esquema < 4 debe alinearse una vez, antes de subir el código de la 1.6.0: el código nuevo escribe NULL en las fechas vacías, que un esquema 3 rechaza incluso en un servidor no strict (#1048), mientras que el esquema 4 también soporta el código 1.5.x. Se sube solo bin/db-allinea-schema.php, se lanza en una prueba en vacío y luego con --vai, y solo después se hace el despliegue. Para ese archivo sirve scp, no deploy.sh --solo: registra como subido todo el HEAD, y el despliegue siguiente no traería el resto.

Y, solo la primera vez, los permisos de las carpetas con escritura:

chmod -R 775 cache uploads && find cache uploads -type d -exec chmod g+s {} +

bin/ no debe ser accesible desde la web: en el paquete está bin/.htaccess con Require all denied. En nginx la regla debe replicarse en la configuración del servidor.

5. Paquete y versiones

./build-zip.sh [versión]      # → joecms-<versión>.zip

Empaqueta los archivos rastreados por git en el estado del working tree (no git archive, que ignoraría los cambios sin commit), y excluye: config de entorno (quedan los .dist), .htaccess de desarrollo, docs/ (salvo el manual), los *.md de la raíz, los hooks de desarrollo (.githooks/, .claude/), los source maps, los directorios de test/doc/example de los vendors. Vacía cache/ y de uploads/ conserva solo loghi.

Excepciones a la regla "nada de markdown": CHANGELOG.md y docs/manuale/ (desde la 1.3.0), que viajan con el paquete.

Excepción a la regla "nada de scripts shell": bin/ — deploy.sh y deploy.conf.example — viaja también. Es con eso con lo que el sitio recién instalado se actualiza a partir de entonces (§4), y bin/.htaccess lo mantiene fuera de la web. Las verificaciones de fin de build comprueban su presencia, y buscan los otros .sh, que en la docroot no pintan nada.

El script verifica por sí mismo que no acaben secretos en el paquete y que seed, instalador, changelog y capítulos del manual estén presentes.

El manual en el paquete es una instantánea

El manual que llega a un sitio describe la versión instalada en ese sitio y no se actualiza cuando el CMS principal avanza: la versión siguiente trae el suyo. La build:

  • antepone a cada capítulo una línea con versión y fecha del paquete;
  • añade docs/manuale/VERSIONE.txt (versión, fecha, commit de origen);
  • pone los archivos en solo lectura;
  • escribe docs/.htaccess con Require all denied: el manual describe el interior de la plataforma (rutas, trampas) y no debe servirse al público. Se lee desde el ZIP o vía FTP/panel. En nginx la regla debe replicarse en la configuración del servidor.

El manual se actualiza con el código (solo en el repo principal)

En el repositorio del CMS el manual sigue al código automáticamente. .githooks/manuale-check.sh compara los archivos modificados con las rutas que cada capítulo cita entre backticks — el mapa archivo → capítulo no está escrito a mano, se obtiene del propio manual — y lista los capítulos tocados pero no actualizados.

Punto de controlQué hace
Hook Stop de Claude Code (.claude/settings.json)al final del turno, si hay capítulos que revisar, detiene el cierre y hace actualizar el manual; cada pareja capítulo/archivo se señala una vez por contenido (.git/manuale-ack)
Hook git pre-commit (.githooks/pre-commit)sobre los archivos en stage bloquea una vez por pareja capítulo/archivo y contenido (.git/manuale-ack-commit): si el manual no hay que tocarlo, basta con repetir el mismo commit. MANUALE_WARN_ONLY=1 lo reduce a un aviso
A mano.githooks/manuale-check.sh sobre el working tree; --commit <sha> sobre un commit ya hecho

El hook git debe activarse una vez por clon: git config core.hooksPath .githooks. Para mantener fiable el mapa, en los capítulos los archivos se citan por ruta, entre backticks. El número de línea pegado (library/gallery/system/cache.php:957) se tolera. Dos reglas fijas completan el mapa: las migraciones de docs/sql/ van al capítulo 07, y hook.php, citado en casi todos los capítulos, cuenta para un capítulo solo si el cambio toca una función que ese capítulo nombra (por ejemplo registerUser()).

⚠️ El control protege solo los cambios que pasan por él. El hook Stop ve solo los cambios sin commit de una sesión de Claude Code en este repositorio. El pre-commit bloquea en lugar de limitarse a avisar porque los clientes gráficos (Sourcetree, PhpStorm) muestran la salida de un hook solo cuando falla: mientras se limitaba a avisar, un trabajo traído de otro proyecto y commiteado enseguida (pasó con la preferencia de idioma) llegó sin manual y sin que nadie lo viera. Un commit hecho con Bypass commit hooks en Sourcetree, o con --no-verify, salta el control: en ese caso se lanza después .githooks/manuale-check.sh --commit <sha>.

Versionado

ConstanteDóndeCuándo se incrementa
JC_VERSIONinstall/lib.phpcon cada paquete
JC_SCHEMA_VERSIONinstall/lib.phpcada vez que cambia database.sql

Los cambios se anotan en CHANGELOG.md bajo [Sin publicar] sobre la marcha, y se convierten en la sección de la versión cuando se crea el paquete (build-zip.sh avisa si falta la sección de la versión en build).

El esquema en el CHANGELOG: qué lee joecms.it

La página de descarga y el changelog de joecms.it deducen del CHANGELOG.md del paquete si una versión cambia el esquema de la base de datos, y en ese caso avisan de que antes del código hay que aplicar las migraciones. Para el sitio, el esquema de una versión es el primer número en negrita (una cifra) a menos de 40 caracteres de la palabra "schema", buscado en el resumen y después en el encabezado; una versión sin número hereda el de la anterior; una versión cambia el esquema si tiene el grupo ### Schema o un número distinto del de la anterior. Por eso la sección de una versión:

  • lleva en el encabezado ## [X.Y.Z] — AAAA-MM-DD · schema **N**, con N = JC_SCHEMA_VERSION;
  • tiene el grupo ### Schema solo si N ha cambiado: qué cambia, la migración de docs/sql/ y el orden, primero el esquema y luego el código (§4);
  • en el resumen no nombra en negrita otro esquema antes de N, porque el sitio leería ese.

Lo comprueba .githooks/changelog-schema.php, que lee la sección como el sitio y la compara con JC_SCHEMA_VERSION, con el esquema de la versión anterior (el de install/lib.php en el commit que llevó JC_VERSION a ese número) y con database.sql, sin líneas vacías ni comentarios --. build-zip.sh se detiene si no cuadra. El pre-commit hace la misma comprobación en el commit de versión, es decir el que cambia JC_VERSION, y no en los demás: durante el desarrollo JC_SCHEMA_VERSION puede subir ya mientras la sección de la versión actual declara todavía el esquema con el que salió. A mano: php .githooks/changelog-schema.php [versión], o --commit <sha> sobre un commit ya hecho.

⚠️ El número tiene una cifra porque así lo lee JoeSitoChangelog::versione() en el proyecto del sitio: el esquema 10 hay que enseñárselo antes al sitio, y hasta entonces la build se detiene. En la historia la regla se saltó una vez: la 1.0.5 añadió a database.sql las filas de ff_international de los textos de logout y registro, dejando el esquema en 2.

Actualizaciones automáticas y migraciones (desde la v3.0.2)

JoeCMS incluye un motor integrado (library/updater/JoeCmsUpdater.php) para actualizar sitios ya en producción de forma automática, segura y no destructiva.

  • CLI (bin/update.php):
    • php bin/update.php --status: diagnóstico del entorno y estado de las migraciones
    • php bin/update.php --file <pacchetto.zip> [--vai]: ejecuta la actualización desde un archivo ZIP
    • php bin/update.php --migrations-only [--vai]: ejecuta solo las migraciones de BD pendientes
    • php bin/update.php --maintenance on|off: activa/desactiva el modo de mantenimiento
  • Backend web (/restricted/updater):
    • Gestión en conf/gallery/manage/updater/index.php, con estado de salud, carga de ZIP, consola de registro en tiempo real y alineación de la base de datos.
  • Sistema de migraciones (migrations/):
    • Migraciones secuenciales .sql o .php (base schema_0004_v302_baseline.php).
    • Seguimiento automático en la tabla jc_migrations, gestionado por MigrationsRunner.
    • schema_0005_testi_multilingua.php (esquema 5) lleva al diccionario los textos del banner de cookies, de los correos de la cuenta y de la recuperación de contraseña: mientras falte, esos textos salen como códigos (svc_cookie_title). El updater la ejecuta solo en la misma operación, con el sitio en mantenimiento. Con un deploy manual se sube primero el archivo de la migración, se ejecutan las migraciones (php bin/update.php --migrations-only --vai, o las migraciones pendientes en /restricted/updater, conf/gallery/manage/updater/index.php) y solo después el resto del código.
  • hook.php y hook.local.php (library/updater/JoeCmsUpdater.php):
    • hook.php es de la plataforma y la actualización lo sustituye; antes, la copia de seguridad guarda una copia, así una restauración lo devuelve junto con el resto.
    • hook.local.php, el código del sitio, está en la lista protegida (con el config, .htaccess, uploads/) y build-zip.sh lo quita del paquete. También están protegidos los archivos PWA que el instalador genera para el sitio (manifest.json, site.webmanifest, browserconfig.xml): en el paquete de actualización manifest.json es el archivo de metadatos, y hasta la 3.0.3 acababa en lugar del manifiesto del sitio.
    • Una sola vez, antes de extraer los archivos: si el config no tiene JC_SITE_DOMAIN y el antiguo hook.php tiene un dominio escrito ($jc_site_domain = "…"), el updater lo copia en el config.
  • Modo de mantenimiento (.maintenance):
    • Gestionado por cm/maintenance.php al principio de index.php. Responde 503 Service Unavailable, con token de bypass para el administrador.
    • Textos en el idioma del visitante (prefijo de la dirección o navegador) y exit tras la página, ver 13 §1bis.
  • Dos paquetes de build (build-zip.sh):
    • joecms-<versione>.zip: paquete completo que descomprimir para una instalación nueva.
    • joecms-update-<versione>.zip: paquete ligero con manifest.json, sin instalador ni dumps destructivos, que conserva siempre config.remote.php, uploads/, cache/ y .htaccess.

6. Checklist de puesta en línea

  • [ ] migraciones aplicadas y reflejadas en database.sql, JC_SCHEMA_VERSION incrementada
  • [ ] lint PHP limpio en todos los archivos tocados
  • [ ] marcadores de las plantillas verificados (ninguno con espacios, ninguno perdido)
  • [ ] routing_table.xml modificados efectivamente subidos (no dan error: simplemente no pasa nada)
  • [ ] subida hecha con ./bin/deploy.sh --vai, no a mano (nada de mezcla de versiones)
  • [ ] cache/ vaciada tras la subida (--svuota-cache)
  • [ ] cron programados y verificados (una línea en el log para cada uno)
  • [ ] webhooks configurados en los proveedores, con el secret correcto
  • [ ] email: envío de prueba real, no solo la vista previa
  • [ ] robots.txt, sitemap.xml, canonical: coherentes con el dominio de producción
  • [ ] ?__debug__ no deja filtrar nada a un usuario cualquiera (cerrado por defecto: ningún SetEnv JC_DEBUG_ALLOWED 1 que se haya quedado encendido, ver 13 §2)
  • [ ] CHANGELOG.md actualizado
  • [ ] capítulos de docs/manuale/ alineados (.githooks/manuale-check.sh no señala nada)

7. Documentos "vivos" del repo

El conocimiento está junto al código, no en los tickets. Deben actualizarse con cada intervención:

ArchivoÁmbito
MIGRAZIONE_PHP7_PHP8.mdmigración y casuística PHP 8
FIX_FUNZIONAMENTO.mdcorrecciones que cambian el comportamiento
MIGLIORIE_ESTETICHE.mdintervenciones solo CSS/UI (marcadas /* INTERVENTO CSS - GP AAAA-MM */)
CHANGELOG.mdhistoria de las versiones
PANORAMICA_JOECMS.mdarquitectura e historia de las decisiones
INSTALLER_PIANO.md, VGALLERY_NEXT_PIANO.mdplanes de trabajo
IGIENE_SEGRETI.mdgestión de secretos
GUIDA_INDICIZZAZIONE_AI.md, GUIDA_SITEMAP.mdvalores por defecto reutilizables para indexación y sitemap
docs/manuale/este manual: qué permite la plataforma — controlado automáticamente, ver §5