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 Hatch ===
  10
  11 Execute the 'Hatch-Installer-(version).exe' executable.
  12
  13 NOTE: See installer/windows/README.adoc for building the Windows
  14 installer from Linux or Windows.  When building the Windows installer
  15 on Windows a full JDK is required for compiling.
  16
  17 ==== Optional: Test Hatch ====
  18
  19 [source,sh]
  20 -------------------------------------------------------------------------
  21 C:\>cd %ProgramFiles(x86)%\Hatch
  22 C:\Program Files (x86)\Hatch>hatch.bat test
  23 -------------------------------------------------------------------------
  24
  25 === Install Chrome Extension ===
  26
  27 If the extension was not installed automatically when installing Hatch you can get it directly in the browser from the
  28 https://chrome.google.com/webstore/detail/hatch-native-messenger/ppooibdipmklfichpmkcgplfgdplgahl[Chrome App Store].
  29
  30 === Install Firefox Extension ===
  31
  32 The Firefox extension can not be installed automatically by the native application installer;
  33 https://addons.mozilla.org/en-US/firefox/addon/hatch-native-messenger/[it is available on the Firefox Addons site].
  34
  35 === Continue with xref:using-hatch[Using Hatch] ===
  36
  37 anchor:linux[]
  38
  39 == Linux ==
  40
  41 === Download Hatch Sources
  42
  43 [source,sh]
  44 -----------------------------------------------------------------------------
  45 git clone git://git.evergreen-ils.org/Hatch.git
  46 cd Hatch
  47 -----------------------------------------------------------------------------
  48
  49 === Download Java Dependencies
  50
  51 [source,sh]
  52 -----------------------------------------------------------------------------
  53 ./fetch-deps.sh linux
  54 -----------------------------------------------------------------------------
  55
  56 === Compile Hatch ===
  57
  58 [source,sh]
  59 -------------------------------------------------------------------------
  60 $ ./hatch.sh compile
  61 -------------------------------------------------------------------------
  62
  63 === Configure Native Messaging ===
  64
  65 Edit extension/host/org.evergreen_ils.hatch.(chrome|firefox).json and change the "path"
  66 value to match the location of your copy of "hatch.sh", found in the root
  67 directory of the Hatch repository.
  68
  69 Copy the correct host file, changing the filename to org.evergreen_ils.hatch.json, into the browser's configuration directory.
  70
  71 For Chrome:
  72
  73 [source,sh]
  74 -------------------------------------------------------------------------
  75 $ mkdir -p ~/.config/google-chrome/NativeMessagingHosts/
  76 $ cp extension/host/org.evergreen_ils.hatch.chrome.json ~/.config/google-chrome/NativeMessagingHosts/org.evergreen_ils.hatch.json
  77 -------------------------------------------------------------------------
  78
  79 For Chromium:
  80
  81 [source,sh]
  82 -------------------------------------------------------------------------
  83 $ mkdir -p ~/.config/chromium/NativeMessagingHosts/
  84 $ cp extension/host/org.evergreen_ils.hatch.chrome.json ~/.config/chromium/NativeMessagingHosts/org.evergreen_ils.hatch.json
  85 -------------------------------------------------------------------------
  86
  87 For Firefox:
  88
  89 [source,sh]
  90 -------------------------------------------------------------------------
  91 $ mkdir -p ~/.mozilla/native-messaging-hosts/
  92 $ cp extension/host/org.evergreen_ils.hatch.firefox.json ~/.mozilla/native-messaging-hosts/org.evergreen_ils.hatch.json
  93 -------------------------------------------------------------------------
  94
  95 === Install Chrome Extension ===
  96
  97 Install the Chrome exenstion directly from the
  98 https://chrome.google.com/webstore/detail/hatch-native-messenger/ppooibdipmklfichpmkcgplfgdplgahl[Chrome App Store].
  99
 100 === Install Firefox Extension ===
 101
 102 Install the Firefox extension from the
 103 https://addons.mozilla.org/en-US/firefox/addon/hatch-native-messenger/[Firefox Addons site].
 104
 105
 106 ==== Optional: Test Hatch ====
 107
 108 NOTE: print commands are disabled by default in the tests to avoid
 109 unexpected printing but they can be added by un-commenting
 110 them in src/org/evergreen_ils/hatch/TestHatch.java and recompiling.
 111
 112 [source,sh]
 113 -------------------------------------------------------------------------
 114 $ mkdir -p ~/.evergreen
 115 $ ./hatch.sh test
 116 -------------------------------------------------------------------------
 117
 118 === Continue with xref:using-hatch[Using Hatch] ===
 119
 120 anchor:mac[]
 121
 122 == Mac ==
 123
 124 === Download Hatch Sources
 125
 126 [source,sh]
 127 -----------------------------------------------------------------------------
 128 git clone git://git.evergreen-ils.org/Hatch.git
 129 cd Hatch
 130 -----------------------------------------------------------------------------
 131
 132 === Download Java Dependencies
 133
 134 [source,sh]
 135 -----------------------------------------------------------------------------
 136 ./fetch-deps.sh mac
 137 -----------------------------------------------------------------------------
 138
 139 === Compile Hatch ===
 140
 141 [source,sh]
 142 -------------------------------------------------------------------------
 143 $ ./hatch.sh compile
 144 -------------------------------------------------------------------------
 145
 146 === Configure Native Messaging ===
 147
 148 Edit extension/host/org.evergreen_ils.hatch.(chrome|firefox).json and change the "path"
 149 value to match the location of your copy of "hatch.sh", found in the root
 150 directory of the Hatch repository.
 151
 152 Copy the correct host file, changing the filename to org.evergreen_ils.hatch.json, into the browser's configuration directory.
 153
 154 For Chrome:
 155
 156 [source,sh]
 157 -------------------------------------------------------------------------
 158 $ mkdir -p ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/
 159 $ cp extension/host/org.evergreen_ils.hatch.chrome.json ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/org.evergreen_ils.hatch.json
 160 -------------------------------------------------------------------------
 161
 162 For Chromium:
 163
 164 [source,sh]
 165 -------------------------------------------------------------------------
 166 $ mkdir -p ~/Library/Application\ Support/Chromium/NativeMessagingHosts/
 167 $ cp extension/host/org.evergreen_ils.hatch.chrome.json ~/Library/Application\ Support/Chromium/NativeMessagingHosts/org.evergreen_ils.hatch.json
 168 -------------------------------------------------------------------------
 169
 170 For Firefox:
 171
 172 [source,sh]
 173 -------------------------------------------------------------------------
 174 $ mkdir -p ~/Library/Application\ Support/Mozilla/NativeMessagingHosts/
 175 $ cp extension/host/org.evergreen_ils.hatch.chrome.json ~/Library/Application\ Support/Mozilla/NativeMessagingHosts/org.evergreen_ils.hatch.json
 176 -------------------------------------------------------------------------
 177
 178 === Install Chrome Extension ===
 179
 180 Install the Chrome exenstion directly from the
 181 https://chrome.google.com/webstore/detail/hatch-native-messenger/ppooibdipmklfichpmkcgplfgdplgahl[Chrome App Store].
 182
 183 === Install Firefox Extension ===
 184
 185 Install the Firefox extension from the
 186 https://addons.mozilla.org/en-US/firefox/addon/hatch-native-messenger/[Firefox Addons site].
 187
 188
 189 ==== Optional: Test Hatch ====
 190
 191 NOTE: print commands are disabled by default in the tests to avoid
 192 unexpected printing but they can be added by un-commenting
 193 them in src/org/evergreen_ils/hatch/TestHatch.java and recompiling.
 194
 195 [source,sh]
 196 -------------------------------------------------------------------------
 197 $ mkdir -p ~/.evergreen
 198 $ ./hatch.sh test
 199 -------------------------------------------------------------------------
 200
 201 anchor:using-hatch[]
 202
 203 == Using Hatch ==
 204
 205 * In Chrome, navigate to the browser staff URL (https://HOSTNAME/eg/staff/).
 206 * Open the Javascript console.  It should show messages like:
 207
 208 [source,sh]
 209 -------------------------------------------------------------------------
 210 Loading Hatch relay content script
 211 ...
 212 sending to Hatch: {"key":"eg.workstation.all","action":"get","msgid":1}
 213 ...
 214 Hatch responded to message ID 1
 215 -------------------------------------------------------------------------
 216
 217 * Enable Hatch features by navigating to
 218   https://HOSTNAME/eg/staff/admin/workstation/hatch.
 219 * To determine if Hatch can see your printer(s), navigate to
 220   https://HOSTNAME/eg/staff/admin/workstation/print/config
 221  ** The "Select Printer" drop-down should show your printer(s).
 222  ** The various printer attribute selectors should show values supported
 223     by the selected printer.
 224
 225 === Optional: Debugging The Chrome Extension ===
 226
 227  * Navigate to chrome://extensions
 228  * Enable "Developer Mode" along the top right of the page.
 229  * Click the "Background Page" link to see the exension console.
 230  * When the extension is loaded (or reloaded), it should show
 231    "Connecting to native messaging host: org.evergreen_ils.hatch"
 232    in the Background Page console with no errors.
 233  * Use the "Reload" link to apply local changes made to the
 234    extension (e.g. extension.js).  (This might only work when installing
 235    the exention manually via developer mode tools).
 236  * See also https://developer.chrome.com/extensions/getstarted
 237