Installing
There are two ways to install the appliance: "Complete" and "Package-Only". We expect that most Windows/Mac OSX desktop users will follow the Complete install procedure. The packaged versions of the iDigBio Media Appliance will also install the Anaconda Python environment. If you are wondering why that last sentence is talking about snakes, it's probably the case that you do not run Python programs and probably safe to go ahead and run the Complete install. If you use any other Python programs or applications, and are familiar with installing python packages, you should run the Package-Only install. If you are somewhere in between, or unsure and need help determining how best to install the appliance in your environment, please contact the iDigBio Technical Team ([email protected]) with a subject line "iDigBio Media Appliance - help request".
Supported browsers include recent Firefox and Chrome. The use of Internet Explorer and Microsoft Edge are strongly discouraged due to a number of known compatibility issues.
Supported operating systems:
- Linux (64-bit)
- Mac OS X (64-bit version 10.4.7+, Tiger or later)
- Microsoft Windows (32- and 64-bit Windows 7 or later)
After completing one of the sets of install instructions below, a functioning iDigBio Media Appliance screen should appear in your system's default browser at http://localhost:5000/
When first running the appliance you will need to enter an "Account Alias" of your choice, and the UUID and API Key that you were given. The account alias will appear in the "previous user" dropdown box on subsequent executions of the appliance.
If you do not yet have an API key, please email your request to the [iDigBio Technical Team ([email protected])](mailto:[email protected]?subject=Request for API Key - iDigBio Media Appliance) with a short description of the intended use, which collection(s) and organization(s) are involved, etc.
Open https://github.com/idigbio/idigbio-media-appliance/releases/latest in another tab or window in your browser so you can keep these instructions open.
The Complete Install includes a full Anaconda-based installation of Python, libraries, and the Media Appliance itself. Most users will likely choose this option.
Under the Downloads heading, choose the file that matches your operating system. Only download the 64 bit package (Windows-x86-64) if you are sure that you are running 64 bit Windows. The 32 bit package (Windows-x86) should work on both 32 and 64 bit versions of Windows.
The Windows packages are executable (.exe) installer programs. Download the .exe to your computer and run the program to proceed through the installation steps. For the vast majority of users, the default options are correct.
The following screenshots walk through the Windows installer screens.
After the installation is finished you are ready to launch the iDigBio Media Appliance via the included batch file (.bat). In most Windows installations, you can do this by running "idigbio_media_appliance".
For example, open the Start Menu and type into the "Run..." or "Search programs and files" box:
idigbio_media_appliance
or, if Windows folder options are configured not to "Hide extensions for known file types" the program name will appear as:
idigbio_media_appliance.bat
If you installed the appliance for just the current user (this is the default in the Installer), the idigbio_media_appliance.bat file is located in the "Scripts" folder under the "iDigBioMediaAppliance" folder inside the user profile, typically "C:\Users<username>\iDigBioMediaAppliance\Scripts\idigbio_media_appliance.bat"
If you want to create a shortcut on the desktop you would enter "idigbio_media_appliance" or "idigbio_media_appliance.bat" into the "command to run" box.
Running the batch file should open a command prompt, start some programs in the background, possibly download some updated helper programs, and then direct your default browser to a web page pointed at the iDigBio Media Appliance local web app running on your own computer at http://localhost:5000/
It may take a while before the web page is visible for the first time.
Supported browsers include recent Firefox and Chrome. The use of Internet Explorer (IE) is strongly discouraged due to a number of known compatibility issues.
If your default browser is IE and the appliance opened in an IE browser window, copy and paste the localhost URL into a supported browser. Close the initial IE tab or window.
To close the appliance once you are done using it (and all uploads have finished), close the browser tab with the appliance in it, then click the X box in the upper right hand corner of the appliance command prompt window.
On Mac OS X, installation of the media appliance require some minor use of the terminal. You should not require administrative privileges to install the appliance with the default options.
Watch a screencast of the installation process here.
Under the Downloads heading, choose the file that matches your operating system (MacOSX). Once it is done downloading, open the Terminal window (either by navigating to the Applications Folder or by typing Terminal into spotlight).
At the terminal prompt type the following to change into the directory you downloaded the file to (the default should be Downloads). If you downloaded the file to another location (eg. Desktop), you will need to change directory to that location instead.
cd Downloads
To find out what version you downloaded type (or copy and paste):
ls iDigBioMediaAppliance-*MacOSX-x86_64.sh
That should return a list of file names with the asterisk in the previous command replaced with a number, eg. that should look like iDigBioMediaAppliance-2.0.6-MacOSX-x86_64.sh . Pick the file name with the largest number, and use that name for the following commands.
Then, to enable the installer to run, type (using the file name from the above command):
chmod +x iDigBioMediaAppliance-<version number>-MacOSX-x86_64.sh
Then, to run the installer type (again, using the file name above) :
./iDigBioMediaAppliance-<version number>-MacOSX-x86_64.sh
This will print out a serious of questions in the terminal. You should read over them just to make sure, but in most cases the default answers will be fine and you can accept them by pressing the ENTER key.
Once this is done, you can close the terminal window with the installer.
After installation, you can run the appliance by typing the following into spotlight search:
idigbio_media_appliance
Or opening up a terminal window and typing:
idigbio_media_appliance
Either of these methods should open your default browser to the appliance home page. To close the appliance, just close the terminal window in which the appliance in running.
On Linux, installation of the media appliance require some minor use of the terminal. You should not require administrative privileges to install the appliance with the default options.
Under the Downloads heading, choose the file that matches your operating system (Linux). Once it is done downloading, open a terminal window.
At the terminal prompt type the following to change into the directory you downloaded the file to (the default should be Downloads). If you downloaded the file to another location (eg. Desktop), you will need to change directory to that location instead.
cd Downloads
To find out what version you downloaded type (or copy and paste):
ls iDigBioMediaAppliance-*Linux-x86_64.sh
That should return a list of file names with the asterisk in the previous command replaced with a number, eg. that should look like iDigBioMediaAppliance-2.0.6-Linux-x86_64.sh . Pick the file name with the largest number, and use that name for the following commands.
Then, to enable the installer to run, type (using the file name from the above command):
chmod +x iDigBioMediaAppliance-<version number>-Linux-x86_64.sh
Then, to run the installer type (again, using the file name above) :
./iDigBioMediaAppliance-<version number>-Linux-x86_64.sh
This will print out a serious of questions in the terminal. You should read over them just to make sure, but in most cases the default answers will be fine and you can accept them by pressing the ENTER key.
After installation, you can run the appliance by opening up a terminal window and typing:
idigbio_media_appliance
Either of these methods should open your default browser to the appliance home page. To close the appliance, just close the terminal window in which the appliance in running.
The iDigBio Media appliance is also distributed as a python package. If you already have a version of python 2.7 or 3.5 installed on your machine, you can install the iDigBio Media Appliance with pip (skip the sudo if you're installing to a virtual environment):
$ sudo pip install idigbio-media-appliance
Some of the dependencies of the appliance may require the ability to compile software. Specifically you may need a C compiler, the Python development libraries, and the libevent development package. On ubuntu getting these would look like:
$ sudo apt-get install build-essential python-dev libevent-dev
Once the appliance is installed you will be able to run it with the executable script:
$ idigbio_media_appliance
This should open your default browser window, pointed at http://localhost:5000/ , where the appliance web server is running.
To exit the appliance, just CTRL-C the process in the terminal.