
          Qube! Installer


The Qube installer is a Wizard-style installation utility that will
download and install Qube! components.  It has pre-defined component
selections based on the role this computer will fill.  A typical worker
will simply select "worker" from the component selection page.  A
typical client machine (artist workstation) will choose "client".  

The installer is designed to be run on a machine with a working internet
connection.  After components have been downloaded, the installer can be
run again on other machines without accessing the internet, assuming the
files that were previously downloaded are visible to the new machine.

A typical install should require very little user input - simply walk
through the pages until you have finished.  The final page will give you
several wrap-up options based on the actions of the installer.

Note that you must have administration privileges to install software.
For Windows users, you may want to right-click > "Run as
Administrator". For Linux users, you must run as root or a sudoer.  macOS
users will be prompted to enter an admin password before installation
begins. 

Use the "Light mode" / "Dark mode" button at the bottom of the wizard
to switch its appearance.

Command-line (non-GUI) mode: running the installer with a kickstart
(.qks) file, or with --upgrade <manifest file>, installs without the
wizard.  On Linux and macOS this must be run as root or with sudo; on
Windows, as an administrator.  Run with --help for all options.



Pages in the installation wizard:


-- Introduction Page --

A welcome message


-- License Agreement Page --

End-user license agreement for all Qube! components.  By agreeing to
these terms, you are agreeing to the terms for all of the components you
will install.


-- Select Package Manifest Page --

The first time you run the installer, after agreeing to the license,
you will be presented with a page that will allow you to choose the
version of Qube you wish to download.  By default, you will choose the
most recent version that is available on the PFX Internet repository.
This will be displayed next to the "Use PFX Internet repository" radio
button.  You can use the same drop-down to select an older version that
is available on the repository, or choose the "Use local manifest
(qmf/qmx) file" option and choose a previously downloaded manifest
file.  We recommend that you always use the most up-to-date manifest for
the given version.  Note that the manifest file creation dates are
displayed in this dialog.  If you choose a local manifest file, be sure
that its creation date is at least as new as the PFX repository's file
for that same version.

If you use the PFX Internet repository, you will be prompted to choose a
directory when you click the "Next" button.  This is the directory that
will be used to hold the manifest file and installation files for each
of the Qube components you choose to download.

If you choose the Local qmf file option, you will be prompted to select
the location of your previously saved qmf/qmx.  Note: There is only one
manifest file per Qube! release - the single file covers all operating
systems, so there is no need to use separate manifest files if you will
be installing Qube! on multiple operating systems.

If the manifest has no entry matching this computer's OS, the "OS
Selection" drop-down shows "Select alternate..."; choose the closest OS
from the list.  On macOS this is always the case with manifests from
Qube! 8.0 and earlier.


-- Component Selection Page --

This page allows you to determine the role of this computer.  You should
be able to simply choose a pre-defined role from the left-hand column
and click "Next". Doing so will automatically select the required
components from the "Component" column & disable components that may be
incompatible with the selected role. 

The "Current" column shows the version of the component that is already
installed on this computer, if any.

The "Final" column shows the version of the component after the
installer completes.  A red 'X' in this column signifies that the
component will be uninstalled.


If you choose to do a "Custom" install, components that are already
installed on your system will get tri-state check boxes, with the third
state signifying that you want to uninstall that component.

At the bottom of this page, you will see the installer attempting to
communicate with your supervisor (if one is running).  It then helps you
with configuration based on what it finds.  Possible scenarios:

- Supervisor found and you are not installing another supervisor:
This is expected.  You can continue to the next page

- No supervisor found, but you are installing a supervisor:
This is expected.  You can continue to the next page

- Supervisor found on the local machine and you are upgrading:
This is expected.  You can continue to the next page

- Supervisor found on another machine and you are installing a second
  one on the local machine:
You will be challenged to give an alternate qb_domain value.  This will
then be written to the local qube configuration to prevent the two
supervisors from trying to communicate with the same workers.  If you
choose not to do this, you may have multiple supervisors running on
the same qb_domain.  This will cause the farm to behave unexpectedly
and will largely halt rendering across all nodes on the farm.

- No supervisor found, but one is running on your network that you will
be using:
This means auto-discovery of the supervisor failed. This is most
likely due to the supervisor being on a different subnet than the
local machine, though there are several other reasons this could
happen. When you click next, you will be challenged for the name/ip
address of your existing supervisor. After you give this information,
you will be taken back to the component selection page which will then
attempt to find the supervisor again. If it finds it, the correct
parameters will be added to Qube's configuration files after
installation.  If it does not, the process will repeat until you
either find the supervisor or ignore this step.  Ignoring this step
will likely mean this computer will not connect to the supervisor and
vice versa


-- Download / Verify Page --

This page will download all requested Qube components.  The files will
be stored in directories named after the OS for which they were made.
The OS directories will be stored next to the manifest file.  The
manifest file will be stored in the directory that was selected on the
"Package Manifest Selection" page.

If the components have already been downloaded, they will not be
re-downloaded unless their md5 sums have changed (as would be the case
for an update).

When a download is complete (or the file is found to already exist),
the file's md5 sum will be checked.  If the md5s match, a green check
mark will be displayed next to the progress bar.  If something went
wrong with the md5 or if a download did not complete, simply click next
& you will be asked if you would like to retry the download.


-- Install / Uninstall Page --

This page will do the actual install/uninstall.  When a component is
installed, the version number of the installed package will be displayed
next to the progress bar.  If a version number shows "(NC)", it was
neither installed nor uninstalled, as the version that was requested to
be installed is the same as was already on the system.


-- Final Page --

This page is context sensitive depending on the type of work the
installer was asked to do.  Possibilities:

If you...
Installed a worker:
- You will have 3 test buttons:
  - Submit basic test job - this will test basic operation of this
  worker on your farm.  Job status will be reported next to the button
  when the job completes.
  - Submit file read test job - You will be prompted to choose the path
  to any file.  This should be a file on your file server.  We want to
  see if this worker, running in service mode, can see the file server.
  As before, job status will be displayed next to the button.
  - Submit file write test job - You will be prompted to choose a
  directory in which Qube can create a file.  This directory should be
  on your file server.  As before, job status will be displayed next to
  the button.
*If any of these jobs fail, check your network settings/permissions,
then you may want to contact support@pipelinefx.com for further
instructions.

Installed a GUI:
- You will get a "Launch Qube! UI" button.  This will launch that
interface, but be warned, it will run as the user who is running the
installer.  On Linux, this will be root or a sudoer.

Installed anything:
- You will see a "View online documentation" button.  If clicked, a
browser will open with the correct URL for Qube's online docs.  Be
warned: the browser will open as the user who is running the installer.
On Linux, this will be the root user.

Uninstalled everything:
- On macOS & Linux, you will see buttons that will remove Qube users from
this machine, if the uninstalled components created any users during
their installation process.
- If you uninstalled a worker or supervisor, you will see buttons that
will remove log directories.  Note: this process could take a very long
time on very busy supervisors.  If you plan on re-installing Qube, it
would be advisable not to remove the existing logs.
- If you uninstalled a supervisor, you will see a "Remove Qube database"
button.
- If you uninstalled everything, you will see buttons that will remove
all PFX directories from this computer.


The final page may show warnings about Perl and Python if you are
installing a worker on a Windows computer that does not have Perl or
Python installed.  While Perl and Python are not necessary for Qube to
function, many of Qube's jobtypes use Perl and/or Python.  Without the
language, those jobtypes will not function.

