The details
User-space updates
By default a new installation of Jalview will assume it cannot be written to by the launching user, and will store the updatable components of Jalview (which amounts to about 55MB) in a user-space location. The default location varies depending on the OS:
| OS |
default user-space location |
| Windows |
~\AppData\Local\Jalview-Desktop\Jalview_Test\HASH\app |
| macOS |
~/Library/Application Support/Jalview‑Desktop/Jalview_Test/HASH/app |
| Linux |
~/.local/share/jalview-desktop/jalview_test/HASH/app |
| Other |
~/.jalview-desktop/jalview_test/HASH/app |
where HASH is an 8-character SHA256 hash of the installation folder (to distinguish between multiple installations).
Use of these user-space folders can be disabled if desired (see Additional options for headless mode below)
Windows EXE / Linux SH / Unix SH installers
The Windows/Linux/Unix installers are created by install4j, and can be run in GUI mode (the default) or in Console mode (not recommended – the file associations choice stage is not lovely!), or in Unattended mode (the recommended headless installation method). There are existing options documented in the Jalview website Download section (see the Installation notes for each OS) with more detail on the install4j help pages.
Additional options for headless mode
The following additional options can now be used when running the install4j installers in either Console or Unattended mode.
| option |
action |
-a folder |
Install Jalview into folder (the same as install4j’s -dir) |
-U |
Disable user-space updates |
-u template |
Install user-space updates into template instead of the default location |
-S |
Disable all updates |
macOS installer
For macOS we don’t distribute an installer programme, but instead distribute the Jalview.app in a DMG (disk image) file (also made by install4j) that opens in a Finder window with an arrow to suggest the user drags the Jalview.app to the Applications folder where it will be copied. This is a very common and simple way for users to install an application in macOS.
This can still be done by an Administrator, and the default behaviour means that all users on the system will be able to run Jalview.app (with any updates downloaded to their user-space folder).
However, we now also have a bash script, macos-install-jalview.sh, to allow a headless installation of Jalview. Its installation options can be adjusted like the install4j installers. This script can also optionally download the latest version of the DMG for a particular channel (release, test-release or develop), perform a SHA256 check on the DMG file it downloaded, and will then headlessly mount the DMG, copy Jalview.app, and then unmount and delete any downloaded DMG. Alternatively you can tell it to use an already downloaded/created DMG file.
One big advantage the macOS installer script has over using the DMG on its own is that it adjusts all users’ PATH by adding a file /etc/paths.d/Jalview_Test-HASH so that the jalview_test command line is available to all users in their PATH.
The script’s options are:
| option |
action |
-h |
Help (usage statement) |
-d |
Download the latest DMG for the channel |
-i dmgfile |
Use existing dmgfile instead of downloading |
-c channel |
Use channel channel (defaults to release, can also be test-release, develop) |
-a folder |
Install Jalview.app into folder (defaults to /Applications) |
-U |
Disable user-space updates |
-u template |
Install user-space updates into template instead of the default location |
-S |
Disable all updates (if you use -U you probably want this too) |
-y |
Don’t ask for confirmation (probably needed for an automated install) |
There are some other less important options too that you can see in the usage statement (-h).
The user-space path template
One of the options:
| option |
action |
-u template |
Install user-space updates into template instead of the default location |
allows you to change the base of the path that the user-space updates will be downloaded to. The default base path depends on the OS, as detailed above, but there might be a reason (some kind of slow network drive maybe) that you want to change where the user-space updates will be downloaded to. You can set that with the -u option.
The template has various substitutions made to it, and you should include one of these substitutions to avoid collisions of user-space updates:
| value |
substitution |
~/ (at the start) |
User’s home directory/ |
| %u |
User’s username |
| %h |
User’s home directory |
e.g.
-u /tmp/jalview-desktop/%u
will set the user-space updates to install in
/tmp/jalview-desktop/username/jalview_test/HASH/app .
Running the installers in Administrator mode
Windows
For the Windows installer, if you launch the GUI with an Administrator account then it will ask if it can have Administrator privileges. On the command line you must launch it in a Terminal, or equivalent, that already has Administrator privileges.
In Administrator mode the default installation location is
C:\Program Files\Jalview_Test .
This can be changed with the -a option.
Linux/Unix
To run the installer in Administrator mode it must be launched with bash in a root environment, e.g. with sudo:
sudo bash jalview_test-...sh
or in unattended mode:
sudo bash jalview_test-...sh -q
In Administrator mode the default installation location is
/opt/jalview_test .
This can be changed with the -a option.
macOS
macos-install-jalview.sh should be run with sudo:
sudo macos-install-jalview.sh -d -c test-release
to allow Administrator privileges – definitely needed to add a file to /etc/paths.d.
The default installation location is /Applications, which can be changed with the -a option.
https://www.jalview.org/downloads/installers/macos-install-jalview.sh
Download the above file and run
sudo bash ./macos-install-jalview.sh -d -c test-release
to then download and install the latest Jalview Test (which has these features – the release channel doesn’t, so it won’t do any of the things being described here… yet!).
Presently this file isn’t linked to on the Jalview website.
Updating your Jalview installation
When new releases of Jalview come out we highly recommend that your installation should be updated. However this doesn’t mean a re-installation since Jalview already has an updating component (shout out to Getdown!) – it’s just been disabled in the installation folder.
Bundled with Jalview is an updater script that will just run the updating component, headlessly (no splash screen), and without launching Jalview afterwards, for the installation the script is found in.
As with the jalview command line launch there are both bash and PowerShell versions of the update script to ensure cross-platform compatibility. The bash version will work in macOS, Linux, Unix, Cygwin and WSL, and the PowerShell version will work in Windows 10/11 Terminal or Command Prompt (there is a wrapping .bat file that launches the PowerShell script), as well as in macOS and Linux should you have pwsh installed and dare to try!
This script can be found in the installation, and on macOS and Windows (if you didn’t disable the add to PATH option at installation time) it will be in your PATH, so running
jalview_test_update
should find it. If you have multiple installations of Jalview (Test) then you should use a full path to the installation and the script is in the bin folder on Windows and Linux, and in .../Jalview.app/Contents/MacOS on macOS.
It requires one of two options:
| option |
action |
--installation |
updates the installation folder |
--userspace |
updates the user-space folder for the user running the script |
If you are running with --installation then you will need to be in an Administrator mode Terminal on Windows, or use sudo on macOS or Linux, e.g.:
sudo jalview_test_update --installation
or
jalview_test_update --installation on Windows.
If you need a full path, you’ll need to do something like
"C:\Program Files\Jalview Test\bin\jalview_test_update" --installation
Problems/issues
If you run across any problems, niggling issues, or just find something so unintuitive that you couldn’t do it, please comment in this Topic. We will do our best to add functionality 
or fix something broken 
.
Thank you! The 
Team
The unnecessary detail
The -U, -u and -S options in the installers adjust Jalview’s update behaviour by setting certain Java system properties that get passed to the Getdown updater/launcher. These are stored in a file called
On macOS: .../Jalview.app/Contents/vmoptions.txt
On everything else: .../Jalview/jalviewg.vmoptions
and if you want to adjust your settings post-installation, you can uncomment/comment out the system properties that get set in that file. There are notes in the file to figure out what to do.
!