= Bonita Studio installation
:description: How to install a Bonita Studio on Windows, Linux, or Mac operating systems. An OS-independent archive can also be used.

How to install a Bonita Studio on Windows, Linux, or Mac operating systems. An OS-independent archive can also be used.

== Prerequisites

Check the xref:hardware-and-software-requirements.adoc[hardware and software requirements].

=== macOS specific prerequisites

[IMPORTANT]
====
For users of macOS Big Sur 11.0 and above: Only version 7.11.4 and upwards are compatible
====

Only *installed JDK* are accepted by the macOS _gatekeeper_. +
If you try to use a JDK directly downloaded, you will get this kind of error: _jdk-11.0.5 can't be opened because it is from an unidentified developer._ +
The solution is to use an installer to install properly the JDK. The easiest way is to tape the following commands:

[source,bash]
----
# Install brew first if it is not installed yet, more details here: https://brew.sh
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

# Use brew to install a JDK
brew tap homebrew/cask-versions
brew cask install java11
----

Another solution is to download and execute manually the installer, https://adoptopenjdk.net/index.html[here for example].

*Note for users of Windows 10*: the security feature called *SmartScreen* prevents execution of Bonita Studio installer.  When you get the "Windows protect your PC" pop up window, click on "More info" link and click on "Run anyway" button.

== Download Bonita Studio

For a Subscription edition of Bonita Studio, go to the https://customer.bonitasoft.com/download/request[Customer Service Center] and request a download.

For the Community edition of Bonita Studio, go to the Bonitasoft website http://www.bonitasoft.com/downloads-v2[downloads page]. On the download page you will get a download button based on your operating system auto-detection. If you want to download a different version (e.g. switch from 32 to 64-bit version), click on the *Customize you download* link.
On this page there are buttons to download the Studio installer for your current operating system and the _all in one_, OS-independent version. +
To download the installer for a different operating system, select it from the *Operating system* section. +
Then click the *_Download_* button.

When the download is complete, you have one of the following new files:

*Linux* +
Community edition: `BonitaStudioCommunity-x.y.z-x86_64.run` +
Subscription editions: `BonitaSubscription-x.y.z-x86_64.run`

*Windows* +
Community edition: `BonitaStudioCommunity-x.y.z-x86_64.exe` +
Subscription editions: `BonitaSubscription-x.y.z-x86_64.exe`

*Mac* +
Community edition: `BonitaStudioCommunity-x.y.z-macOs.dmg` +
Subscription editions: `BonitaSubscription-x.y.z-macOs.dmg`

*Zip, no Installer (Windows or Linux)*
Community edition

* `BonitaStudioCommunity-x.y.z.zip`

Subscription editions

* `BonitaStudioSubscription-x.y.z.zip`

== Install using a wizard

To run the installer wizard for Linux, Windows, or Mac, double-click the downloaded file.

Then follow the installation wizard through to the end of the installation procedure.

For subscription editions: the installer import workspace feature applies only to local repositories. +
If you have shared repositories in your workspace, you will need to reconnect to these manually, and possibly migrate the processes to your new version of Bonita Studio.
The default workspace is automatically initialized at the end of the installation.

== Install using Zip archive (Windows or Linux)

To install Bonita Studio using the zip archive, unzip the downloaded .zip file to a folder on your hard drive. Avoid using a folder with a long path. Do not use a path that contains spaces.

== Start Bonita Studio

To start Bonita Studio, go to the directory where you installed it, and run the launcher for your operating system:

*Linux* +
Community edition: `BonitaStudioCommunity-linux` +
Subscription editions: `BonitaStudioSubscription-linux`

*Windows* +
Community edition: `BonitaStudioCommunity.exe` +
Subscription editions: `BonitaStudioSubscription.exe`

*Mac* +
Community edition: `BonitaStudioCommunity.app` +
Subscription editions: `BonitaStudioSubscription.app`

== License

This information applies to the Subscription editions. No license is needed for the Community edition.

When you launch Bonita Studio for the first time, you need to install a license:

. Click *_Copy to clipboard_* to copy the request key from the pop-up
. Use the generated request key to request a license on the https://customer.bonitasoft.com/license/request[Customer Service Center]
. *_Check_* your email box (after a few minutes) and open the email from `no-reply@bonitasoft.com`
. *_Download_* the attached file (.lic)
. Go back to your Bonita Studio, click *_Install license..._*, and select your .lic file.

[#enable_cache]

== Configure Bonita Studio to use a specific JVM

Bonita Studio only support Java 8 or 11. If you have multiple versions of Java installed on your computer you might need to specify which Java Virtual Machine (JVM) to use.

To specify the JVM version used to run the Studio you first need to identify the appropriate file to edit. For example if you launch the Studio using `BonitaStudioCommunity.exe`, the file to edit will be `BonitaStudioCommunity.ini`. This file is located in your Studio installation folder.

Next you need to add a -vm option and the path to the Java runtime in the ini file (each of them on a new line). Note the format of the -vm option − it is important to be exact:

* The -vm option and its value (the path) must be on separate lines.
* The value must be the full absolute or relative path to the Java executable, not just to the Java home directory.
* The -vm option must occur after the other Bonita-specific options (such as -product, --launcher.*, etc), but before the -vmargs option, since everything after -vmargs is passed directly to the JVM.

For example on Windows:

[source,ini]
----
-startup
plugins/org.eclipse.equinox.launcher_1.4.0.v20161219-1356.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.1.551.v20171108-1834
--launcher.XXMaxPermSize512m
-vm
C:\progra~1\Java\jre1.8.0_112\bin\javaw.exe
-vmargs
-Xmx512m
-Xms512m
-Dosgi.requiredJavaVersion=1.8
-Dfile.encoding=UTF8
-Dgreclipse.nonlocking=true
-Djava.endorsed.dirs=endorsed
----

[.troubleshooting-title]
== Troubleshooting

[.troubleshooting-section]
--
[.symptom]
Bonita Studio log file

[.symptom-description]
In case of trouble when running Bonita Studio, you might want to take a look at log file.

[.solution]#Where to find Bonita Studio log file.#
Studio log file can be displayed from Bonita Studio in "Help" \-> "Show Bonita Studio log" menu.
Or, in case Studio fails to start, you can open the log file manually. File is named `.log` and is located in `<studio_folder>/workspace/.metadata` folder. +
Note that folder might be hidden and file might not be displayed if you choose to hide file extensions in your file manager.
--

[.troubleshooting-section]
--
[.symptom]
JVM terminated. Exit code=1

[.symptom-description]
If when launching the Studio you get an error message "JVM terminated. Exit code=1" 

[.cause]#Potential cause#
It might be because you try to launch Bonita Studio with a version of the JVM that is not supported. 

[.solution]#Possible solution#
See above "Configure Bonita Studio to use a specific JVM" how to force the JVM to use.
--

[.troubleshooting-section]
--
[.symptom]
OutOfMemory error in Bonita Studio

[.symptom-description]
After installation, you might see an `OutOfMemory` error in Bonita Studio.

[.cause]#Potential cause#
This error sometimes occurs when importing a large process definition. +
The log messages are similar to the following:

[source,log]
----
!ENTRY org.bonitasoft.studio.importer 4 0 2014-04-25 09:43:49.467
!ERROR Import has failed for file Autorisation Engagement Depenses-2.0.bos

!ENTRY org.bonitasoft.studio.importer 4 0 2014-04-25 09:43:49.470
!ERROR
!STACK 0
java.lang.reflect.InvocationTargetException
Caused by: java.lang.OutOfMemoryError: GC overhead limit exceeded
----
[.solution]#Possible solution#
To fix this issue, you need to increase the memory allocated to the JVM that runs Bonita Studio.

Edit the `*.ini` file that corresponds to the executable you use to launch the Studio and modify this line: `-Xmx512m` to `-Xmx1024m` (or higher).

Then restart Bonita Studio.
--

[.troubleshooting-section]
--
[.symptom]
OutOfMemory error in Bonita Studio embedded Tomcat server

[.symptom-description]
When using connectors having a large amount of dependencies.

[.cause]#Cause#
Due to this amount of dependencies, you may encounter some memory issue with the default `-Xmx` used for the tomcat server.

[.solution]#Solution#
You can increase this value in Studio preferences \-> Server settings \-> Tomcat Maximum memory allocation.
--

[.troubleshooting-section]
--
[.symptom]
Bonita Studio installation fail due to JVM errors

[.symptom-description]
A given Bonita Studio version can only run with some specifics Java versions (xref:hardware-and-software-requirements.adoc[hardware and software requirements]). +

[.cause]#Cause#
Issues can be related to bad Java installations, or to incompatibilities between a given Java version and Bitrock (Bitrock is the install builder used to install Bonita, it has the responsibility to detect the JRE used to install Bonita. Some defects on a given version could lead to incompatibility).

[.solution]#Solutions#
If you encounter some issues related to the JVM during the installation, ensure first that a valid Java version is available. You can for exemple type _java -version_ on a terminal, and informations about the main Java version used will be displayed. +
If the problem persists, the easiest way to solve it is to remove the installed Java versions, to download the last stable build of the required Java version https://www.oracle.com/technetwork/java/javase/downloads/index.html[on the Oracle website] and to install it properly. +
--

[.troubleshooting-section]
--
[.symptom]
java.security.cert.CertificateException: No subject alternative DNS name matching github-releases.githubusercontent.com found.

[.symptom-description]
Bonita Studio needs to retrieve some remote assets from Github.

[.cause]#Cause#
If the download of those assets fails with the above exception, it may be due to an out of date install of Java.

[.solution]#Solution#
https://adoptopenjdk.net/[Install] the latest xref:hardware-and-software-requirements.adoc[supported Java] package to fix this issue.
--
