Last updated: 2019-03-26 (Last changes: branch version)
Important changes (2018-06-22): These instructions and the addon repository layout have been highly modified. Please review the updated sections below.
Scipio ERP offers a number of addons available for enterprise clients as well as through Scipio ERP Store. These include functional Addons for social media, web integration and payment providers, as well as alternative backend and frontend Themes.
Addons and Themes, together referred to as “plugins” or “addons” for short, are installed into Scipio ERP using the drop-in addons/ and themes/ component container folders, respectively. These have specially modified framework integration to allow better self-containment and expression of dependencies. Some addons require extra configuration and some may be composed of more than one component, but many can work out-of-the-box.
The official way to integrate addons into your project is using the Git version control system, which allows to customize the addons while maintaining the ability to merge changes from upstream if needed. It is possible to manually drop-in the addons into the project, but this is rarely appropriate except for demoing purposes.
We provide access to Git repositories for the addons. Upon placing an order for an addon or receiving enterprise access, you will be provided with a Scipio ERP Gitlab account, a way to add an SSH key to your account, and a link to the Git repository for the addon.
- Git 2.0 or greater command line client or equivalent (commands may run on older versions, but not recommended) – to determine, run:
git --versionNOTE: Git 2.7 or later is highly recommended
- An SSH agent loaded with your SSH key
- A copy or forked project of Scipio ERP – cloned from Github, the Scipio ERP Gitlab, your own mirror or the address of your forked project
- For the git-addons script: Bash v4 or higher (Linux/Mac; for Windows, Git Bash or Cygwin may need to be used)
Each addon’s Git repository consists of:
- An addon branch for and named after each major Scipio ERP branch: master, 2.x, … (NOTE: in the past, these branches were pre-squashed “full” branches from root; these have been replaced by regular subtree branches)
- Legacy support: several “subtree/[addons|themes]/[component]/[master|2.x|…]” branches – these are exact copies of the [master|2.x|…] branches, provided for backward compability for the time being (NOTE: These may be removed in some time)
Addon layout changes (2018-06-22): The addon repositories have been modified: A new git-addons script is provided to install addons, while the previous “full” addon branches have been removed from the Scipio addon Git repositories, replaced with regular subtree branches instead (simple copies of the “subtree/” branches). So, “master” now contains the same branch/commit as “subtree/[addons|themes]/[component]/master”. The git-addons script removes the need for the previous “full/from-root” squashed branches and simplifies the merging process (see further below). Note that the “subtree/” branches remain for temporary backward-compatibility with user scripts but may be removed in the future.
For example, currently the Ignite Admin theme contains the following branches:
master 2.x subtree/themes/ignite-admin/master subtree/themes/ignite-admin/2.x
These branches are most often single Scipio ERP components, though some may also have more than one contained. They are mainly intended to be added into Scipio ERP working copies at predetermined component directory locations using Git subtrees, with or without the git-addons script detailed below.
In the examples below, you will have to substitute
ssh://.../[addon].git with the addon repository address provided to you, and the
[branch] with the name of the Scipio ERP branch you intend to work with and checkout, or that your project’s branch forked from. You must always use the same branch name for SCIPIO ERP and any addons you merge (i.e. Do not try to install master addon branches into Scipio 2.x branch or installed copy).
You may substitute the address
https://github.com/ilscipio/scipio-erp.git with the Scipio ERP Gitlab ScipioCE address (it is a mirror), your own mirror or the address of your project.
All commands in the sections after this assume that you cloned either your own project forked from Scipio ERP or Scipio ERP itself in case you are preparing to push to a new repo, and you checked out the branch in question. The simplest way to test the instructions below is to simply clone Scipio ERP (but you will have to push the result to another remote afterward):
git clone https://github.com/ilscipio/scipio-erp.git cd scipio-erp git checkout [branch]
To mirror SCIPIO ERP to a git repository of your own, you could do:
git clone --bare https://github.com/ilscipio/scipio-erp.git cd scipio-erp.git git push --mirror https://[my-server-address]/my-scipio-erp-fork.git
and afterward delete the scipio-erp.git folder and re-clone from my-scipio-erp-fork.git.
Addons can be installed with the help of the new git-addons script, or failing that, manually using git subtree commands.
It is also possible to use Git submodules, but they are rarely appropriate for Scipio-based projects and usually not recommended in this context, and so will not be covered here.
Installing addons using the git-addons bash script
As of 2018-06-22, the Scipio ERP Community Edition master branch and upcoming branches contain a simple addon installation Bash script in the project root: git-addons. It requires Bash v4 or higher or compatible environment (for Linux/Mac; for Windows, use or update your Git Bash, Cygwin, etc.).
The script’s main purpose is to add and pull addons into your working copy using git subtree. It merges the squashed addon into your Scipio ERP branch and becomes part of your branch. As such the addon can be edited in-place and if your branch is pushed to a repo and checked out, it will automatically contain the addon (as opposed to git submodules). Further updates are merged in.
Secondarily, the script can also trigger addon configuration and data load.
For help, simply type on the console:
Configuring the git-addons script
Before using the other commands below, if you have purchased an addon from the Scipio store, you must input the base ssh://…/SCIPIO-ERP/ address you received (excluding the addon.git suffix) into the file: git-addons-config, with trailing slash:
You will have to commit the change locally (otherwise the other commands will complain about working copy changes):
git add git-addons-config git commit -m "Updated git-addons-config"
Alternatively to git-addons-config, you can instead set the SCIPIO_ADDONS_URL_EE variable in a file named “git-addons-config-local” in the same directory as git-addons-config (you will need to create the file). The filename git-addons-config-local is under git ignore and therefore does not need to be committed. This is suitable if only one developer is handling the addons for your project.
If you omit setting this address, you will only be able to pull community/public addons from Github.
Using the git-addons script
To get a list of available addons and status of ones installed, as well as the target folders for each addon:
./git-addons list --all
To add the files for a new addon or update an existing one:
./git-addons pull angular-shop
This command will invoke git subtree pull or git subtree add, as appropriate, depending on whether the addon is already installed or not. NOTE: If you add any options (e.g. -e, –dry-run), they must come after the addon name (e.g. ./git-addons pull angular-shop -e).
In addition, the ‘pull’ command will automatically trigger addon configuration, if any is available or needed (this can be prevented by passing –no-config option).
To update all subtree addons in your working copy:
./git-addons pull --all
Note that addon updates will usually prompt you to enter a merge commit message (this can be turned off by passing the -e option to git-addons). If a conflict occurs during pull, you will have to resolve it using the regular Git conflict resolution commands, commit, and re-run the script again to finish updates for the remaining addons (if any more).
After you have pulled an addon, you can optionally load seed and/or demo data for the addon individually using the load-xxxx command:
./git-addons load-demo angular-shop OR ./git-addons load-production angular-shop
Note that you only need to do this if you are adding an addon after you have already seeded your Scipio project using ./ant [load-demo|load-extseed|…] or the install.sh script. If you have not yet seeded the main project, the addon’s data will automatically be included with all others when you seed the main project.
As a shortcut, it is also possible to run ‘pull’ and ‘load-xxxx’ in a single command, ‘install-xxxx’:
./git-addons install-demo angular-shop OR ./git-addons install-production angular-shop
Note that the script can only update addons installed using Git subtree. If you have an addon you installed using a different method, you will have to remove it before running the commands above (and reapply any custom changes afterward). This is because the Git subtree command can only merge in changes to a subtree that it previously added and squashed itself.
Custom git-addons addon definitions
The git-addons-config script file contains the information for all Scipio ERP addons. Most users should not have need to edit or override them.
If you do need custom definitions (e.g., to fork an addon to a different target folder than the default, install multiple modified copies of the same one into different folders, etc.), you can add overrides at the end of the file overriding or adding entries in the
SCIPIO_ADDON_MAP array. The entry format is documented above.
Manual addon installation: Git subtrees
If you are unable to use the git-addons script or run into problems, you may try to add/pull addons manually using git subtree commands directly. Another more thorough explanation of the subtree command can be found here.
The following is an example using the Ignite Admin Theme:
# Add the addon project remote git remote add ignite-admin-theme ssh://.../ignite-admin-theme.git # Add the addon's component as a subtree # NOTE: To get correct target folder (--prefix), consult the output of "./git-addons list --all" git subtree add --squash --prefix=themes/ignite-admin ignite-admin-theme [master|2.x|...] # Later, to update ignite-admin: git subtree pull --squash --prefix=themes/ignite-admin ignite-admin-theme [master|2.x|...]
Note that the
subtree add and
subtree pull commands must always have the same parameters. The squash flag is always necessary for this usage of subtrees. These commands must be re-inputted in full every time because git subtree does not record much information about the subtrees on its own.
Advanced: Some other subtree-like integration methods exist as alternatives to the git subtree command (example using read-tree), each with their strengths and drawbacks; git subtree is simply the most popular, succinct and least error-prone, and as such the only one currently supported in Scipio.