Compare commits

...

3 Commits

3 changed files with 0 additions and 263 deletions
-117
View File
@@ -1,117 +0,0 @@
<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
This file is part of a Moko Consulting project.
SPDX-License-Identifier: GPL-3.0-or-later
# FILE INFORMATION
DEFGROUP: MokoPlatform.Documentation
INGROUP: MokoPlatform.Templates
REPO: https://git.mokoconsulting.tech/MokoConsulting/moko-platform
PATH: /templates/docs/dolibarr/update-server.md
BRIEF: Developer guide for wiring up Dolibarr module update checks — synced to docs/ in all CRM repos
-->
# 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:
```php
// 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:
```php
/**
* 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
```json
{
"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
```bash
curl -s https://raw.githubusercontent.com/mokoconsulting-tech/REPO_NAME/main/update.txt | jq .
```
@@ -1,56 +0,0 @@
# Update Server — Dolibarr Modules
## Overview
MokoGitea provides a built-in Update Server that can serve Dolibarr-compatible JSON update feeds from repository releases. **No static feed file is needed in the repository.**
## How It Works
1. **Enable Update Server** in the repository's Settings > Advanced Settings
2. **Configure metadata** in Settings > Update Server (set platform to `dolibarr`)
3. **Create releases** with tagged module archives
4. MokoGitea serves the update feed at `/{owner}/{repo}/updates/dolibarr.json`
## Feed URL
```
https://git.mokoconsulting.tech/{owner}/{repo}/updates/dolibarr.json
```
## Release Naming Convention
Release assets should follow:
```
{module_name}-{version}.zip
```
Examples:
- `mokocrm-18.0.1.zip`
- `mokodolisign-3.2.0.zip`
## Update Server Settings
Configure these in Settings > Update Server:
| Field | Description | Example |
|-------|-------------|---------|
| Platform | Set to `dolibarr` | `dolibarr` |
| Extension Name | Dolibarr module directory name | `mokocrm` |
| Display Name | Human-readable name | `Module - MokoCRM` |
| Extension Type | Usually `module` | `module` |
| Maintainer | Organization name | `Moko Consulting` |
| Support URL | Product support page | `https://mokoconsulting.tech/support/mokocrm` |
## Download Gating
Same three modes as Joomla: `none`, `prerelease`, `all`.
## Status
Dolibarr Update Server support is currently **disabled for all modules except MokoCRM**. Metadata is pre-configured and ready to enable when needed.
## What NOT to Do
- **Do NOT commit static feed files to the repository**
- **Do NOT use legacy update check mechanisms** — use the built-in feed
@@ -1,90 +0,0 @@
# Update Server — Joomla Extensions
## Overview
MokoGitea provides a built-in Update Server that dynamically generates Joomla-compatible update XML feeds from repository releases. **No static `updates.xml` file is needed in the repository.**
## How It Works
1. **Enable Update Server** in the repository's Settings > Advanced Settings
2. **Configure metadata** in Settings > Update Server (extension name, type, target version, etc.)
3. **Create releases** with tagged assets (e.g. `pkg_mokowaas-02.19.00.zip`)
4. MokoGitea automatically serves the update feed at `/{owner}/{repo}/updates.xml`
## Feed URL
```
https://git.mokoconsulting.tech/{owner}/{repo}/updates.xml
```
This URL is what goes into your Joomla extension's `update_server` element in the manifest XML.
## Manifest Configuration
In your extension's manifest XML (`*.xml`), add:
```xml
<updateservers>
<server type="extension" name="{Extension Name}">
https://git.mokoconsulting.tech/MokoConsulting/{RepoName}/updates.xml
</server>
</updateservers>
```
## Release Naming Convention
Release assets must follow this naming pattern for the feed generator to detect them:
```
{extension_name}-{version}.zip
{extension_name}-{version}.tar.gz
```
Examples:
- `pkg_mokowaas-02.19.00.zip`
- `tpl_mokoonyx-02.19.00.zip`
- `mod_mokojoomhero-01.05.00.zip`
## Update Server Settings
Configure these in Settings > Update Server:
| Field | Description | Example |
|-------|-------------|---------|
| Extension Name | Joomla element name | `pkg_mokowaas` |
| Display Name | Human-readable name | `Package - MokoWaaS` |
| Extension Type | package, plugin, template, module, component | `package` |
| Target Version | Regex for compatible Joomla versions | `(5|6)\..*` |
| PHP Minimum | Minimum PHP version | `8.1` |
| Maintainer | Organization name | `Moko Consulting` |
| Maintainer URL | Organization website | `https://mokoconsulting.tech` |
| Support URL | Product support page | `https://mokoconsulting.tech/products/{alias}` |
| Info URL | Product information page | `https://mokoconsulting.tech/products/{alias}` |
## Download Gating
Three modes control who can download release assets:
| Mode | Behavior |
|------|----------|
| `none` | All downloads are public |
| `prerelease` | Pre-release downloads require a license key; stable releases are public |
| `all` | All downloads require a license key |
The update feed XML is **always public** — only the actual file downloads are gated.
## What NOT to Do
- **Do NOT commit `updates.xml` to the repository** — it is served dynamically
- **Do NOT use static update server workflows** — the old CI-generated approach is deprecated
- **Do NOT hardcode version numbers in feed URLs** — the feed auto-detects from releases
## Changelog Feed
A changelog XML is also served automatically at:
```
https://git.mokoconsulting.tech/{owner}/{repo}/changelog.xml
```
This is generated from release notes (markdown body of each release).