INSTALL.adoc

   1 = Hatch Install Documentation =
   2
   3 This documentation assumes Windows users will use the Hatch Windows
   4 installer.  The xref:linux[Linux]-only steps can also be done on Windows
   5 from a source checkout but are not documented here.
   6
   7 == Windows ==
   8
   9 === Install Java ===
  10
  11 Windows only requires a JRE to run Hatch, not a full JDK.  Download and
  12 install JRE version 1.8 or higher from (for example)
  13 http://java.com/[java.com].
  14
  15 === Install Hatch ===
  16
  17 Execute the 'Hatch-Installer-(version).exe' executable.
  18
  19 NOTE: See installer/windows/README.adoc for building the Windows
  20 installer from Linux or Windows.  When building the Windows installer
  21 on Windows a full JDK is required for compiling.
  22
  23 ==== Optional: Test Hatch ====
  24
  25 [source,sh]
  26 -------------------------------------------------------------------------
  27 C:\>cd %ProgramFiles(x86)%\Hatch
  28 C:\Program Files (x86)\Hatch>hatch.bat test
  29 -------------------------------------------------------------------------
  30
  31 === Install Chrome Extension ===
  32
  33 If the extension was not installed automatically when installing Hatch you can get it directly in the browser from the
  34 https://chrome.google.com/webstore/detail/hatch-native-messenger/ppooibdipmklfichpmkcgplfgdplgahl[Chrome App Store].
  35
  36 === Install Firefox Extension ===
  37
  38 The Firefox extension can not be installed automatically by the native application installer;
  39 https://addons.mozilla.org/en-US/firefox/addon/hatch-native-messenger/[it is available on the Firefox Addons site].
  40
  41 === Continue with xref:using-hatch[Using Hatch] ===
  42
  43
  44 anchor:linux[]
  45
  46 == Linux ==
  47
  48 === Install Java ===
  49
  50 [source,sh]
  51 -------------------------------------------------------------------------
  52 # Debian/Ubuntu version
  53 $ sudo apt-get install openjdk-8-jdk openjfx
  54 -------------------------------------------------------------------------
  55
  56 === Install Hatch ===
  57
  58 [source,sh]
  59 -------------------------------------------------------------------------
  60 $ ./hatch.sh compile
  61 -------------------------------------------------------------------------
  62
  63
  64 === Configure Native Messaging ===
  65
  66 Edit extension/host/org.evergreen_ils.hatch.(chrome|firefox).json and change the "path"
  67 value to match the location of your copy of "hatch.sh", found in the root
  68 directory of the Hatch repository.
  69
  70 Copy the correct host file, changing the filename to org.evergreen_ils.hatch.json, into the browser's configuration directory.
  71
  72 For Chrome:
  73
  74 [source,sh]
  75 -------------------------------------------------------------------------
  76 $ mkdir -p ~/.config/google-chrome/NativeMessagingHosts/
  77 $ cp extension/host/org.evergreen_ils.hatch.chrome.json ~/.config/google-chrome/NativeMessagingHosts/org.evergreen_ils.hatch.json
  78 -------------------------------------------------------------------------
  79
  80 For Chromium:
  81
  82 [source,sh]
  83 -------------------------------------------------------------------------
  84 $ mkdir -p ~/.config/chromium/NativeMessagingHosts/
  85 $ cp extension/host/org.evergreen_ils.hatch.chrome.json ~/.config/chromium/NativeMessagingHosts/org.evergreen_ils.hatch.json
  86 -------------------------------------------------------------------------
  87
  88 For Firefox:
  89
  90 [source,sh]
  91 -------------------------------------------------------------------------
  92 $ mkdir -p ~/.mozilla/native-messaging-hosts/
  93 $ cp extension/host/org.evergreen_ils.hatch.firefox.json ~/.mozilla/native-messaging-hosts/org.evergreen_ils.hatch.json
  94 -------------------------------------------------------------------------
  95
  96 === Install Chrome Extension ===
  97
  98 Install the Chrome exenstion directly from the
  99 https://chrome.google.com/webstore/detail/hatch-native-messenger/ppooibdipmklfichpmkcgplfgdplgahl[Chrome App Store].
 100
 101 === Install Firefox Extension ===
 102
 103 Install the Firefox extension from the
 104 https://addons.mozilla.org/en-US/firefox/addon/hatch-native-messenger/[Firefox Addons site].
 105
 106
 107 ==== Optional: Test Hatch ====
 108
 109 NOTE: print commands are disabled by default in the tests to avoid
 110 unexpected printing but they can be added by un-commenting
 111 them in src/org/evergreen_ils/hatch/TestHatch.java and recompiling.
 112
 113 [source,sh]
 114 -------------------------------------------------------------------------
 115 $ mkdir -p ~/.evergreen
 116 $ ./hatch.sh test
 117 -------------------------------------------------------------------------
 118
 119
 120 anchor:using-hatch[]
 121
 122 == Using Hatch ==
 123
 124 * In Chrome, navigate to the browser staff URL (https://HOSTNAME/eg/staff/).
 125 * Open the Javascript console.  It should show messages like:
 126
 127 [source,sh]
 128 -------------------------------------------------------------------------
 129 Loading Hatch relay content script
 130 ...
 131 sending to Hatch: {"key":"eg.workstation.all","action":"get","msgid":1}
 132 ...
 133 Hatch responded to message ID 1
 134 -------------------------------------------------------------------------
 135
 136 * Enable Hatch features by navigating to
 137   https://HOSTNAME/eg/staff/admin/workstation/hatch.
 138 * To determine if Hatch can see your printer(s), navigate to
 139   https://HOSTNAME/eg/staff/admin/workstation/print/config
 140  ** The "Select Printer" drop-down should show your printer(s).
 141  ** The various printer attribute selectors should show values supported
 142     by the selected printer.
 143
 144 === Optional: Debugging The Chrome Extension ===
 145
 146  * Navigate to chrome://extensions
 147  * Enable "Developer Mode" along the top right of the page.
 148  * Click the "Background Page" link to see the exension console.
 149  * When the extension is loaded (or reloaded), it should show
 150    "Connecting to native messaging host: org.evergreen_ils.hatch"
 151    in the Background Page console with no errors.
 152  * Use the "Reload" link to apply local changes made to the
 153    extension (e.g. extension.js).  (This might only work when installing
 154    the exention manually via developer mode tools).
 155  * See also https://developer.chrome.com/extensions/getstarted
 156