MokoCLI/templates/docs/dolibarr/update-server.md

Module Update Server

This module uses update.txt hosted in the repo root to enable Dolibarr's built-in update checker.

How It Works

1. When a PR is merged to main, the auto-release.yml workflow:
   • Reads the version from README.md
   • Sets $this->version in the module descriptor to the real version
   • Creates a GitHub Release with a git tag
   • Writes update.txt to the repo root
2. The module descriptor's $this->url_last_version points to the raw update.txt URL
3. Dolibarr's admin panel fetches this URL to check for available updates

Setup

1. Module Descriptor

In src/core/modules/mod*.class.php, ensure these lines are in the constructor:

// Version — 'development' on dev branches, real version set by auto-release on merge to main
$this->version = 'development';

// Update check — points to update.txt written by auto-release workflow
$this->url_last_version = 'https://raw.githubusercontent.com/mokoconsulting-tech/REPO_NAME/main/update.txt';

Replace REPO_NAME with this repository's name.

2. Version Parser

Add this method to the module descriptor class to parse the JSON response:

/**
 * Get the latest available version from the update server.
 *
 * Reads update.txt from the GitHub repo and extracts the version field.
 * Called by Dolibarr's module update checker.
 *
 * @return string Latest version number, or empty string on failure
 */
public function getLatestVersion(): string
{
    if (empty($this->url_last_version)) {
        return '';
    }

    $content = @file_get_contents($this->url_last_version);
    if ($content === false) {
        return '';
    }

    $data = json_decode($content, true);
    return $data['version'] ?? '';
}

3. That's It

Everything else is automated:

• deploy-dev.yml sets version to "development" on dev branches
• auto-release.yml sets the real version and writes update.txt on release
• sync-version-on-merge.yml bumps the patch version in README.md

update.txt Format

{
  "version": "01.02.03",
  "tag": "v01.02.03",
  "repo": "mokoconsulting-tech/REPO_NAME",
  "release_url": "https://git.mokoconsulting.tech/mokoconsulting-tech/REPO_NAME/releases/tag/v01.02.03",
  "updated": "2026-03-27T00:00:00Z"
}

Do not edit update.txt manually — it is auto-generated by the release workflow.

Version Lifecycle

dev/** branch    → $this->version = "development"   (no update.txt)
merge to main    → $this->version = "01.02.03"      → update.txt written → GitHub Release
next commit      → README auto-bumps to 01.02.04    (no release yet)

Troubleshooting

Issue	Solution
update.txt doesn't exist	Merge a PR to main — the first release creates it
Version shows "development"	Expected on dev/** branches — real version set on release
Dolibarr doesn't detect updates	Check $this->url_last_version URL returns valid JSON
Wrong version in update.txt	Check README.md VERSION field — it's the source of truth

Test the URL

curl -s https://raw.githubusercontent.com/mokoconsulting-tech/REPO_NAME/main/update.txt | jq .