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 extension 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 extension 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 extension manually via developer mode tools).
 236  * See also https://developer.chrome.com/extensions/getstarted
 237