This is a guide intended to help you install and manage the Bio-Prodict 3DM YASARA Plugin.

Index

Basic (recommended)

Installing the YASARA 3DM Plugin

The recommended way to install the YASARA 3DM plugin is by using the version that comes with your YASARA distribution. This ensures that the version of YASARA is compatible with the version of your plugin.

If you already have YASARA installed we recommend that you still follow this procedure to update YASARA. You need to have the latest version of the YASARA plugin to complete the course and work with 3DM effectively.

1.  Retrieve and install YASARA from the YASARA downloads page. Every YASARA download comes with the 3DM plugin pre-packaged.
   
   
2. Activate the 3DM plugin. This can be done using the Help > Install > 3DM Plugin menu option. You must restart YASARA after the installation has finished.
   
   1. If the 3DM button does not appear, please verify that Python 2.7 has been installed. It can be installed using the Help > Install > Python menu option.
      
      
3. Check the installation. To verify that the plugin works correctly, please confirm that the top menu bar contains the 3DM menu. If it is listed, you can verify the installation completely by Clicking on 3DM > Info > About Bio-Prodict 3DM. When a screen comes up with information about the plugin, the installation was completed successfully. The latest stable version number can be found here.
   
   1. If the 3DM menu is listed, but no screen shows up after clicking About Bio-Prodict 3DM, please scroll down to the bottom of the page for troubleshooting information.

Advanced

Installing the YASARA Plugin (Manual)

If you want to update your plugin installation yourself without reinstalling YASARA, you can update the plugin yourself. Note: if your installation was mediated by the Bio-Prodict team, this is the recommended installation process.

1. Locate the installation directory of YASARA on your computer.
2. Use your file explorer to navigate to this directory.
3. Open the plg directory.
4. Download the latest stable plugin from our website.
5. Open the 3dm_plugin_yasara_stable.zip archive.
6. Open the plg directory inside the archive.
7. Select the contents of the archive (this should be 1 file and 1 folder)
8. Copy the selected files into the plg directory of YASARA. If your computer asks you whether you wish to overwrite files, answer Yes.
9. Restart YASARA

Your YASARA installation is now updated to the latest stable version.

Using the YASARA plugin with a proxy

Using the YASARA plugin with your proxy is easier than ever with our integrated proxy settings screen. You can find this settings screen under 3DM > Info > Set proxy information. You do not need to be logged in to set your proxy settings. Simply enter your HTTP(S) proxy urls in the text fields, click Test proxy to verify your proxy works, and click OK to apply the settings. You do not need to restart YASARA for the settings to take effect.

If you encounter an error while testing your proxy settings, contact your system administrator. After you have successfully adjusted your settings, YASARA will show a message confirming the adjustment. If your settings have remained unchanged, you will be notified as well. You can always find the currently applied proxy settings by looking at this menu. The text field headers will show the currently active proxy settings.

If you have proxy settings defined as environment variables (for example, if you previously used the old method of setting proxy information) these will take precedent over the those set in the built-in menu. Administrators can adjust the proxy adresses manually by adjusting the .PROXIES file in the 3DM plugin directory.

Proxy troubleshooting

I entered the correct proxy server, but testing results in an error with code 407.
Your proxy requires authentication information to proceed. You may need to retrieve this information from your IT department. Please enter the proxy information in the following format:

http://<username>:<password>@<proxy_server>/
https://<username>:<password>@<proxy_server>/

I am required to connect to a proxy, but the proxy settings screen does not pop up/is empty.
Automatic update checking is turned off and our plugin cannot detect the need for a proxy. Please turn on automatic update checking in the configuration file, or enter the proxy information in the .PROXIES file. (see below)

I would like to automatically transfer the proxy information.
The plugin gathers its proxy information from the .PROXIES file, situated in the directory where YASARA is run from. It will be automatically created when you click "Apply proxy settings." You can transfer this file between computers and between versions, or create it yourself. It is formatted like this (username and password optional):

{
	"http": "http://<username>:<password>@<proxy_server>/",
	"https": "https://<username>:<password>@<proxy_server>/"
}

Linux

In Linux, it depends on your shell, e.g. bash users can add it to the ~/.bashrc file. If you launch YASARA with a desktop shortcut, please consult the documentation of your Linux distribution how environment variables are set there.

http_proxy="http://yourproxy.yourdomain.com:3128"
export http_proxy
https_proxy="http://yourproxy.yourdomain.com:3128"
export https_proxy

OSX 10.8+ / macOS

In MacOSX 10.8 and newer, environment variables must be added to the file /etc/launchd.conf, e.g. the following entry:

setenv http_proxy http://yourproxy.yourdomain.com:3128
setenv https_proxy http://yourproxy.yourdomain.com:3128

NOTE that due to a MacOSX caching problem you may have to reboot your computer after making the change. Type 'env' in a terminal to verify it worked.

OSX 10.7 and older

In MacOSX 10.7 and older, you can add them to the .MacOSX/environment.plist file, like in the following example:

<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
 "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>http_proxy</key>
  <string>http://yourusername:yourpassword@yourproxy.yourdomain.com:3128</string>
  <key>https_proxy</key>
  <string>http://yourusername:yourpassword@yourproxy.yourdomain.com:3128</string>
</dict>
</plist>

NOTE that due to a MacOSX caching problem you may have to reboot your computer after making the change. Type 'env' in a terminal to verify it worked.

Instructions have been copied (with small alterations) from the YASARA documentation.

SSL Errors

If you encounter the following error:

bioprodict.shared.vendors.requests.exceptions.SSLError: hostname 'api.bio-prodict.nl' doesn't match either of 'bio-prodict.com', 'bio-prodict.nl', 'bioprodict.com', 'bioprodict.nl', 'www.bio-prodict.com', 'www.bio-prodict.nl', 'www.bioprodict.com', 'www.bioprodict.nl'

It appears that the version of Python that is installed on your system is does not support SNI. Version 2.7.10 or higher is required to run the plugin, in order to ensure a safe connection between our servers and your computer.

Windows

Linux

If problems persist/Version retrieval errors

You may also encounter an error that starts with "Unable to retrieve version information.", like this:

Windows

Adjusting API URLs in the configuration

If you are running a 3DM installation on a server that is not hosted by Bio-Prodict, you will need to change the configuration of the plugin to speak to that server. To do so, you will need to alter the plugin configuration file the YASARA plugin loads. There are two ways of doing this.

Note: please contact your systems provider in order to get the correct URLs for your configuration before starting either procedure.

Basic method

Currently, this procedure will need to be run every time the plugin is updated, as the default configuration is included as part of the plugin. It is, however, rather simple to perform.

1. Open your favorite plain-text editor (notepad, gedit, kate...)
2. Find the configuration file. It is located here: 
   <YASARA Directory>/plg/bio-prodict/config.json
3. It is recommended that you make a backup of the config.json file, so you can quickly and easily revert to the previous settings.
4. Open the config.json file with your editor.
5. Replace each of the URLs in this file with the proper URL for your server.
6. Save the file and exit your text editor.
7. Restart YASARA to have the settings take effect.

If you have entered a wrong URL, YASARA will alert you of that fact when you start using the 3DM plugin.

Advanced method

This method will only need to be applied once, but is more involved. You may need experience with the command line for your operating system.

1. Find the configuration file. It is located here: 
   <YASARA Directory>/plg/bio-prodict/config.json
2. Copy this file to another directory where you have write and read access.
3. Using your favorite plain-text editor, replace the urls in the copied file with the proper urls for your server.
4. Save the file and exit your editor.
5. When starting YASARA from here on out, start it with the THREEDM_PLUGIN_CONFIG environment variable pointing to the location of the copied file you created.
• For Linux and Mac OSX, this involves launching YASARA from the terminal like this:THREEDM_PLUGIN_CONFIG=/path/to/config.json <YASARA Directory>/yasara
• In Windows, you can either set a System Environment Variable, or create a shortcut to the YASARA executable with the THREEDM_PLUGIN_CONFIG variable set. You can also use PowerShell to launch YASARA with the variable.

If you have entered a wrong URL, YASARA will alert you of that fact when you start using the 3DM plugin.

Troubleshooting

I can see the 3DM menu, but nothing happens when I click a menu option.

Please check that you have the correct version of Python installed. The 3DM YASARA Plugin relies on Python 2.7 being available on your system. To install the proper version of Python, please visit the Python Downloads page and download the latest version of the 2.7.xx series.

After the download has finished, start the installer. During the installation process you will be presented with a list of components. At the bottom of this list the option "Add python.exe to your PATH" is demarkated by a red cross. Click this component and select "This feature will be installed to the local hard disk" (the first option). Continue the installation as normal.

After restarting YASARA, the plugin should function as expected.