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) ygd(recomendada) - MySQL 8 / MariaDB, también con el
sql_modestrict por defecto (ver 07). Puerto no estándar (Aiven, bases de datos gestionadas):FF_DATABASE_PORTen la config, que el asistente escribe solo, o bienhost:portaenFF_DATABASE_HOST - Apache con
mod_rewrite— el.htaccesses 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()yshell_exec()no son necesarios: en los hostings que los incluyen endisable_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 (convertde ImageMagick, sustituido por el icono genérico) y los optimizadores externos de imágenes, CSS y JS queffMedia::optimize()usa si los encuentra (jpegoptim,optipng,cssnano,uglifyjs…). La protección está en ambas copias deffMediayffThumb: los sitios instalados por el asistente cargan las devendor/phpformsframework/, noff/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_SECRETyJC_AUTH_SALTson únicos por instalación (64 hex derandom_bytes). Regenerarconfig.remote.phpinvalida 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:
| Constante | Efecto |
|---|---|
JC_SITE_DOMAIN | el 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_UPLOAD | valores que hook.php fija solo si el config no los ha definido ya (08 §4) |
JC_REGISTRATION_ENABLE | enciende/apaga el registro |
JC_USER_AREA_PATH | ruta del área personal (/area-utente es solo un fallback) |
ADMIN_TOOLBAR_HIDDEN | barra de edición en el front-end (por defecto true = oculta) |
AI_MD_ENABLED | versión Markdown de los contenidos para los LLM |
MOD_AUTH_COOKIE_SECURE, MOD_AUTH_COOKIE_SAMESITE | cookie de sesión (08 §6) |
SENTRY_DSN | seguimiento de errores (13 §4) |
AUTH_2FA | segundo factor en el login: '' apagado, email o sms (08 §5bis). El instalador la escribe vacía |
DEBUG_MODE, DISABLE_CACHE, CACHE_LAST_VERSION | caché 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.phpy se leen conjc_t('chiave', …)(marcadoressprintf); tambiéninstall/lib.php,install/icons.phpeinstall/cleanup.phppasan por ahí. En la primera visita el idioma viene deAccept-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 cookiejc_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 DATABASEcon 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).
.htaccessgenerado a partir del dominio del asistente (jc_write_htaccess()), con el dominio introducido en todas las condicionesHTTP_HOST(puntos escapados,www.y desnudo, subdominiosmedia./static., CORS, caché estática), ancladas por ambos lados para que las del host principal no valgan también paramedia.(11 §5). Sin dominio conocido → ningún vínculoHTTP_HOST, así el sitio sigue siendo alcanzable.- Archivos internos cerrados al navegador: justo después de la redirección HTTPS el
.htaccessresponde 404 a los PHP (y a.sql,.log,.sh,.ini,.lock…) delibrary/,vendor/,ff/,conf/,applets/,contents/,cache/,uploads/,migrations/, a todocache/logs/y, en la raíz, adatabase.sqly a los.md. Apache sirve por su cuenta cada archivo que existe (index.phpentra 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á envendor/),cm/(showfiles.php,static.php,error.phpson direcciones reales),themes/(kcfinder) ymodules/: cada módulo se protege por sí mismo, porque el Package Manager abre/modules/<id>/installer/wizard.php. La condición sobreREDIRECT_STATUSdeja pasar las reescrituras internas (/static→cm/static.php, elErrorDocument). - Endurecimiento:
install.lock,chmod 0640en el config,install/cleanup.php(solo POST, solo si el config existe) que borra recursivamente/install.
⚠️ El
.htaccessno 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.phpdefineWWW_LINK,WWW_LINK_ABSOLUTE,DOMAIN_PRODyLOCAL_DOMAINen toda condición, con la comparación del host tolerante con el prefijowww.y el puerto. Las instalaciones viejas las definían dentro de unswitch ($_SERVER["HTTP_HOST"]): servido en un host distinto del listado no definían nada, y en PHP 8 leer una constante inexistente es unErrorfatal — página en blanco, ya no el warning con fallback al nombre de PHP 7. Como en un sitiohook.phppuede ser más viejo que el código que lo lee, el CMS nunca lo da por supuesto:library/gallery/common/set_header_page.phppasa porset_header_page_is_canonical_host()y por la guardadefined("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 escribedefine('JC_SITE_DOMAIN', 'esempio.it')enconfig.remote.php, yhook.phplo 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, sinnoindex). Hasta la 3.0.3 el instalador lo escribía dentro dehook.phpen lugar del marcador[DOMINIO], y cada actualización, que sustituyehook.php, lo borraba.hook.phpes ahora todo de la plataforma: lo que es del sitio está en el config (valores) y enhook.local.php(código), que la actualización no toca (10 §1). Con un deploy manual, la líneaJC_SITE_DOMAINse añade al config antes de subir el nuevohook.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.
| Clave | Para qué sirve |
|---|---|
DEPLOY_HOST, DEPLOY_USER, DEPLOY_PORT | conexión SSH; host y usuario obligatorios |
DEPLOY_ROOT | docroot 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_PHP | el PHP CLI del contenedor del sitio, para el control de versión final |
DEPLOY_URL, DEPLOY_SMOKE | smoke 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 controllamuestra el propietario correcto.
Las opciones
| Opción | Efecto |
|---|---|
controlla | diagnó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 |
--vai | ejecuta |
--completo | todos los archivos versionados del HEAD (primer despliegue, o realineación) |
--rimuovi | borra del servidor los archivos eliminados del repo (sin ella, se quedan donde están) |
--svuota-cache | vací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 |
--forza | continúa con el working tree sucio |
--niente-smoke | salta la verificación HTTP final |
Qué no viaja, y por qué
| Excluido | Por qué |
|---|---|
themes/*/conf/config.remote.php, config.local.php | credenciales de BD y JC_APP_SECRET: se tocan a mano en el servidor |
.htaccess de la raíz | en 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.sql | el 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/.htaccessconRequire 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/.htaccessconRequire 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 control | Qué 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
| Constante | Dónde | Cuándo se incrementa |
|---|---|---|
JC_VERSION | install/lib.php | con cada paquete |
JC_SCHEMA_VERSION | install/lib.php | cada 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
### Schemasolo si N ha cambiado: qué cambia, la migración dedocs/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 migracionesphp bin/update.php --file <pacchetto.zip> [--vai]: ejecuta la actualización desde un archivo ZIPphp bin/update.php --migrations-only [--vai]: ejecuta solo las migraciones de BD pendientesphp 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.
- Gestión en
- Sistema de migraciones (
migrations/):- Migraciones secuenciales
.sqlo.php(baseschema_0004_v302_baseline.php). - Seguimiento automático en la tabla
jc_migrations, gestionado porMigrationsRunner. 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.
- Migraciones secuenciales
hook.phpyhook.local.php(library/updater/JoeCmsUpdater.php):hook.phpes 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/) ybuild-zip.shlo 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ónmanifest.jsones 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_DOMAINy el antiguohook.phptiene un dominio escrito ($jc_site_domain = "…"), el updater lo copia en el config.
- Modo de mantenimiento (
.maintenance):- Gestionado por
cm/maintenance.phpal principio deindex.php. Responde503 Service Unavailable, con token de bypass para el administrador. - Textos en el idioma del visitante (prefijo de la dirección o navegador) y
exittras la página, ver 13 §1bis.
- Gestionado por
- 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 conmanifest.json, sin instalador ni dumps destructivos, que conserva siempreconfig.remote.php,uploads/,cache/y.htaccess.
6. Checklist de puesta en línea
- [ ] migraciones aplicadas y reflejadas en
database.sql,JC_SCHEMA_VERSIONincrementada - [ ] lint PHP limpio en todos los archivos tocados
- [ ] marcadores de las plantillas verificados (ninguno con espacios, ninguno perdido)
- [ ]
routing_table.xmlmodificados 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únSetEnv JC_DEBUG_ALLOWED 1que se haya quedado encendido, ver 13 §2) - [ ]
CHANGELOG.mdactualizado - [ ] capítulos de
docs/manuale/alineados (.githooks/manuale-check.shno 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.md | migración y casuística PHP 8 |
FIX_FUNZIONAMENTO.md | correcciones que cambian el comportamiento |
MIGLIORIE_ESTETICHE.md | intervenciones solo CSS/UI (marcadas /* INTERVENTO CSS - GP AAAA-MM */) |
CHANGELOG.md | historia de las versiones |
PANORAMICA_JOECMS.md | arquitectura e historia de las decisiones |
INSTALLER_PIANO.md, VGALLERY_NEXT_PIANO.md | planes de trabajo |
IGIENE_SEGRETI.md | gestión de secretos |
GUIDA_INDICIZZAZIONE_AI.md, GUIDA_SITEMAP.md | valores por defecto reutilizables para indexación y sitemap |
docs/manuale/ | este manual: qué permite la plataforma — controlado automáticamente, ver §5 |