You are here:Home»KB»Web Design»CMS»Joomla»Extensions»My Akeeba Release System Notes
Sunday, 04 February 2018 15:14

My Akeeba Release System Notes

Written by

Akeeba Release System is an extension that allows the administration and creation of update streams for both Joomla extensions in the XML format and for other software packages using a standard INI format that is compatible across many programming platforms. ARS also is capable of automatically submitting your Joomla extensions updates to the JED automatically.

The instructions for ARS are not so easy to follow until you know some key things and I will clear these up. Read this article first and then follow the official documentation because they will then make more sense. This article is based on Akeeba Release System v4.2.2 and the documentation available at the time.

Once you have gone through this guide you should considered the offcial wiki as your primary source of information as it is a great resource once you are going.

Understanding the structure of a repository

Consider the following example taken from the PDF, this will allow me to explain how things work.

Practical example: Software distribution

This is the kind of repositories ARS excels at. Create one category per software you want to publish. Let's say you produce an application named "Kitten Finder" and a Joomla! component named "Kitten.me". Each one of them is a category in ARS. Create one release per version of the software. For instance, "Kitten Finder" has released versions 1.0.b1 (a beta release) and 1.0 stable. Each one of the versions is a release in ARS. Each downloadable file is an ARS item. For example, you may have an installer of Kitten Finder for Windows, another for Linux, a third one for Mac OS X, a PDF with instructions and so on. Each file belonging to specific version of the application is an item in ARS.

In order to allow your visitors to browse the entirety of your repository, you will have to create a menu item to the full repository.

There are the following categorisations in ARS (in order: Parent --> Child)

  1. Visual Group
    • This should be considered as a section.
    • This is only used for displaying categories and releases on the front-end etc.
    • This does not affect any of the Categories, Releases or Update Streams hierarchy.
  2. Categories
    • Usually you have to create one category per software you want to publish.
    • QWcrm and QWGrabMeta should both have their own category.
  3. Releases
    • Think of a release as a group of files belonging to the same chronological order. Each release is supposed to supersede the directly previous release (the one with a higher ordering number than itself).
    • Each release is a different version of the software
    • QWcrm 3.0.0 and QWcrm 3.0.1 should both have their own release.
  4. Items
    • These what your visitors download. We chose to name them "items" instead of "files" because they can either be physical files stored on your server or links to a remote resource served from a different web server.
    • A downloadable file can either be a local file stored on the server or a remote file via a link.
    • The reason a Releases can have many Items is because you might have compiled the software for multiple operating systems such as Windows, Linux, Mac or Android and each of these will need their own record in ARS but are for the same release. It is also possible that you create documentation in a PDF for this version of the software and that again will need it's own record in ARS and so on.
  5. Update Streams
    • These are the update files builtas either XML or INI files which disemminate the softwares update information
    • Offer updates to your software in two formats: INI files easily usable by any and all programming languages or automatic creation of Joomla! XML extension update streams and JED Remote XML files. As soon as you publish a new version, all your clients using a modern version of Joomla! will be able to automatically upgrade to it. Moreover, the Joomla! Extensions Directory will be notified of the new version and update its listing. No extra file creation or manual action is necessary.

NB: The repository is logically separated to two sub-repositories. By default, they are named "Official Releases" and "Development Releases" https://github.com/akeeba/release-system/wiki/Understanding-the-structure-of-a-repository

Example Usage

The following examples should help you work out how the different areas of ARS fit together.

Here are some example Visual Group > Categories > Releases > Items designs...

QWcrm

  • Visual Group - QWcrm Downloads
  • Categories - QWcrm
  • Releases - QWcrm
  • Items - QWcrm-3.1.2.zip

QWGrabMeta

  • Visual Group - Joomla Downloads
  • Categories - QWCGrabMeta
  • Releases - QWGrabMeta
  • Items - plg_qwgrabmeta-v1.00.zip

Open Source Software

  • Visual Group - Downloads
  • Categories - Software, Documents
  • Releases - Joomla, WordPress, HowTo Documents
  • Items - JoomlaInstall.zip, WordPressInstall.zip, HowToJoomla.pdf

School Documents

  • Visual Group - Documents
  • Categories - Newsletters, Policy Documents, Job Applications
  • Releases - Whole School Newsletter, Sports Newsletter, Maths Newsletter
  • Items - January.pdf, Spring.pdf, SportsDay2012.pdf

Learning Resources

  • Visual Group - Learning Resources
  • Categories - Software, Documents
  • Releases - Gimp, Flash, Word
  • Items - GimpInstall.zip, FlashInstall.zip, MathsResource.doc

Settings Explained

I will go through the different ares of ARS and their settings so i can clear up any missing infromation.

Visual Group

The Visual Group seems to be optional because I created a Category without a Visual Group. A Visual Group should be considered like a section for displaying downloads and is only needed when displaying downloads on the Front-End.

This can only be created from the Control Panel where you will see a icon on the right. For some reason it is not a tab aswell.

  • Title - This is the title of the Visual Group displayed to your site's visitors
  • Published
    • Should it be visible to your users? Set to off to hide the Visual Group from view.
    • There are no other permissions for this feature.
    • This does not affect any of the Categories, Releases or Update Streams availablity
  • Description
    • Use the WYSIWYG editor to type in a description to be displayed for this Visual Group. You can use plugins freely.
    • This can be used to group Normal and BleedingEdge downloads together.

Category

Category management · akeeba/release-system Wiki · GitHub

  • Title - This is the title of the category displayed to your site's visitors
  • Alias
    • The standard Joomla SEF alias and if you leave this blank as it will get filled in automatically.
    • This is the alias (slug) appended to the URL pointing to that category's page. It's best to keep it short and only use lowercase unaccented Latin letters (a-z), numbers (0-9), dashes and underscores. Anything else may behave oddly.
  • Visual Group - Select a Visual Group that you have already created. This is optional.
  • Directory Type
    • Normal - In a Normal directory you have to manually create releases and items.
    • BleedingEdge -In a BleedingEdge directory all subdirectories created in the selected Files Directory will result into new releases being created and published without your intervention. Similarly, files uploaded in the subdirectories will be automatically turned into items and published.
  • Files Directory
    • This is the path to a directory which contains the files to be published in this category's releases.
    • The paths are given relative to your site's root.
    • This is the folder you actually put the software packages in to be downloaded.
    • Example folder names are:
      • qwcrm
      • com_qwcrm
      • plg_qwgrabmeta
      • If you have a version package with multiple items you might consider putting them in the same folder (Normal only, All updatable items in BleedingEdge mode need their own folder).
    • You can not create a category without assigning it a files directory.
    • You can use the same directory in multiple releases.
    • You can use directories in completely different base folders on each release.
    • If a directory doesn't already exists it will not be created, you will see an error message and your category won't be created.
    • Please note that ARS uses Joomla!'s API to filter directories. This limits you to using directories under your site's root.
    • If you want to protect your files from direct web access, please create a .htaccess file with the following content inside your files directory:
  • Published - Should it be visible to your users? Set to off to hide the category from view.
  • Access - The Joomla! access level / view level to apply to the release. You can create custom view levels, effectively choosing which user groups should be granted access.
  • Show unauthorised links - Unauthorised links refers to the downloadable items
  • Subscription Levels
    • This requires Akeeba Subscriptions to be installed.
    • Configure a subscription in Akeeba Subscriptions and then you can limit/control this category by those configured subscriptions.
  • Redirect URL for unauthorised - This option enables the redirect to the specified URL when the download is not authorised.
  • This is software is still supported - If enabled a tag on the frontend will say 'This software is no longer supported' or similiar.
  • Language - Leave set to All for automatic language handling or manually force a specific language.
  • Description - Use the WYSIWYG editor to type in a description to be displayed for this Category. You can use plugins freely.
  • Permissions - This is fine grained permission for the category. Do not change these unless you know what you are doing and need to.

Release

Release management · akeeba/release-system Wiki · GitHub

  • Category - Choose the category where the release will be placed in.
  • Version - Type in the title of this release. Since ARS is optimised for software delivery, we call this field Version, but you may type in anything you want, not just numbers.
  • Alias
    • The standard Joomla SEF alias and if you leave this blank as it will get filled in automatically.
    • This is the alias (slug) appended to the URL pointing to that release's page. It's best to keep it short and only use lowercase unaccented Latin letters (a-z), numbers (0-9), dashes and underscores. Anything else may behave oddly.
  • Maturity - If you are using ARS for software distribution, select the maturity level of this release. The possible options are Alpha, Beta, Release Candidate and Stable.
  • Hits - How many times the release page has been displayed. You can use this field to alter that number. Do note, that you do not need to change it on copied releases; copies will automatically receive a Hits number of zero.
  • Published - Should it be visible to your users? Set to off to hide the category from view.
  • Access - The Joomla! access level / view level to apply to the release. You can create custom view levels, effectively choosing which user groups should be granted access.
  • Show unauthorised links - Unauthorised links refers to the downloadable items
  • Redirect URL for unauthorised - This option enables the redirect to the specified URL when the download is not authorised.
  • Subscription Levels
    • This requires Akeeba Subscriptions to be installed.
    • Configure a subscription in Akeeba Subscriptions and then you can limit/control this category by those configured subscriptions.
  • Released On - The release date for the Release.
  • Language - Leave set to All for automatic language handling or manually force a specific language.
  • Description - Use the WYSIWYG editor to type in a description to be displayed for this release. You can use plugins freely. (First WYSIWYG)
  • Release Notes - Another text field where you can add release notes such as a changelog or specific requirements. (Second WYSIWYG)

Item

Item management · akeeba/release-system Wiki · GitHub

  • Release - Choose the Release to which the Item belongs.
  • Title - The title of the item used to display it to your users. If you are using Automatic Descriptions you don't have to fill it in.
  • Alias
    • The standard Joomla SEF alias and if you leave this blank as it will get filled in automatically.
    • This is the alias (slug) appended to the URL pointing to that category's page. It's best to keep it short and only use lowercase unaccented Latin letters (a-z), numbers (0-9), dashes and underscores. Anything else may behave oddly.
    • Tip: Leave it blank. As soon as you select a file or type in a link, ARS will automatically fill it in before your eyes. Didn't I already mention that ARS is designed to save you lots of time? But please note that ARS will also include the extension of the file (e.g. .zip) in the alias. Unless you've modified your .htaccess to redirect all extensions to Joomla!, this might cause 404 errors. In this case, just edit the automatic alias, removing the dot.
  • Type
    • This decides what type of download type this item has, File or Link.
    • File items allow your visitors to download files stored on your server, the most common case of downloads.
    • Link items allow you to link to a file or even a web page by its URL, internally or externally.
    • Using the Link type will not reveal the URL of the external item to your visitors until they proceed with downloading the item.
  • (Selected File Type Options)
    • Linked item URL - If you chose the Link type, type in the full URL to the file or web page you want to link to. Oh, yes... As soon as you click anywhere outside this field, the Alias will be filled in automatically based on the contents of the URL field if and only if you had an empty alias.
    • Filename - If you chose the File type, this displays a drop down of files found in the category's Files Directory and all of its subdirectories.
  • File size - Type in the file size in bytes. Or don't. If you leave it empty, ARS will try to determine this automatically. In the case of Link items, it will try to download the linked file.
  • MD5 Signature - Type in the MD5 hash of the file. Or don't. If you leave it empty, ARS will try to determine this automatically. In the case of Link items, it will try to download the linked file.
  • SHA1 Signature - Type in the hash of the file. Or don't. If you leave it empty, ARS will try to determine this automatically. In the case of Link items, it will try to download the linked file.
  • SHA-256 Signature - Type in the hash of the file. Or don't. If you leave it empty, ARS will try to determine this automatically. In the case of Link items, it will try to download the linked file.
  • SHA-384 Signature - Type in the hash of the file. Or don't. If you leave it empty, ARS will try to determine this automatically. In the case of Link items, it will try to download the linked file.
  • SHA-512 Signature - Type in the hash of the file. Or don't. If you leave it empty, ARS will try to determine this automatically. In the case of Link items, it will try to download the linked file.
  • Hits - How many times the item has been downloaded. You can use this field to alter that number. Do note that you do not need to change it on copied items; copies will automatically receive a Hits number of zero.
  • Published - Should it be visible to your users? Set to off to hide the category from view.
  • Access - The Joomla! access level / view level to apply to the item. You can create custom view levels, effectively choosing which user groups should be granted access.
  • Show unauthorised links - Unauthorised links refers to the downloadable items
  • Redirect URL for unauthorised - This option enables the redirect to the specified URL when the download is not authorised.
  • Subscription Levels
    • This requires Akeeba Subscriptions to be installed.
    • Configure a subscription in Akeeba Subscriptions and then you can limit/control this category by those configured subscriptions.
  • Environments
    • You can pick from a preconfigured list of software enviroments e.g. Windows, linus, Joomla 1.5, Joomla 3.0 etc..
    • These all have a description and an icon that will get display on this item's page.
    • These Enviroments can be configured from the ARS Control Panel.
  • Update Stream
    • Select which update stream which you want this download to be attached to.
    • I think this is so you can have mulitple versions of the software in one stream i.e. v3.0.0, v3.1.0, v3.1.2....
    • You can save an item without attaching it to a stream.
  • Language - Leave set to All for automatic language handling or manually force a specific language.
  • Description - Use the WYSIWYG editor to type in a description to be displayed for this item. You can use plugins freely.

Update Stream

 Setting up update streams · akeeba/release-system Wiki · GitHub

  • Stream Name
    • A name for the update stream. It can be anything you want and is only used in the Joomla! XML format streams.
    • This is what Joomla! will also display as the Extension Name when it lists new available updates.
  • Alias
    • Used to construct the URL in the front-end.
    • Keep it short and sweet, but definately use something that you choose rather that the autmatic naming as below.
    • The standard Joomla SEF alias and if you leave this blank as it will get filled in automatically.
    • The automatic alias names are as follows updatestreams, updatestreams-2, updatestreams-3 and so on.
  • Extension Type
    • This is used by the Joomla! XML format update stream to description what sort of extension it is.
  • Category
    • The category where we're going to look for updates.
    • You can have more than one update streams per category. However, a single update stream can only look inside a single category.
  • Package naming pattern
    • This is a type of Regex to use to look for files for this Update Stream.
    • An update stream looks for files following a specific naming convention. You have to supply a "shell pattern" in here. This is fancy wording for saying that you provide a filename and use a single question mark (?) to match any single character or a single start (*) to match any number of characters. It's what you already use on your operating system! Only items whose File or URL field matches this pattern will be included in the update stream.
    • For instance, all Akeeba Backup Core installation packages are named com_akeeba-VERSIONNUMBER-core.zip, where only VERSIONNUMBER changes, i.e. com_akeeba-3.1-core.zip, com_akeeba-3.1.5-core.zip etc. This leads us to a naming pattern of com_akeeba-*-core.zip and that's what I would use.
  • Element
    • This is required for Joomla! update streams. It should contain the name of your extension, e.g. com_something, mod_something, plg_something etc.
    • For example, Akeeba Backup Core installs in the com_akeeba directory. This is the element name: com_akeeba
  • Site area (client_id)
    • Since Joomla! 1.7.0, all update streams must indicate the site area (frontend or backend) the extension applies to. For component, library and file extensions you must always use "Backend". For plugins, modules and templates select "Frontend" or "Backend" depending on whether your extension applies to the frontend or the backend of your clients' sites respectively.
    • This is only required for XML update streams. If you are only interested in providing INI update streams, e.g. for desktop software, simply ignore this option.
  • Folder (for plugins)
    • For all extension types except plugins, leave this blank. For plugins, this must be set to the plugin type. For example, if you have a system plugin, type in system in this box. If you have a content plugin, type in content in this box. You get the idea! This is the name of the plugins folder's subdirectory where the plugin is being installed to.
    • This is only required for XML update streams. If you are only interested in providing INI update streams, e.g. for desktop software, simply ignore this option.
  • JED Extension ID
    • This is optional and only needs to be entered for extensions listed in the Joomla! Extensions Directory (JED). This is the numeric ID of your extension as listed in the JED. This is used for the Install from Web feature integration. For more information please take a look at the Content - Akeeba Release System Latest Version plugin which contains the plumbing to actually provide the URLs you need to use for the (quite convoluted) Install from Web feature.
    • If the ID is not set I beleieve then changes to this extesnion will not cause the JED stream to be pushed to the JED.
  • Published - Unpublished streams result in empty pages which is almost the same as disabled but not quite.

 Notes

  • Disabled streams will just return a blank page with a 200 OK code.

Setting Up ARS: A Practical Example

These instructions assume you have installed Akeeba Release System.

1) Create a Primary Repository Folder

NB: This might not be needed if using a download manager such as JDownloads because ARS will only use links. Create it anyway as it won't harm.

You need somewhere for your downloadable files to be stored but ARS does not automatically create the Primary Repository folder or any other folders. Folder creation has to be done manually for some reason however the primary folder only needs to be created once.

  • Using your FTP program log in to your website's FTP and create the following folder in your website root. You can put this folder anywhere you want but within the public filesystem. This setup is my preference only.
    /arsrepo/
  • You now need to prevent direct linking to these files. This step is optional but highly recommended. Create a .htaccess file in your root repository folder /arsrepo/ that you just created above with the following content: 
    <IfModule !mod_authz_core.c>
    Order deny,allow
    Deny from all
</IfModule>
<IfModule mod_authz_core.c>
    <RequireAll>
        Require all denied
    </RequireAll>
</IfModule>

2) Create Your First Update Stream

Now select what type of repository you want and go to that section. (2a) or (2b) and i would recommend (2a) but If you want more automationtion, use the BleedingEdge (2b) option. You should repeat the choosen step as many times as you need but If you only do it once you can come back later for more software.

Although I am using a Non-Joomla software (QWcrm) for this example there is no difference except on that in Update Streams there might be different options for Joomla and Non-Joomla software.

2a) Normal (Category)

The following is a practical example on how to setup your software in ARS so you can get your first update stream working. Once you have done one, everything will be a lot easier to understand.

The option will require manually intervention, such as creating folders, i think?

NB: Visual Group does not seem to do anything, If anyone knows what it is for post a comment

Joomla Extension - com_qwcrm-3.0.0.zip

  • Create a folder /arsrepo/qwcrm/ (This assumes you repository root is /arsrepo/)
  • Upload the file com_qwcrm-3.0.0.zip to /arsrepo/qwcrm/
  • Create a Visual Group (Optional)
    • Title: QWcrm Downloads (or Non-Joomla Downloads)
    • Published: Yes
    • Description: QWcrm software including plugins and modules.
    • Click 'Save & Close'
  • Create a Category
    • Title: QWcrm (or Non-Joomla)
    • Alias: automatically gets filled in
    • Visual Group: QWcrm Downloads (or Non-Joomla Downloads) (optional)
    • Directory Type: Normal
    • Files Directory: arsrepo/qwcrm
    • Published: Yes
    • Access: Public
    • Show unauthorised links: No
    • Subscription Levels: Ignore this setting.
    • Redirect URL for unauthorised: Ignore this setting.
    • This is software is still supported: Yes
    • Language: All
    • Description: These are my releases of QWcrm and related software.
    • Click 'Save & Close'
  • Create a Release
    • Category: QWcrm
    • Version: 3.0.0
    • Alias: automatically gets filled in
    • Maturity: Stable (This assumes it is stable).
    • Hits: ignore this setting
    • Published: Yes
    • Access: Public
    • Show unauthorised links: No
    • Redirect URL for unauthorised: Ignore this setting.
    • Subscription Levels: Ignore this setting.
    • Released On: Todays Date
    • Language: All
    • Description: The Best Open Source Repairs Business CRM program available (First WYSIWYG)
    • Release Notes:This is my initial release. (Second WYSIWYG)
    • Click 'Save & Close'
  • Create an Item
    • Release: 3.0.0
    • Title: QWcrm
    • Alias: automatically gets filled in
    • Type: File
    • File name: com_qwcrm-3-0.0.zip (This will fill in the alias automatically)
    • File Size:
    • MD5 Signature:
    • SHA1 Signature:
    • SHA-256 Signature:
    • SHA-384 Signature:
    • SHA-512 Signature:
    • Hits: ignore this setting
    • Published: Yes
    • Access: Public
    • Show unauthorised links: No
    • Redirect URL for unauthorised: Ignore this setting.
    • Subscription Levels: Ignore this setting.
    • Enviroments: Select the appropriate options from the list.
    • Update Stream: If you already have an Update stream you can select it other wise you have to leave this and come back later after creating it.
    • Language: All
    • Description: Release 3.0.0 of QWcrm
    • Click 'Save & Close' (Upon saving ARS will attempt to calculate and fill in the File Size, MD5 Signature and all of the SHA Signatures).
  • Create an Update Stream
    • Title: QWcrm
    • Alias: automatically gets filled in
    • Extension Type: Components (Files might be the best choice for non-Joomla item, might add my own)
    • Category: QWcrm
    • Package naming pattern: com_qwcrm-*.zip (* = any charcters, ? = any single character)
    • Element: com_qwcrm
    • Site area (client_id) Backend (Because QWcrm is a component the should be set to Backend.)
    • Folder (for plugins): QWcrm is not a plugin so you should just leave empty.
    • JED Extension ID: QWcrm is not listed on the JED so leave empty.
    • Published: Yes
    • Click 'Save & Close' (when you save this might update the Item update stream to match, does not harm to check)
  • Check to make sure that your Category, Release, Item and Update Stream are all published.

2b) BleedingEdge (Category)

BleedingEdge (BE) categories are quite different than the Normal-type categories. You don't have to visit your site's back-end to publish and unpublish releases and items. It all happens automatically whenever you upload or delete files on your server. This can be used in conjuction with Akeeba Release Maker to almost make releasing files a 1 click affair.

  • How the BleedingEdge categories work · akeeba/release-system Wiki · GitHub - This official documentation includes details on how to write your CHANGELOG and a clear explantion of what is going on with a BleedingEdge Category.
  • If you upload a plain text file named CHANGELOG (yes, all caps and no extension), ARS will read it, compare it with the previous releases's CHANGELOG, colorize the result and use that as the ARS Release's description.This implies that you upload raw files and not zip files or I read somewhere it will extract the file and look in it, I have not confirmed this but it seems sensible. You would need to play around with this. Possibly this is uploaded within the release folder. This can be disabled in the Component options.

The following is a practical example on how to setup your software in ARS so you can get your first update stream working. Once you have done one, everything will be a lot easier to understand.

The option is the automated type for developers who do constent releases.

NB: Visual Group does not seem to do anything, If anyone knows what it is for post a comment

Joomla Extension - com_qwcrm-3.0.0.zip

  • To get the automation working you need to enable these plugins in the Joomla Plugins Manager.
    • Akeeba Release System - Bleeding Edge release maturity - Sets the maturity of Bleeding Edge releases based on the folder name suffix (e.g. _BETA for beta releases, _RC for Release Candidates, etc)
    • Akeeba Release System - Bleeding Edge automatic file diff - Automatically generates a colorised unified diff (like what GitHub does) for items automatically created in a Bleeding Edge repository.

The following is mostly the same as (2a) except for the Directory Type whichg is now set to BleedingEdge.

  • Create a folder /arsrepo/qwcrm/ (This assumes you repository root is /arsrepo/)
  • Upload the file com_qwcrm-3.0.0.zip to /arsrepo/qwcrm/
  • Create a Visual Group (Optional)
    • Title: QWcrm Downloads (or Non-Joomla Downloads)
    • Published: Yes
    • Description: QWcrm software including plugins and modules.
    • Click 'Save & Close'
  • Create a Category
    • Title: QWcrm (or Non-Joomla)
    • Alias: automatically gets filled in
    • Visual Group: QWcrm Downloads (or Non-Joomla Downloads) (optional)
    • Directory Type: BleedingEdge
    • Files Directory: arsrepo/qwcrm
    • Published: Yes
    • Access: Public
    • Show unauthorised links: No
    • Subscription Levels: Ignore this setting.
    • Redirect URL for unauthorised: Ignore this setting.
    • This is software is still supported: Yes
    • Language: All
    • Description: These are my releases of QWcrm and related software.
    • Click 'Save & Close'
  • Create a Release
    • Category: QWcrm
    • Version: 3.0.0
    • Alias: automatically gets filled in
    • Maturity: Stable (This assumes it is stable).
    • Hits: ignore this setting
    • Published: Yes
    • Access: Public
    • Show unauthorised links: No
    • Redirect URL for unauthorised: Ignore this setting.
    • Subscription Levels: Ignore this setting.
    • Released On: Todays Date
    • Language: All
    • Description: The Best Open Source Repairs Business CRM program available (First WYSIWYG)
    • Release Notes:This is my initial release. (Second WYSIWYG)
    • Click 'Save & Close'
  • Create an Item
    • Release: 3.0.0
    • Title: QWcrm
    • Alias: automatically gets filled in
    • Type: File
    • File name: com_qwcrm-3-0.0.zip (This will fill in the alias automatically)
    • File Size:
    • MD5 Signature:
    • SHA1 Signature:
    • SHA-256 Signature:
    • SHA-384 Signature:
    • SHA-512 Signature:
    • Hits: ignore this setting
    • Published: Yes
    • Access: Public
    • Show unauthorised links: No
    • Redirect URL for unauthorised: Ignore this setting.
    • Subscription Levels: Ignore this setting.
    • Enviroments: Select the appropriate options from the list.
    • Update Stream: If you already have an Update stream you can select it other wise you have to leave this and come back later after creating it.
    • Language: All
    • Description: Release 3.0.0 of QWcrm
    • Click 'Save & Close' (Upon saving ARS will attempt to calculate and fill in the File Size, MD5 Signature and all of the SHA Signatures).
  • Create an Update Stream
    • Title: QWcrm
    • Alias: automatically gets filled in
    • Extension Type: Components (Files might be the best choice for non-Joomla item, might add my own)
    • Category: QWcrm
    • Package naming pattern: com_qwcrm-*.zip (* = any charcters, ? = any single character)
    • Element: com_qwcrm
    • Site area (client_id) Backend (Because QWcrm is a component the should be set to Backend.)
    • Folder (for plugins): QWcrm is not a plugin so you should just leave empty.
    • JED Extension ID: QWcrm is not listed on the JED so leave empty.
    • Published: Yes
    • Click 'Save & Close' (when you save this might update the Item update stream to match, does not harm to check)
  • Check to make sure that your Category, Release, Item and Update Stream are all published.

This is additional to (2a) for obvious reasons.

  • Upload the Files (ftp or other method).
    • Create a folder /arsrepo/qwcrm/3.0.0_STABLE/
    • Upload com_qwcrm-3.00.zip to /arsrepo/qwcrm/3.0.0_STABLE/
    • Done

Uploading Notes

  • You can automatically create Releases by creating a directory within /arsrepo/qwcrm/
  • You can automatically create Items by creating adding files within a release directory i.e. /arsrepo/qwcrm/3.0.0/ or /arsrepo/qwcrm/3.0.0_BETA/
  • If your rename or delete files/directories then the corresponding ARS records will become unpublished.
  • If you include _ALPHA, _BETA, _RC or _STABLE as a suffix when you create your new directories, ARS will know to initialise the directory's maturity status accordingly. Otherwise your Release will default to ALPHA, and you will have to manually change it as required.
  • The different maturity settings are possibly used by Joomla when you choose the update channel you want.

3) Check The Update Stream Works

You have now successfully created an update stream for you software and you will now see on the Update Streams page a new record for it. On this record you can see the links to your various stream types. Click on the INI link to see if it is working. If you get a message like below something is wrong. Most likely you have not gone back to your new QWcrm Item and selected the new Update Stream. In the examples below you can see where all of the different configurations end up.

Failed INI file

; Live Update provision file
; No updates are available!

Successful INI file

This is an example INI file that is generated by ARS.

; Live Update provision file
; Generated on 2019-11-15 11:29:18 GMT
software="QWcrm"
version="3.0.0"
link="https://quantumwarp.com/index.php?option=com_ars&view=Item&task=download&format=raw&id=1"
date="2019-11-13"
releasenotes="<p>This is my initial release.</p>"
infourl="https://quantumwarp.com/index.php?option=com_ars&view=Items&release_id=1"
md5="f7dbe1333891bdd4e599e3520050bb57"
sha1="cd0361655c6722e667ab42ae275f3068cec96720"
sha256="625a1bfe329438ded94386a50b56d68962f0ab610a1bd300c5de8a8b7cf1beea"
sha384="7c9271509978ea3f8ab252f9c4ad9910568a5c07fd6b5ff068fb3545fb792e912017b73f984867283ecb6c652d8143ff"
sha512="e08b53f359f4ab8d62c87c1fc1b10338446818220182cb46bd4cb68435692b24887707ce114835e27514b9bc080b8b560402e7ae366aca3f449e874960edf02b"
platforms="joomla/3,php/7.3"

Successful XML file

This is an example XML file that is generated by ARS.

<?xml version="1.0" encoding="utf-8"?><!-- Update stream generated automatically by Akeeba Release System on 2019-11-15 11:31:11 GMT -->
<updates>
    <update>
        <name><![CDATA[QWcrm]]></name>
        <description><![CDATA[QWcrm]]></description>
        <element>com_qwcrm</element>
        <type>component</type>
        <version>3.0.0</version>
        <infourl title="QWcrm 3.0.0">
            <![CDATA[https://quantumwarp.com/index.php?option=com_ars&amp;view=Items&amp;release_id=1]]>
        </infourl>
        <downloads>
            <downloadurl type="full" format="zip">
                <![CDATA[https://quantumwarp.com/index.php?option=com_ars&view=Item&task=download&format=raw&id=1&dummy=my.zip]]>
            </downloadurl>
        </downloads>
        <tags>
            <tag>stable</tag>
        </tags>
        <maintainer><![CDATA[QuantumWarp]]></maintainer>
        <maintainerurl>https://quantumwarp.com/</maintainerurl>
        <section>Updates</section>
        <targetplatform name="joomla" version="3"/>
        <client>1</client>
        <folder></folder>
        <ars-phpcompat version="7.3" />
    </update>
</updates>

NB:

4) Create Basic Menu System

These are the a bridged instructions from Setting up your menu items for best results · akeeba/release-system Wiki · GitHub which are worth a read.

  • Create a new 'hidden' menu with these settings (i.e. hidden = dont create a menu module for this menu):
    • Title: ARS Hidden
    • Menu Type: ars-hidden
    • Description: ARS menu structure, do not publish
  • Create our Base menu item for the repository in our new hidden menu:
    • Menu Type: Entire Repository
    • Menu Title: Update Server
    • Alias: updates
  • Create one menu item for each of your ARS Categories. Each menu item needs the following setup:
    • Menu Type: Akeeba Release System, Category View
    • Parent Item: select the menu Entire Repository menu item you created above
  • Create Visible menus. To make these visible to users we shall go ahead and create menu aliases to them in a normal menu
    • Select a normal menu you want this link and create a menu item as follows
    • Menu Item Type: System Links, Menu Item Alias
    • Menu Item: Update Server (In the Menu Item drop-down: Choose one of the ARS Hidden menu items.)
  • Create an Update Stream for each piece of software in the 'ARS Hidden Menu'
    • Create a new menu item of Type XML Stream Feed under the relevant category
    • Select the 'Update Stream' in the 'Basic options' tab.
  • Create an JED Stream for each piece of software in the 'ARS Hidden Menu' if you have published them to the JED.
    • Create a new menu item of Type JED Remote XML under the relevant category
    • Select the 'Update Stream' in the 'Basic options' tab.
    • Submit this new URL to the your JED listing.

NB:

  • I am not use why the menu has to be hidden if you are wondering. You can probably just use the menu published and not bother with 'Menu Aliases'. I suspect it is if you want create XML Stream via menu items.
  • You can just use the non-sef direct URLs that ARS generates and not require menu items for the strems.
  • Select and build your menus as you see fit following the basic format above. Create them in the hidden menu and then use 'Menu Aliases'.
  • Menus are not used to create the XML update streams but you can do if needed. The offcial wiki says "You may have noticed the absence of any reference to JED Remote XML, XML Master Feed, XML Stream Feed and XML Category Feed menu items. Do not create such menu items at all! Due to the way Joomla! routing works you may end up with update URLs that have broken download or information URLs." - I think this applied to old version of Joomla and ARS.
  • You dont need any visible menu items for ARS to work.
  • You cannot add XML to the end of a menu item.
  • The setups of ARS I have seen always use the Non-SEF URLs for their streams.

5) Further Configurations

You should look at these various different settings to see if you need to change any of them.

  • Component options - The standard button at the top right of the component. Various settings in here you need to got through.
  • Enviroments - Tags that are used in the XML update streams to denote the compatible platform. Format: platform name/platform version, e.g. joomla/1.6 for Joomla! 1.6
  • GeoIP Plugin - This needs installing so you can

6) Other ARS Plugins

  • Content - Download ID - Displays the Download ID for the currently logged in user. Use as {downloadid} anywhere in your articles.
  • Button - ARS Item - Displays a button to make it possible to link to ARS download items. Displays a popup allowing you to select an ARS item.
  • System - Akeeba Release System integration with Install from Web - Allows the Akeeba Release System's Latest Release plugin to produce URLs which work with the Install from Web feature introduced in Joomla! 3.2. If a user comes to your site from the Install from Web feature the generated URL will take the user back to their site's Extensions Manager page with the download URL pre-filled. You will need to have both this and the Latest Releases plugins enabled for this feature to work. (Enabled by default)
  • Content - Akeeba Release System Latest Releases - Allows you to display the latest release of a category or generate links to it or specific items under it. (Enabled by default)
  • GeopIP Plugin - Akeeba Release System require an extra plugin to be installed on your site, "System - Akeeba GeoIP provider plugin", in order to be able to determine the country the downloads are started from.

7) Features that need configuring if you want them

  • Automatic item descriptions - Used in conjuction with BleedingEdge you can apply preconfigured item descriptions to specified packages. It is not clear if it is required for BleedingEdge to work.
  • Download IDs - Like a license key. It is a unique hash so a user does not have to be logged it to get a download.
  • GeoIP Logging - Ip to location via a database
  • Amazon S3 integration - Use bandwidth from Amazon.
  • No Access URL - When a user does not have access you can send them to a URL which is better. A fail example is shown below:
    This software is a commercial product and cannot be downloaded directly. The only way to download it is either through your QuantumWarp account or automatically by Joomla! updates with a correctly configured and valid license code in the extension's configuration.

Notes

General

Enviroment Tags

  • If you do not have a Jooma Environment Tag set for an item then the XML stream will not work correctly. The item will be missing from the stream. Information found here Update Screams. In paticular it is the word Joomla in the following example that is the control Joomla/3.0.
  • If you look in ARS code the Environment Tag is used for display control for the various streams. Search for = 'joomla' to find the locations. It is
  • the PHP Tag is the other special case. This is used to set, if found, specific tags in the update stream i.e. <ars-phpcompat version="7.3"/> which are used for the FOF (Akeeba Framework of Frameworks) built into Joomla to determine as to wether that Joomla Servers PHP version is suitable for the update.
Read 1526 times Last modified on Friday, 15 November 2019 15:08
Published in Extensions
back to top