Installation

Prerequisites

Zegami has been successfully run on many systems of differing specifications. At a minimum Zegami can run on a reasonably low powered machine. A low spec machine will have a minimal impact on the performance of the client as most of the processing occurs within the Browser.

Minimum Hardware Recommendation

Tables can't be imported directly. Please insert an image of your table which can be found here.

What is impacted by the processing capabilities of the server is the time take to process the collection cache. Collection processing is CPU and disk intensive, meaning that the greater the number of CPU’s and the faster the disk the faster collections will be processed. Ultimately it comes down to how often the data will need to be reprocessed and what is considered to be a reasonable processing time. A collection that takes 20 hours to process may be acceptable if the actual data only changes once a week.

Zegami can either be hosted on a physical machine, visualized or cloud based.

Storage Requirements

The amount of storage required depends on the size of the initial collection of images (if there is a one-to-one relationship between items and images). In general the amount of space required is 2.5 to 3 times more than the original size of the source images.
It is recommended that the processing cache be stored on SSD’s to maximize performance.

Supported Operating Systems

Zegami has been tested on and fully supports the following:

  • Windows Server 2012 R2 (2008 R2 coming soon)
  • Windows 10
  • Windows 8.1
  • Ubuntu 16.04
  • Ubuntu 14.04
  • CentOS 7

Please note: Other Linux distros may also work, but have not been tested and are therefore unsupported.

Before installing the following prerequisites are required.

Storage

Zegami Server will require write access to a directory which is used to store processed collections and their associated data. For best performance this location should be local to the server running Zegami. The default location created on install is C:\Zegami\collections on Windows and /zegami/collections on Linux. A second folder that requires backup is the data directory for mongodb. By default this is found in C:\Zegami\Data on Windows and /zegami/mongodb_data on Linux.

These directories can be changed by editing the settings.conf file.

Windows Software Prerequisites

If the ODBC data source plugin is required (used to query relational databases as a source of data for Zegami) then the appropriate ODBC driver must be installed.

Linux Software Prerequisites

If the ODBC data source plugin is required (used to query relational databases as a source of data for Zegami) then the appropriate ODBC driver must be installed.

Windows Installation

The Windows installation package has been specifically built to make installation and configuration as automated as possible.

Once installed Zegami will be up and running and ready to create collections. While most common deployments will be satisfied with the default settings, more complicated scenarios may require additional configuration.

Prerequisites

Before installing the following prerequisites are recomended:

Service Accounts

The Zegami server and it's related services need to run under a user account. On Windows the default account used on installation the LocalSystem account. This is a highly privileged user and is suitable for simple installations and testing.

For production deployments it is strongly recommended that in production that a dedicated service account be used with minimum permissions.

See the section on updating the service accounts for more details.

Storage

Zegami Server will require write access to a directory which is used to store processed collections and their associated data. For best performance this location should be local to the server running Zegami. On installation a default location at C:\Zegami\collections is created, however this can be changed.

Installation

To begin installation run the supplied installer Zegami-[VERSION]-Windows-x86_64.exe (where [VERSION] is the latest version number).


Click Next > and accept the Licence Agreement.


The installation will then begin. Depending on the version of Windows and previously installed software a reboot may be required. Once restarted the installation will continue.


Once installation is complete, click Finish to complete.


Zegami is now installed and ready to use!

On Windows 8.1 and 10 you can access Zegami at http://localhost

On Windows Server Zegami uses Internet Information Services (IIS) and is available at http://localhost:5159 (port 5159 has been selected so that it does not conflict with other web applications that may already be running. The port can be changed via IIS Manager).


(OPTIONAL) Updating Service Accounts

When changing the service account used by Zegami's services the account will need READ and WRITE permissions on the following directories:

  • C:\Program Files\Zegami\Lib\site-packages\zegami
  • C:\Zegami

Depending on the data sources required for collections the Zegami service account will also require read permission to the data sources. For example if the CSV data source is used for a collection, the Zegami service account will need to have read access to the location of the CSV data file. In the case of an ODBC data source the service account will need read access to the database.

Once the account is ready, update the Log On User for the Zegami Scheduler Service, Zegami Log Service, Zegami Cluster Service and Zegami Web Service (Windows Desktop only)

  1. Open the Services SnapIn
  2. Right click the service and select Properties
  3. Select the Log On tab
  4. Select the This account radio button and set the username and password of the new service account.
  5. Accept the dialog granting the account "Log On as a service" permission if displayed.
  6. Close the properties dialog and restart the service.

For Windows Server deployments the IIS App Pool account will also need to be changed.

  1. Open IIS Manager
  2. In the tree view expand the Server node and select Application Pools.
  3. Right click the Zegami Application Pool and select Advanced Settings...
  4. Select the ... next to the Identity property
  5. Select the Custom account radio button and set the new service account credentials.
  6. Close the properties dialog and recycle the Application Pool

Troubleshooting

The default logging location is located at C:\Zegami\Logs and contains log files for the database, services and web server. The services also log to the Windows Application Event Log. If problems occur these logs can be useful when contacting support.

Linux Installation

The Linux installation package has been specifically built to make installation and configuration as simple as possible.

After installation Zegami will be up and running and ready to create collections. While most common deployments will be satisfied with the default settings, more complicated scenarios may require additional configuration.

Installation

The installer has been tested with Ubuntu 16.04 and CentOS 7. If installing on CentOS, some additional setup may be required if the networking does not work, see Preparing A CentOS VM to install Zegami.

Once the install package has been downloaded, extract it using the archive manager on your OS or at the command line with:

tar -xvf zegami-linux.tgz

For Ubuntu 16.04 and CentOS 7, the installation package, once extracted, contains an installation script called linux-install.sh. This can be used for automatic installation of packages, a webserver (nginx), MongoDB and the uWSGI python server.

Once extracted run the following to start the installation process.

sudo bash linux-install.sh

There are a set of options which can be configured on install of Zegami. These can be altered in the file zegamiscripts/settings.sh before you run the installer.

The installation process will install the Zegami appication to /opt/zegami, create a collection data directory at /zegami and configure related permissions.

It will then start all Zegami related services, create an initial test collection and set up the initial admin user. Once installation is complete the final output with initial users details will be displayed like the following.


...
zegami_nginx: started
zegami_uwsgi: started
zegami_services: started
settings up demo collection

====== Collections ======
found 2 lines
Demo collection created succesfully

====== Creating Collection ======

Name: xenopus
Url: /xenopus
ID: 57a476ac2cff4d7bb61df22c
Total Items: 324
Last Processed: 2016-08-05 12:21:24.304798
Data Source URL: /api/collections/57a476ac2cff4d7bb61df22c/datasource.tsv
Deep Zoom URL: /api/collections/57a476ac2cff4d7bb61df22c/dz/57a476ac2cff4d7bb61df22d/collection.json
Snapshot URL: /api/collections/57a476ac2cff4d7bb61df22c
Setting the demo.html file
settings setup

User successfully created

=========================================================
A user has been created to access the administration portal
Your username is admin158
Your password is ODVlM2U2NDHl

The Zegami service consists of 5 python processes that are marshalled by the supervisord process control tool. Logging and data processing are grouped as one process so 4 of these services currently have their own config files for supervisor. These config files are put in place during the installation in the default supervisor configuration folder (/etc/supervisor/conf.d).

You can verify that the 4 processes are up and running typing the following at the terminal:

sudo supervisorctl

This should look as follows:

sudo supervisorctl
zegami_nginx RUNNING pid 5271, uptime 8:40:23
zegami_services RUNNING pid 5272, uptime 8:40:23
zegami_uwsgi RUNNING pid 5273, uptime 8:40:23
supervisor>

At the supervisorctl prompt you can see a realtime view of the logs from a process by running:

tail -f zegami_nginx

Installation complete


If installation completed successfully and the services have been confirmed as running then you can launch Zegami by navigating to [http://localhost](http://localhost).

Full or Trial License Web interface (Zegami Manager)

If you have a full or trial license you will see a username and password at the end of the installation output that looks like this:


User successfully created
=========================================================
A user has been created to access the administration portal
Your username is admin158
Your password is ODVlM2U2NDHl


The username and password are diplayed in the terminal. in the example above the username is admin158 and the password is ODVlM2U2NDHl.

Use these to log in to the administration portal via the login form at http://localhost

Web interface for CLI installs (Academic License)

Upon launch of the index page from an academic license install you will see the standard web server index page including demo.html.

Before running the CLI for the first time the PATH needs to be set to the zegami python interpreter. Which can be set by running export PATH="/opt/zegami_python/anaconda/bin:$PATH". This will be done automatically if you open a new terminal window.

Zegami Server Configuration

By default, the Zegami server will be running once installed. Further details on how the server can be configured are located in Server Configuration.

Authentication Security

If using the LocalAuth authentication plugin, please ensure to configure SSL for encryption of payload data.
This is done automatically as part of the install process.
If you would like to it again with different details or add a comercial SSL certificate, the details can be changed in hte below script and it can be run again as shown.

To create a self signed certificate run the folowing:


cd zegamiscripts
sudo su -c "bash create_ssl_certificate.sh" zegami