Skip to content
JoeCMS Download 3.1.5
Manual · 14

Environments, installation and deploy

Where configurations live, what changes between development and production, how a change goes live and how a version is packaged.

1. Operating requirements

  • PHP ≥ 8.1 with mysqli, mbstring, json, curl, openssl (critical) and gd (recommended)
  • MySQL 8 / MariaDB, also with the default strict sql_mode (see 07). Non-standard port (Aiven, managed databases): FF_DATABASE_PORT in the config, which the wizard writes on its own, or host:porta in FF_DATABASE_HOST
  • Apache with mod_rewrite — the .htaccess is an integral part of the architecture, not an accessory: without it, the front controller receives nothing
  • write access to themes/site/conf/, uploads/, cache/ and the docroot (for the .htaccess)
  • exec() and shell_exec() are not required: on hostings that place them in disable_functions (many shared hostings, all free ones) the site still runs, because cache and job syntax is checked using PHP's internal parser (vendor/wolfgan/filemanager/services/fs_php.php, vendor/hcore/jobs/Jobs.php). Without them, only external programs are missing: PDF previews (convert from ImageMagick, falling back to a generic icon) and external image, CSS and JS optimizers that ffMedia::optimize() uses if found (jpegoptim, optipng, cssnano, uglifyjs…). The guard is present in both copies of ffMedia and ffThumb: wizard-installed sites load those from vendor/phpformsframework/, not ff/classes/
  • if jobs are needed: a scheduler (panel cron, via curl) — see 05
  • if a worker is needed: shell access and systemd — not all shared hostings allow it

2. The two environment configuration files

themes/site/conf/config.local.php     development (host ending in .local)
themes/site/conf/config.remote.php    production  (written by the installer, chmod 0640)

HTTP_HOST decides which one is loaded. Neither is tracked in git: the repo only has the .dist files. This is where the secrets live — DB credentials, SMTP, JC_APP_SECRET, JC_AUTH_SALT, SENTRY_DSN, provider keys. See IGIENE_SEGRETI.md.

⚠️ JC_APP_SECRET and JC_AUTH_SALT are unique per installation (64 hex from random_bytes). Regenerating config.remote.php invalidates sessions and makes everything encrypted with that secret unreadable. The file goes in the backup, and it isn't regenerated.

Constants a project often touches:

ConstantEffect
JC_SITE_DOMAINthe installation's domain, from which hook.php derives DOMAIN_PROD and WWW_LINK (see the box in §3). The installer writes it
AREA_SEO_SHOW_MODIFY, AREA_PUBLISHING_SHOW_PREVIEW, MOD_SEC_PROFILING, MAX_UPLOADvalues that hook.php sets only if the config has not already defined them (08 §4)
JC_REGISTRATION_ENABLEturns registration on/off
JC_USER_AREA_PATHpersonal area path (/area-utente is only a fallback)
ADMIN_TOOLBAR_HIDDENedit bar on the front end (default true = hidden)
AI_MD_ENABLEDMarkdown version of content for LLMs
MOD_AUTH_COOKIE_SECURE, MOD_AUTH_COOKIE_SAMESITEsession cookie (08 §6)
SENTRY_DSNerror tracking (13 §4)
AUTH_2FAsecond factor at login: '' off, email or sms (08 §5bis). The installer writes it empty
DEBUG_MODE, DISABLE_CACHE, CACHE_LAST_VERSIONasset cache (12)

3. First installation: the wizard

The guard is in config.php: if the host does not end in .local and config.remote.php is missing, it includes install/index.php and exits. The mere presence of the config disables the wizard.

Ten steps: requirements → database → application → billing → localization → admin → registration → layout → services → done. Details in PANORAMICA_JOECMS.md §7 and INSTALLER_PIANO.md.

The parts that matter operationally:

  • Interface in four languages (IT, EN, ES, FR). All wizard texts, error messages included, live in the install/i18n.php dictionary and are read with jc_t('chiave', …) (sprintf placeholders); install/lib.php, install/icons.php and install/cleanup.php go through it too. On the first visit the language comes from Accept-Language (the supported one with the highest q; English if there is none), then it stays in the session and in the jc_install_lang cookie. The selector at the top right opens ?step=<step>&lang=xx: the controller saves the choice and redirects without the parameter, so later POSTs don't repeat the change (unsent data in the current form is lost). The installer's language is the site's default language: until the localization step has been submitted it is also the only active one; after that, changing language moves the default and adds it to the chosen ones. The localization step has the last word. The language is also the default for time zone and country. A new string is added to the dictionary in all four languages, with the same placeholders.
  • CREATE DATABASE with graceful fallback: if the hosting denies it, the wizard says "create it from the panel" and retries just the connection. It degrades, it doesn't block.
  • Test email during installation: mail is verified before finishing. Encryption must be chosen together with the port — SSL/TLS with 465, STARTTLS with 587, none with 25 — and it's the same value that ends up in A_SMTP_SECURE: a wrong pair gives a timeout, and the error suggests the right one. A password left empty keeps the one already entered.
  • The services step: cookie consent, Sentry and notification provider credentials — JoeSMTP and Twilio for SMS (with the sender, without which they don't go out), OneSignal for push. They end up in the Services area, not in the config; they can be left empty and filled in later (06 §4).
  • .htaccess generated from the wizard's domain (jc_write_htaccess()), with the domain entered in all HTTP_HOST conditions (escaped dots, www. and bare, media./static. subdomains, CORS, static cache), anchored at both ends so that the main host's ones don't also apply to media. (11 §5). Without a known domain → no HTTP_HOST constraint, so the site stays reachable.
  • Internal files closed to the browser: right after the HTTPS redirect the .htaccess answers 404 to the PHP files (and to .sql, .log, .sh, .ini, .lock…) in library/, vendor/, ff/, conf/, applets/, contents/, cache/, uploads/, migrations/, to all of cache/logs/ and, at the root, to database.sql and the .md files. Apache serves by itself every file that exists (index.php kicks in only for the others): up to 3.1.0 anyone could download the CMS logs and the dump, and run PHP files that the CMS only includes. Static files (CKEditor lives in vendor/), cm/ (showfiles.php, static.php, error.php are real addresses), themes/ (kcfinder) and modules/ stay open: every module protects itself, because the Package Manager opens /modules/<id>/installer/wizard.php. The condition on REDIRECT_STATUS lets internal rewrites through (/static → cm/static.php, the ErrorDocument).
  • Hardening: install.lock, chmod 0640 on the config, install/cleanup.php (POST only, only if the config exists) that recursively deletes /install.

⚠️ The .htaccess doesn't travel in the ZIP. The file tracked in git contained development domains, and the "don't overwrite if it exists" guard left it intact → dead site. The installer generates it.

⚠️ Domain constants are always read with defined(). hook.php defines WWW_LINK, WWW_LINK_ABSOLUTE, DOMAIN_PROD and LOCAL_DOMAIN in every case, with a host comparison tolerant of the www. prefix and port. Old installations defined them inside a switch ($_SERVER["HTTP_HOST"]): served on a host other than the listed one they defined nothing, and on PHP 8 reading a non-existent constant is a fatal Error — blank page, no longer PHP 7's warning with fallback to the name. Since on a site hook.php may be older than the code reading it, the CMS never takes it for granted: library/gallery/common/set_header_page.php goes through set_header_page_is_canonical_host() and the defined("DOMAIN_PROD") gate. Same rule for applets and site code.

⚠️ The domain lives in the config, not in hook.php. The installer writes define('JC_SITE_DOMAIN', 'esempio.it') into config.remote.php, and hook.php reads it from there; without it, production is assumed and links are built from the request host (no noindex on a staging site). Up to 3.0.3 the installer wrote it inside hook.php in place of the [DOMINIO] placeholder, and every update, which replaces hook.php, wiped it out. hook.php is now entirely platform code: what belongs to the site lives in the config (values) and in hook.local.php (code), which updates never touch (10 §1). With a manual deploy, the JC_SITE_DOMAIN line goes into the config before uploading the new hook.php.

4. Deploy: shipping the active branch

Regenerating the package for every fix is too slow, and uploading single files from an FTP client is the most effective way to break a live site: production is left with a mix of versions — an old hook.php with a new module gives a Fatal error — and that combination doesn't exist in any commit, so you can't reproduce it locally.

The CMS ships with the tool that avoids all this: bin/deploy.sh, which uploads over SSH the HEAD of the git branch you're on, and only the files changed since the last deploy.

cp bin/deploy.conf.example bin/deploy.conf    # once per installation
./bin/deploy.sh controlla                     # who am I on the server, where's the docroot, which commit
./bin/deploy.sh                               # dry run: lists what it would upload
./bin/deploy.sh --vai                         # uploads for real

The first run, on a site created by the wizard or by manual uploads, must be a full one — it doesn't match any commit, and the incremental mode wouldn't know where to start:

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

If the shell answers permission denied: ./bin/deploy.sh, the file has lost its execute permission (it happens when copying it by hand, from an FTP client, from Windows or in a repository with core.fileMode=false, or in a new project created by copying the files of cms). Launch it once with bash: the script notices it has lost the bit, restores it on disk and in the git index, and from there a commit is enough so it is never lost again at the next checkout:

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

How it knows where to resume

At the end of the deploy it writes the commit on the server in $HOME/.joecms-deploy-rev-<site>: in the SSH user's home, not the docroot, because it must not be reachable from the web. The site-name suffix is for when several installations live on the same server, with the same user (often root): with a single file every deploy would resume from another site's commit.

It always deploys the HEAD: modified, uncommitted files don't go, nor do files never added to git — the script lists them before moving, and if you asked for --vai with a dirty working tree it stops.

Configuration

It lives in bin/deploy.conf, which is outside git: it's per-installation and per-machine. The repo only has bin/deploy.conf.example.

A site with several environments (production, staging) keeps one file for each, bin/deploy.<environment>.conf, and picks it with --ambiente:

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

With --ambiente the file must exist: the script doesn't fall back to bin/deploy.conf, which would mean deploying to the wrong environment. It's best for the default file to be staging, so production is reached only by asking for it by name.

KeyPurpose
DEPLOY_HOST, DEPLOY_USER, DEPLOY_PORTSSH connection; host and user are mandatory
DEPLOY_ROOTdocroot as seen over SSH — the same value as FF_DISK_PATH in config.remote.php
DEPLOY_CHOWNthe site's 'user:group', mandatory if you log in as root
DEPLOY_PHPthe PHP CLI of the site's container, for the final version check
DEPLOY_URL, DEPLOY_SMOKEend-of-deploy HTTP smoke test; on a multilingual site, one page per language

⚠️ Deploying as root without DEPLOY_CHOWN: uploaded files stay owned by root and with suexec or suPHP the site answers 500 on everything. The script refuses to start, and the warning can't be bypassed with --forza. ./bin/deploy.sh controlla shows the right owner.

Options

OptionEffect
controlladiagnostics: user, docroot found automatically, PHP binaries with mysqli/mbstring, permissions of cache/ and uploads/, recorded commit
(none)dry run — doesn't touch the server
--vaiexecutes
--completoall versioned files of the HEAD (first deploy, or realignment)
--rimuovideletes from the server files removed from the repo (without it, they stay where they are)
--svuota-cacheempties cache/ on the server, keeping cache/logs/ and cache/.thumbs/
--da <sha>starts from a commit given by hand instead of the recorded one
--solo <path>limits to a subtree
--forzaproceeds with a dirty working tree
--niente-smokeskips the final HTTP check

What doesn't travel, and why

ExcludedWhy
themes/*/conf/config.remote.php, config.local.phpDB credentials and JC_APP_SECRET: they're edited by hand on the server
root .htaccessin production it's the one generated by the installer with the real domain; overwriting it with the development one takes the site down
install/the installer has already been removed by install/cleanup.php: putting it back online is just more surface
database.sqlthe schema is never applied by copying files
cache/content generated by the site
docs/, tests/, working *.md, .idea/, .claude/, .githooks/development material; a published docs/sql would be an invitation to read the migrations
modules/*/tests/module tests: destructive on the database they're given, and not needed on the server

When one of these changes and the change must still reach production, the script says so instead of uploading it silently: it lists the docs/sql/ migrations, reminding you they must be applied before the code (new code on an old schema runs SHOW COLUMNS and switches itself off; old code on a new schema doesn't), the new define()s appearing in config.remote.php.dist, and changes to the .htaccess.

The cache

Templates, content and assets go through the disk cache: just uploaded, the site keeps serving the old version. If the deploy touches applets/, contents/ or themes/<theme>/{layouts,contents,css,javascript} the script flags it and you add --svuota-cache, which cleans cache/ leaving cache/logs/ (the error diary, the first thing to look at if something broke) and without recreating the folder, so permissions stay the good ones. It also leaves cache/.thumbs/, the image copies that media.<domain> serves as they are: deleting them all at once is a wave of regenerations, and with a .htaccess that also sends media. requests to index.php it's a 500 on every image (11 §5). On a multilingual site this also holds cache/locale.php, the snapshot of the active languages.

⚠️ With a high opcache.revalidate_freq on the server, empty the cache afterwards, not right away. PHP rechecks the date of an already compiled file at most every revalidate_freq seconds (default 2): with a value like 60, in the first minute after the upload it may still run the old version of a recently used file, while it already reads the templates new from disk. Pages regenerated in that minute — including by the script's final check — come out with the old code, or with the new template and the old PHP, and the page cache keeps them for hours. With a high value, empty cache/ by hand once that time has passed (the script, if there's nothing to upload, exits without touching it), or restart the site's PHP-FPM before emptying it.

Fixes to the generated .htaccess (by the wizard, jc_write_htaccess() in install/lib.php, or by the old installer's template, conf/gallery/install/.htaccess-cms.tpl) don't reach sites already installed, because that file doesn't travel: they have to be carried over by hand, as for the media. subdomain (11 §5). After 3.1.0 there are two: the internal files block (§3) and ExpiresByType text/html "access plus 0 seconds" (12); the exact lines are in jc_write_htaccess() and jc_htaccess_static_tail(), and since 3.1.1 also in the old installer's three conf/gallery/install/.htaccess-*.tpl templates.

The final check

The smoke test runs from your computer, not the server: it calls the routes over HTTP as a browser would, and it's the check that catches the forgotten file. DEPLOY_SMOKE lists the paths; on a multilingual site you put one per language, and that's how you find the language left behind. If the project has tests/run.php with tests/smoke.config.php, the script uses that suite instead of the curl calls.

What stays manual

SQL migrations, new constants in config.remote.php, .htaccess, panel cron.

An installation with schema < 4 has to be aligned once, before uploading the 1.6.0 code: the new code writes NULL into empty dates, which a schema 3 rejects even on a non-strict server (#1048), while schema 4 also works with the 1.5.x code. You upload bin/db-allinea-schema.php alone, run it as a dry run and then with --vai, and only then deploy. For that file scp is fine, not deploy.sh --solo: it records the whole HEAD as uploaded, and the next deploy wouldn't bring the rest.

And, only the first time, permissions of the writable folders:

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

bin/ must not be reachable from the web: the package includes bin/.htaccess with Require all denied. On nginx the rule must be replicated in the server configuration.

5. Package and versions

./build-zip.sh [version]      # → joecms-<version>.zip

It packages the files tracked by git in their working-tree state (not git archive, which would ignore uncommitted changes), and excludes: environment configs (the .dist ones stay), the development .htaccess, docs/ (except the manual), root *.md files, development hooks (.githooks/, .claude/), source maps, vendors' test/doc/example directories. It empties cache/ and keeps only loghi in uploads/.

Exceptions to the "no markdown" rule: CHANGELOG.md and docs/manuale/ (since 1.3.0), which travel with the package.

Exception to the "no shell scripts" rule: bin/ — deploy.sh and deploy.conf.example — travels too. It's what the freshly installed site is updated with from then on (§4), and bin/.htaccess keeps it off the web. The end-of-build checks verify it's present, and look for the other .sh files, which have no business in the docroot.

The script checks by itself that no secrets end up in the package and that seed, installer, changelog and manual chapters are present.

The manual in the package is a snapshot

The manual that reaches a site describes the version installed on that site and doesn't update when the main CMS moves on: the next version brings its own. The build:

  • prepends to each chapter a line with the package version and date;
  • adds docs/manuale/VERSIONE.txt (version, date, source commit);
  • makes the files read-only;
  • writes docs/.htaccess with Require all denied: the manual describes the platform's internals (paths, pitfalls) and must not be served to the public. It's read from the ZIP or via FTP/panel. On nginx the rule must be replicated in the server configuration.

The manual updates with the code (main repo only)

In the CMS repository the manual follows the code automatically. .githooks/manuale-check.sh compares modified files with the paths each chapter cites in backticks — the file → chapter map isn't written by hand, it's derived from the manual itself — and lists chapters touched but not updated.

CheckpointWhat it does
Claude Code Stop hook (.claude/settings.json)at the end of a turn, if there are chapters to review, it stops the close and has the manual updated; each chapter/file pair is flagged once per content (.git/manuale-ack)
git pre-commit hook (.githooks/pre-commit)on staged files it blocks once per chapter/file pair and content (.git/manuale-ack-commit): if the manual needn't change, just repeat the same commit. MANUALE_WARN_ONLY=1 reduces it to a warning
By hand.githooks/manuale-check.sh on the working tree; --commit <sha> on a commit already made

The git hook must be enabled once per clone: git config core.hooksPath .githooks. To keep the map reliable, chapters cite files by path, in backticks. An attached line number (library/gallery/system/cache.php:957) is tolerated. Two fixed rules complete the map: docs/sql/ migrations go to chapter 07, and hook.php, cited in almost every chapter, counts for a chapter only if the change touches a function that chapter names (for example registerUser()).

⚠️ The check only protects changes that go through it. The Stop hook only sees uncommitted changes of a Claude Code session in this repository. The pre-commit blocks instead of just warning because graphical clients (Sourcetree, PhpStorm) show a hook's output only when it fails: while it only warned, work brought over from another project and committed straight away (it happened with the language preference) arrived without the manual and without anyone noticing. A commit made with Bypass commit hooks in Sourcetree, or with --no-verify, skips the check: in that case run .githooks/manuale-check.sh --commit <sha> afterwards.

Versioning

ConstantWhereWhen it's bumped
JC_VERSIONinstall/lib.phpon every package
JC_SCHEMA_VERSIONinstall/lib.phpevery time database.sql changes

Changes are noted in CHANGELOG.md under [Unreleased] as you go, and become the version's section when the package is created (build-zip.sh warns if the section for the version being built is missing).

The schema in the CHANGELOG: what joecms.it reads

The Download page and the changelog on joecms.it work out from the package's CHANGELOG.md whether a version changes the database schema, and in that case they warn that the migrations must be applied before the code. For the site, a version's schema is the first bold number (one digit) within 40 characters of the word "schema", looked for in the summary and then in the heading; a version with no number inherits the previous one's; a version changes the schema if it has the ### Schema group or a number different from the previous one. A release's section therefore:

  • carries ## [X.Y.Z] — YYYY-MM-DD · schema **N** in its heading, with N = JC_SCHEMA_VERSION;
  • has the ### Schema group only if N has changed: what changes, the docs/sql/ migration and the order, first the schema and then the code (§4);
  • in the summary doesn't name another schema in bold before N, because the site would read that one.

It is checked by .githooks/changelog-schema.php, which reads the section the way the site does and compares it with JC_SCHEMA_VERSION, with the previous release's schema (the one in install/lib.php at the commit that brought JC_VERSION to that number) and with database.sql, empty lines and -- comments excluded. build-zip.sh stops if it doesn't add up. The pre-commit runs the same check on the release commit, i.e. the one that changes JC_VERSION, and not on the others: during development JC_SCHEMA_VERSION may already go up while the current version's section still declares the schema it shipped with. By hand: php .githooks/changelog-schema.php [version], or --commit <sha> on a commit already made.

⚠️ The number has one digit because that's how JoeSitoChangelog::versione() reads it in the site's project: schema 10 must first be taught to the site, and until then the build stops. In the history the rule was skipped once: 1.0.5 added to database.sql the ff_international rows for the logout and registration texts, leaving the schema at 2.

Automatic updates and migrations (since v3.0.2)

JoeCMS includes a built-in engine (library/updater/JoeCmsUpdater.php) to update live sites automatically, safely and non-destructively.

  • CLI (bin/update.php):
    • php bin/update.php --status: environment diagnostics and migration status
    • php bin/update.php --file <pacchetto.zip> [--vai]: runs the update from a ZIP archive
    • php bin/update.php --migrations-only [--vai]: runs only the pending DB migrations
    • php bin/update.php --maintenance on|off: turns maintenance mode on/off
  • Web backend (/restricted/updater):
    • Handled in conf/gallery/manage/updater/index.php, with health status, ZIP upload, real-time log console and database alignment.
  • Migration system (migrations/):
    • Sequential .sql or .php migrations (baseline schema_0004_v302_baseline.php).
    • Automatic tracking in the jc_migrations table, handled by MigrationsRunner.
    • schema_0005_testi_multilingua.php (schema 5) brings into the dictionary the texts of the cookie banner, the account emails and password recovery: until it runs, those texts come out as codes (svc_cookie_title). The updater runs it by itself in the same operation, with the site in maintenance. With a manual deploy you upload the migration file first, run the migrations (php bin/update.php --migrations-only --vai, or the pending migrations in /restricted/updater, conf/gallery/manage/updater/index.php) and only then the rest of the code.
  • hook.php and hook.local.php (library/updater/JoeCmsUpdater.php):
    • hook.php belongs to the platform and updates replace it; beforehand, the backup keeps a copy, so a rollback brings it back with the rest.
    • hook.local.php, the site's code, is on the protected list (with the config, .htaccess, uploads/) and build-zip.sh removes it from the package. Also protected are the PWA files the installer generates for the site (manifest.json, site.webmanifest, browserconfig.xml): in the update package manifest.json is the metadata file, and up to 3.0.3 it ended up in place of the site's manifest.
    • Once only, before extracting the files: if the config has no JC_SITE_DOMAIN and the old hook.php has a written domain ($jc_site_domain = "…"), the updater copies it into the config.
  • Maintenance mode (.maintenance):
    • Handled by cm/maintenance.php at the top of index.php. Responds 503 Service Unavailable, with a bypass token for the administrator.
    • Texts in the visitor's language (address prefix or browser) and exit after the page, see 13 §1bis.
  • Two build packages (build-zip.sh):
    • joecms-<versione>.zip: full package to unpack for a new installation.
    • joecms-update-<versione>.zip: lightweight package with manifest.json, without installer or destructive dumps, which always preserves config.remote.php, uploads/, cache/ and .htaccess.

6. Go-live checklist

  • [ ] migrations applied and copied into database.sql, JC_SCHEMA_VERSION bumped
  • [ ] clean PHP lint on all touched files
  • [ ] template markers checked (none with spaces, none lost)
  • [ ] modified routing_table.xml files actually uploaded (they don't error: simply nothing happens)
  • [ ] upload done with ./bin/deploy.sh --vai, not by hand (no mix of versions)
  • [ ] cache/ emptied after uploading (--svuota-cache)
  • [ ] crons scheduled and verified (one log line for each)
  • [ ] webhooks configured at the providers, with the right secret
  • [ ] email: a real test send, not just the preview
  • [ ] robots.txt, sitemap.xml, canonical: consistent with the production domain
  • [ ] ?__debug__ leaks nothing to an arbitrary user (closed by default: no SetEnv JC_DEBUG_ALLOWED 1 left on, see 13 §2)
  • [ ] CHANGELOG.md updated
  • [ ] docs/manuale/ chapters aligned (.githooks/manuale-check.sh flags nothing)

7. The repo's "living" documents

Knowledge lives next to the code, not in tickets. They must be updated with every change:

FileScope
MIGRAZIONE_PHP7_PHP8.mdmigration and PHP 8 cases
FIX_FUNZIONAMENTO.mdfixes that change behaviour
MIGLIORIE_ESTETICHE.mdCSS/UI-only changes (marked /* INTERVENTO CSS - GP YYYY-MM */)
CHANGELOG.mdversion history
PANORAMICA_JOECMS.mdarchitecture and history of decisions
INSTALLER_PIANO.md, VGALLERY_NEXT_PIANO.mdwork plans
IGIENE_SEGRETI.mdsecrets management
GUIDA_INDICIZZAZIONE_AI.md, GUIDA_SITEMAP.mdreusable defaults for indexing and sitemap
docs/manuale/this manual: what the platform can do — checked automatically, see §5