Skip to content

Publishing to the store

Modules and themes are published to the store with a signed catalogue. This page covers both sides so that both the publisher and the person running the site know what is going on: how a package is prepared and what happens on the user's site when "Install" is pressed.

Catalogue and packages

Three things live on the server:

File Meaning
extensions/index.json The catalogue of all modules and themes: name, title, summary, category, whether it is free, the zip address and SHA-256 digest of each version, the compatibility range
extensions/index.sig The catalogue's Ed25519 signature
modules/<Name>/<Name>-<version>.zip, themes/<Name>/… Packages

When the core downloads the catalogue it first verifies the signature with the public key. A catalogue whose signature is invalid or expired is not shown at all; the store appears empty and installation cannot be done.

Release flow

  1. Increase the version in module.json. If you do not increase the version, the store sees no new release and no "update" button appears on sites.
  2. If the module relies on a new core feature, raise the lower bound of core_version to that core version (e.g. ">=2.2.53 <3").
  3. Update the catalogue text (eklenti-katalogu.json): title, summary, category, feature list, free (can it be installed from the panel), bundled (does it come inside the installation package).
  4. If it needs the core, release the core first.
  5. bash yayinla-eklenti.sh hepsi Name builds the package, signs the index and uploads it.

The script's modes:

Mode What it does
derle [Name …] Builds the zips and the signed index locally; if no name is given, all modules and themes
yukle Uploads only changed packages or those not on the server; uploads the index last
hepsi [Name …] derle + yukle
imzala Only refreshes the index signature

Uploading the index last is important: at the moment the index shows the new version, the package must already be in place. Otherwise the user would try to download a file that does not exist.

Compatibility check

Every catalogue version carries the module's core_version range and requires dependencies. It is checked in two places:

  • When installing: if the user's core is outside the range, installation stops saying "Not compatible with this installation"; the reason is listed.
  • When updating the core: the update is blocked if it would break an installed module's range.

That is why the order is always: first the core, then the add-on that relies on the core. The Notes module is an example: the studio.body.end hook arrived with core 2.2.53, the module asks for >=2.2.53 <3 and was released after the core.

When the user presses "Install"

The core's ExtensionInstaller class does the following in order:

  1. The name is validated ([A-Za-z][A-Za-z0-9_-]*) and looked up in the catalogue. An extension that is not in the catalogue or not marked free is not installed from the panel.
  2. Compatibility is checked.
  3. The zip address must be under the server's own area; an address containing .. or pointing elsewhere is rejected.
  4. The package is downloaded (at most 32 MB, 120-second timeout).
  5. The SHA-256 digest of what was downloaded is compared with the digest in the signed catalogue. If it does not match, installation stops: the package is not what the signed catalogue described.
  6. The zip is safely extracted and its content is prepared in a side-by-side folder.
  7. A backup of the existing files is taken; the new files are put in place in one go. Old files that the new version no longer ships are deleted, so no old leftovers remain in the module folder.
  8. If the module is active and this is an update, the same protected flow runs: maintenance lock, database snapshot, the module's migrations. If something goes wrong, files and database are rolled back together.
  9. The cache is cleared.

The first installation of a module that is not active only downloads files; database changes are made the moment you activate the module.

Pre-release checklist

  • The module.json version was increased.
  • core_version is correct; if a new core feature is needed, the core was released.
  • New migrations are newly numbered and re-runnable (Database and migrations).
  • The catalogue text is up to date.
  • The post-release check "the index on the server is signed and valid" passed.
  • A clean installation and an update from the previous version were tried on a test site.

Signature

The signing key exists only with the publisher and is never shared; the public key is embedded in the core. The catalogue is valid for 45 days. If there will be no new release, run the imzala mode before the time runs out; otherwise all sites see the store empty.

Next: Checklist.

Last updated: 13.10.2026