Compare commits
3 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
| c57b5724ac | |||
| 78affd37ff | |||
| b3062c6559 |
@@ -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).
|
|
||||||
Reference in New Issue
Block a user