How to create a packaged version of Archi (including configuration and plugins)
A pre-packaged version of Archi is a package that doesn't require admin-right to be installed or used, already comes with some addtional plugins, and is pre-configured with chosen company defaults (grid size, default icons, defaults fonts and colors...) which is very often needed when team's members collaborate (otherwise each user should follow a written procedure to configure its local Archi install, which is long and error prone).
Reports templates and scripts can optionally be included in a package, which is one less step for end users.
In addition, some simple configuration tricks allow different versions of Archi to be installed at the same time, making it easier to migrate from one version to another (user can use both versions depending on their constraints).
Last, some additional tools can be added depending on your needs (e.g. a command line git client to help troubleshot some potential issues when using coArchi, the collaboration plugin for Archi).
How does this differ from a portable software, and by the way, there is already a "Portable Zip" version on main download page...
A pre-packaged version is not necessarily portable. A portable software is a software which doesn't use OS registry or user profile and thus can be moved easily (including associated user configuration) from one computer to another (usually through a USB key). A pre-package version can (and in an enterprise context will often) make use of OS user profile.
The "Portable Zip" version that you can find on the download page doesn't require administration rights but stores configuration in your user profile which is useful if you often upgrade Archi and expect you configuration to be kept, but is not the intended behavior of a true portable software.
- As soon as Archi is used by one (or more) team and some specific configuration is needed.
- As soon as your company decides to distribute Archi through its official (internal) channels.
This how-to will allow you to build a single executable. During the installation, this self-extractible ZIP archive will prompt you to select the folder in which Archi will be uncompressed. This folder should not be related to a specific version of Archi as it will be used for subsequent updates.
Assuming you've selected C:\ArchiMate as the target folder, you'll end up with a directory structure similar to:
C:\ArchiMate\
|
|--- Archi\
| |--- configuration\
| |--- docs\
| |--- features\
| |--- jre\
| |--- p2\
| |--- plugins\
| |--- Archi.exe
| |--- [...]
.
.
Here is the main flow of operations:
- Setup your workspace
- Start with an official ZIP version of Archi
- (Optional) Add some tools
- (Optional) Use another JVM
- (Optional) Add plugins
- Change default configuration
- (Optional) Use custom certificates
- Build the package
- Test the package
Note: what follows is based on Archi 5.
In the following I will assume that everything is done under a "root" folder named ROOT.
Define a package name that will reflect the version of Archi which is being used. For example Archi-5.0.0. If you plan to add some plugins, you can also add their name: e.g. if you plan to add coArchi and jArchi, the package name could be Archi-5.0.0 - coArchi+jArchi. From now on, I'll use PKGNAME to refer to the chosen package name.
Under ROOT, create an empty folder named after PKGNAME.
If you plan to create a fully portable version:
Under ROOT, create an empty folder named LocalData. You can then provide some custom reports under ROOT\LocalData\jasper-reports, or scripts (if you use jArchi) under ROOT\LocalData\scripts.
Download the "Windows 64-bit Portable Zip" version on the download page. Unzip its somewhere and then move the content of its Archi folder to ROOT\PKGNAME. Make sure that you end up with a folder hierarchy similar to this one (no subfolder named Archi):
ROOT\
|--- PKGNAME\
| |--- configuration\
| |--- docs\
| |--- features\
| |--- jre\
| |--- p2\
| |--- plugins\
| |--- Archi.exe
| |--- [...]
Note: Remember that ROOTand PKGNAME are not actual folder names, but instead refer to the folder names you choose previously.
This step is optional
At this stage, you might want to add some additional tools in your package. If so, I suggest that you create a new folder under ROOT\PKGNAME.
I usually create one named addons containing the following tools:
- A JGit based command line tool (created with Launch4J). Useful to troubleshoot issues related to git repositories when using coArchi. Download it here.
- Notepad2: an old but still very useful and lightweight text editor with syntax highlighting. Here is my configuration file to use Javascript syntax highlighting with jArchi scripts.
- A strip down (and portable) version of WinFontsForAll. It allows user without administration rights to load and use any font. This is especially useful if you rely on some icon fonts or number pill. Download it here.
This step is optional
In some situation, you might want to use a different JVM than the one provided by default with Archi (which comes with the free, HotSpot based, JVM built by AdoptOpenjJDK). In such case, remove the ROOT\PKGNAME\jre folder and replace it with the one from your chosen JVM. This has to be at least Java 17.
I (JB Sarrodie) have personaly tested the OpenJ9 based JVM built by AdoptOpenJDK for more than 6 months. OpenJ9 is supposed to use less memory than other JVM, which might be useful when working on large models with Archi, but the way it manages memory can lead to some issues with jArchi scripts that are memory intensive (for example scripts loading CSV data into memory using Papa Parse library. So I recommend to stick with default (HotSpot) JVM.
This step is optional
If you rely on some plugins (e.g. coArchi, jArchi or some of the plugins developed by Hervé Jouin) you can make them part of your package and deploy them in the dropins folder.
Plugins can come in two format:
- Jar plugins which are simple
.jarfiles ready to be dropped into thedropinsfolder - The official distribution format is based on
.archipluginfiles which are meant to be installed through the Plugins Manager. They can't simply be dropped into thedropinsfolder but have to be unpacked before. To do so, simple replace the.archipluginextension by.zip, extract the content and remove thearchi-pluginfile.
To include plug-ins into your package, simply drop the .jar files into ROOT\PKGNAME\dropins.
Archi comes with its own set of defaults, written in the code, but there is a trick you can use to make sure people will get a specific configuration right from the begining without having to do it manually.
For this, run you own version of Archi and configure it with what you consider being safe defaults for your colleagues.
Then export your current configuration by opening the Preferences and using the "Export" feature:
You should end up with a file similar to this one:
#Thu Jun 25 17:54:44 CEST 2020
\!/=
/instance/com.archimatetool.editor/colorChooser_0=\#027180
/instance/com.archimatetool.editor/colorChooser_1=\#a86f04
/instance/com.archimatetool.editor/colorChooser_10=\#ffffff
/instance/com.archimatetool.editor/colorChooser_11=\#ffffff
/instance/com.archimatetool.editor/colorChooser_12=\#ffffff
/instance/com.archimatetool.editor/colorChooser_13=\#ffffff
/instance/com.archimatetool.editor/colorChooser_14=\#ffffff
/instance/com.archimatetool.editor/colorChooser_15=\#f9f9f9
/instance/com.archimatetool.editor/colorChooser_2=\#52b38d
/instance/com.archimatetool.editor/colorChooser_3=\#ffffff
/instance/com.archimatetool.editor/colorChooser_4=\#ffffff
/instance/com.archimatetool.editor/colorChooser_5=\#ffffff
/instance/com.archimatetool.editor/colorChooser_6=\#ffffff
/instance/com.archimatetool.editor/colorChooser_7=\#ffffff
/instance/com.archimatetool.editor/colorChooser_8=\#00aec6
/instance/com.archimatetool.editor/colorChooser_9=\#fcd385
/instance/com.archimatetool.editor/defaultArchiMateTextPosition=1
/instance/com.archimatetool.jasperreports/JR_ExportOptions=10
/instance/com.archimatetool.jasperreports/JR_Filename=report-filename
/instance/com.archimatetool.modelimporter/ImporterUpdate=true
/instance/com.archimatetool.script/consoleScrollLock=true
/instance/org.eclipse.e4.ui.css.swt.theme/themeid=org.eclipse.e4.ui.css.theme.e4_default6.0,6.1,6.2,6.3,10.0
/instance/org.eclipse.gef/Layout\ Setting=2
/instance/org.eclipse.gef/org.eclipse.gef.psize=191
/instance/org.opengroup.archimate.xmlexchange/ExportXMLExchangeLanguage=en
@com.archimatetool.editor=4.7.0.202005280908
@com.archimatetool.jasperreports=4.7.0.202005280908
@com.archimatetool.modelimporter=4.7.0.202005280908
@com.archimatetool.script=0.7.2.202002281003
@org.eclipse.e4.ui.css.swt.theme=0.12.600.v20200124-0005
@org.eclipse.gef=3.11.0.201606061308
@org.opengroup.archimate.xmlexchange=4.7.0.202005280908
file_export_version=3.0
Now keep only the lines starting with /instance/ and then remove the /instance/ prefix. This should now look like this:
com.archimatetool.editor/colorChooser_0=\#027180
com.archimatetool.editor/colorChooser_1=\#a86f04
com.archimatetool.editor/colorChooser_10=\#ffffff
com.archimatetool.editor/colorChooser_11=\#ffffff
com.archimatetool.editor/colorChooser_12=\#ffffff
com.archimatetool.editor/colorChooser_13=\#ffffff
com.archimatetool.editor/colorChooser_14=\#ffffff
com.archimatetool.editor/colorChooser_15=\#f9f9f9
com.archimatetool.editor/colorChooser_2=\#52b38d
com.archimatetool.editor/colorChooser_3=\#ffffff
com.archimatetool.editor/colorChooser_4=\#ffffff
com.archimatetool.editor/colorChooser_5=\#ffffff
com.archimatetool.editor/colorChooser_6=\#ffffff
com.archimatetool.editor/colorChooser_7=\#ffffff
com.archimatetool.editor/colorChooser_8=\#00aec6
com.archimatetool.editor/colorChooser_9=\#fcd385
com.archimatetool.editor/defaultArchiMateTextPosition=1
com.archimatetool.jasperreports/JR_ExportOptions=10
com.archimatetool.jasperreports/JR_Filename=report-filename
com.archimatetool.modelimporter/ImporterUpdate=true
com.archimatetool.script/consoleScrollLock=true
org.eclipse.e4.ui.css.swt.theme/themeid=org.eclipse.e4.ui.css.theme.e4_default6.0,6.1,6.2,6.3,10.0
org.eclipse.gef/Layout\ Setting=2
org.eclipse.gef/org.eclipse.gef.psize=191
org.opengroup.archimate.xmlexchange/ExportXMLExchangeLanguage=en
Then keep only the lines matching a configuration item which makes sense for you.
If you want you can customize the "Check for Updates..." feature:
- add
com.archimatetool.editor/updateURL=andcom.archimatetool.editor/downloadURL=(empty values) to disable the feature - or set them to the URL you want to use for checking for update (
updateURL) and downloading new version (downloadURL).
If you did add any useful add-ons, make sure you use a relative path. For example, if choose to use Notepad2.exe, you'll most certainly want to add this:
com.archimatetool.script/scriptEditor=.\\addons\\Notepad2\\Notepad2.exe
Save the resulting content in ROOT\PKGNAME\custom_defaults.prefs.
And then edit ROOT\PKGNAME\Archi.ini to make Archi use this as default when running the first time:
-startup plugins/org.eclipse.equinox.launcher_1.6.400.v20210924-0641.jar --launcher.library plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.2.700.v20221108-1024 -cleanConfig --launcher.defaultAction openFile -pluginCustomization custom_defaults.prefs -eclipse.keyring @user.home/AppData/Roaming/Archi/secure_storage -vmargs -Dosgi.requiredJavaVersion=17 -Declipse.p2.data.area=@config.dir/p2 -Ddata.location=@user.home/Documents/Archi --add-modules=ALL-SYSTEM -Dosgi.instance.area=@user.home/AppData/Roaming/Archi -Dosgi.configuration.area=@user.home/AppData/Roaming/Archi/config -Dorg.eclipse.equinox.p2.reconciler.dropins.directory=%user.home%/AppData/Roaming/Archi/dropins
At this stage, you can further customize Archi.ini file:
you can set an alternate splash screen by creating a ROOT\PKGNAME\custom_splash.bmp image (use ROOT\PKGNAME\plugin\com.archimatetool.editor_x.y.z.timestamp\splash.bmp as a template and don't change its size of format) and reference it like that:
-startup plugins/org.eclipse.equinox.launcher_1.6.400.v20210924-0641.jar --launcher.library plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.2.700.v20221108-1024 -cleanConfig --launcher.defaultAction openFile -showSplash custom_splash.bmp -pluginCustomization custom_defaults.prefs -eclipse.keyring @user.home/AppData/Roaming/Archi/secure_storage -vmargs -Dosgi.requiredJavaVersion=17 -Declipse.p2.data.area=@config.dir/p2 -Ddata.location=@user.home/Documents/Archi --add-modules=ALL-SYSTEM -Dosgi.instance.area=@user.home/AppData/Roaming/Archi -Dosgi.configuration.area=@user.home/AppData/Roaming/Archi/config -Dorg.eclipse.equinox.p2.reconciler.dropins.directory=%user.home%/AppData/Roaming/Archi/dropins
By default Archi stores all user configuration files (Archi plug-ins, config, .metadata folder) in an Archi folder located in the AppData/Roaming/ subfolder of the Windows user profile folder (usually C:\Users\user_id) which makes it difficult for users to find it (AppData is a hidden folder).
You might want to make Archi a direct subfolder of the Windows user profile folder:
-startup plugins/org.eclipse.equinox.launcher_1.6.400.v20210924-0641.jar --launcher.library plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.2.700.v20221108-1024 -cleanConfig --launcher.defaultAction openFile -eclipse.keyring @user.home/AppData/Roaming/Archi/secure_storage -vmargs -Dosgi.requiredJavaVersion=17 -Declipse.p2.data.area=@config.dir/p2 -Ddata.location=@user.home/Documents/Archi --add-modules=ALL-SYSTEM -Dosgi.instance.area=@user.home/Archi -Dosgi.configuration.area=@user.home/Archi/config -Dorg.eclipse.equinox.p2.reconciler.dropins.directory=%user.home%/Archi/dropins
Note that Archi stores all user data (jArchi scripts, Jasper report templates, coArchi repositories) in a C:\Users\user_id\Documents\Archi folder so you may not need to change this.
Please see the wiki for more on editing the Archi.ini file.
This step is optional
If some of your plugins rely on SSL/TLS certificates, you have can add them to the ROOT\PKGNAME\jre\lib\security\cacerts:
- Open a Windows command shell (you can use the
WIN Rkeyboard shortcut to open the "Run" box, entercmdand press Enter) - Go the the
ROOT\PKGNAME\jre\binfolder - Enter the following command:
.\keytool -keystore ..\lib\security\cacerts -importcert -alias <alias> -file <certificate_filename>, where<alias>is a short description of the certificate to be added, and<certificate_filename>is the full path to the certificate. - Type the password for the keystore at the “Password” prompt and press Enter. The default Java password for the
cacertsfile is “changeit”.
The best way to create the package is through 7-Zip. Note: screenshots are in french and should be re-created using 7-Zip EN version
Open 7-Zip and go the the ROOTfolder (you can see PKGNAME folder):
Select the folder containing package content and clic on "Add" (green cross icon):
Use '7z' as archive format and select option to create an "SFX archive" (SelF eXtractible). Then validate.
Congratulation, you now have a packaged version of Archi.
Backup any existing content you have in your Archi folder and remove it. Then run your package executable, select a target folder to unzip it. Once uncompressed, go to the newly created folder and run Archi.exe from here. You see Archi starts and use your default configuration. In case of issues, double check this procedure and try again. If this still fails, don't hesitate to open a thread on Archi's forum.