INSTALL.adoc

   1 = Hatch Install Documentation =
   2
   3 This documentation assumes Windows users will use the Hatch Windows
   4 installer.  The Linux-only steps can also be done on Windows, but
   5 are not documented here.
   6
   7 == Install Java ==
   8
   9 === Windows ===
  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://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html[oracle.com].
  14
  15 === Linux ===
  16
  17 [source,sh]
  18 -------------------------------------------------------------------------
  19 # Debian/Ubuntu version
  20 $ sudo apt-get install openjdk-8-jdk openjfx
  21 -------------------------------------------------------------------------
  22
  23 == Install Hatch ==
  24
  25 === Windows ===
  26
  27 Execute the 'Hatch Installer.exe' executable.
  28
  29 NOTE: See installer/windows/README.adoc for building the Windows
  30 installer from Linux or Windows.  When building the Windows installer
  31 on Windows, the full JDK will be required (for compiling Java).
  32
  33 === Linux ===
  34
  35 [source,sh]
  36 -------------------------------------------------------------------------
  37 $ ./hatch.sh compile
  38 -------------------------------------------------------------------------
  39
  40 ==== Optional: Test Hatch ====
  41
  42 NOTE: print commands are disabled by default in the tests to avoid
  43 unexpected printing, but they can be added by un-commenting
  44 them in src/org/evergreen_ils/hatch/TestHatch.java and recompiling.
  45
  46 [source,sh]
  47 -------------------------------------------------------------------------
  48 $ mkdir -p ~/.evergreen
  49 $ ./hatch.sh test
  50 -------------------------------------------------------------------------
  51
  52 == Install Chrome Extension [Windows & Linux] ==
  53
  54 . Open Chrome/Chromium and navigate to chrome://extensions
  55 . Enable "Developer Mode" along the top right of the page.
  56 . Click the "Load Unpacked Extension..." button.
  57 . Load the directory at Hatch => extension => app
  58 .. In Windows, the default location for the app directory will be
  59    C:\Program Files (x86)\Hatch\extension\app
  60
  61 === Optional: Debugging The Chrome Extension ===
  62
  63  * Click the "Background Page" link to see the exension console.
  64  * When the extension is loaded (or reloaded), it should show
  65    "Connecting to native messaging host: org.evergreen_ils.hatch"
  66    in the Background Page console with no errors.
  67  * Use the "Reload" link to apply local changes made to the
  68    extension (e.g. main.js).
  69  * See also https://developer.chrome.com/extensions/getstarted
  70
  71 === Linux: Configure Native Messaging ===
  72
  73 Edit extension/host/org.evergreen_ils.hatch.json and change the "path"
  74 value to match the location of your copy of "hatch.sh", found in the root
  75 directory of the Hatch repository.
  76
  77 Copy the host file into Chrome's configuration directory.
  78
  79 For Chrome:
  80
  81 [source,sh]
  82 -------------------------------------------------------------------------
  83 $ mkdir -p ~/.config/google-chrome/NativeMessagingHosts/
  84 $ cp extension/host/org.evergreen_ils.hatch.json ~/.config/google-chrome/NativeMessagingHosts/
  85 -------------------------------------------------------------------------
  86
  87 For Chromium:
  88
  89 [source,sh]
  90 -------------------------------------------------------------------------
  91 $ mkdir -p ~/.config/chromium/NativeMessagingHosts/
  92 $ cp extension/host/org.evergreen_ils.hatch.json ~/.config/chromium/NativeMessagingHosts/
  93 -------------------------------------------------------------------------
  94
  95 == Using Hatch ==
  96
  97 NOTE: At time of writing, the Evergreen server used must have the
  98 patches included in the
  99 http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/berick/lp1646166-hatch-2.12-omnibus[Hatch 2.12 Omnibus Branch].
 100
 101 * In Chrome, navigate to the browser staff URL (https://HOSTNAME/eg/staff/).
 102 * Open the Javascript console.  It should show messages like:
 103
 104 [source,sh]
 105 -------------------------------------------------------------------------
 106 Loading Hatch relay content script
 107 ...
 108 sending to Hatch: {"key":"eg.workstation.all","action":"get","msgid":1}
 109 ...
 110 Hatch responded to message ID 1
 111 -------------------------------------------------------------------------
 112
 113 * Enable Hatch features by navigating to
 114   https://HOSTNAME/eg/staff/admin/workstation/hatch.
 115 * To determine if Hatch can see your printer(s), navigate to
 116   https://HOSTNAME/eg/staff/admin/workstation/print/config
 117  ** The "Select Printer" drop-down should show your printer(s).
 118  ** The various printer attribute selectors should show values supported
 119     by the selected printer.
 120