LP#1434728: make password_required configurable per library
[sitka/overdrive-evergreen-opac.git] / README.txt
1 The source code for the project is written in Coffeescript.
2
3 The source needs to be completed by writing a od_config.coffee file to define
4 configuration parameters, primarily related to authentication. Use the template
5 file 'od_config_template.coffee' by following its instructions.
6
7 The source also needs to be compiled into Javascript and minimized on a
8 development machine before executable code can be deployed on a production
9 server.
10
11
12 A. Prerequisites, development machine
13
14 1. Install nodejs.org
15
16 2. Install node packages
17 # sudo npm install --global coffee-script
18 # sudo npm install --global requirejs
19
20
21 B. Production Deployment
22
23 1. Put yourself at top-level project directory.
24
25 2. Compile source files from Coffeescript to Javascript
26
27 (long form)
28 # coffee --compile --bare --output app src
29
30 (short form)
31 # coffee -cb -o app src
32
33 3. Minify Javascript files
34 # r.js -o build.js
35
36 4. Deploy minified files to production server
37 # rsync -e 'ssh -l sitkastaff' -azv build/overdrive.js servername.domainname:/var/tmp
38
39 On production server:
40 # sudo chown opensrf:opensrf /var/tmp/overdrive.js
41 # sudo mv /var/tmp/overdrive.js /srv/openils/var/web/js/ui/default/opac
42
43
44 C. Configuration of Web Service
45
46 1. Add the following script tag to /srv/openils/var/templates/opac/parts/js.tt2.
47
48 <script type="text/javascript"
49     src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.1.10/require.min.js"
50     data-main="[% ctx.media_prefix %]/js/ui/default/opac/overdrive.js">
51 </script>
52
53 2. Define the file /etc/apache2/mods-available/proxy_http.conf, with the
54 following contents.
55
56 <IfModule mod_proxy_http.c>
57     SSLProxyEngine On
58     ProxyPass        /od/oauth        https://oauth.overdrive.com
59     ProxyPassReverse /od/oauth        https://oauth.overdrive.com
60     ProxyPass        /od/oauth-patron https://oauth-patron.overdrive.com
61     ProxyPassReverse /od/oauth-patron https://oauth-patron.overdrive.com
62     ProxyPass        /od/api          http://api.overdrive.com
63     ProxyPassReverse /od/api          http://api.overdrive.com
64     ProxyPass        /od/api-patron   http://patron.api.overdrive.com
65     ProxyPassReverse /od/api-patron   http://patron.api.overdrive.com
66     ProxyPass        /od/images       http://images.contentreserve.com
67     ProxyPassReverse /od/images       http://images.contentreserve.com
68     ProxyPass        /od/fulfill      http://fulfill.contentreserve.com
69     ProxyPassReverse /od/fulfill      http://fulfill.contentreserve.com
70 </IfModule>
71
72 3. Ensure that the proxy_http module is enabled.
73
74 # cat /etc/apache2/mods-available/proxy_http.load
75 > LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so
76
77 4. Gracefully restart the Apache web service.
78
79 # sudo service apache2 graceful
80
81
82 D. Web Browser
83
84 Reload the browser at http://libraryname.servername.domainname/eg/opac/home, to
85 run the home page of the OPAC.  Ensure that the browser's cache is disabled.
86 By monitoring the network traffic, you should see new JS and CSS files load, in
87 the following approximate sequence.
88
89 require.min.js
90 overdrive.js
91 jquery.min.js
92 lodash.min.js
93 cookies.min.js
94 json3.min.js
95 moment.min.js
96 jquery-ui.min.js
97 jquery-ui.min.css
98
99
100 E. Development Cycle
101
102 During development, you will cycle between compiling source files, deploying
103 unminified files, and testing.
104
105 - Run the compiler in watch mode and as a background process.
106
107 # coffee -cbw -o app src &
108
109 - Edit a file. It will be compiled automatically via the background process.
110
111 - Deploy unminified files in app directory to the test server.  (A convenient
112   way is to upload the files to /var/tmp/od/ and to symbolically link each file
113   to the target directory, /srv/openils/var/web/js/ui/default/opac.)
114
115 # rsync -e 'ssh -l sitkastaff' -azv app/ servername.domainname:/var/tmp/od
116
117   On servername.domainname machine, repeat for each js files:
118
119 # sudo ln -s /var/tmp/od/overdrive.js /srv/openils/var/web/js/ui/default/opac
120
121 - Reload your browser, https://libraryname.servername.domainname, to run the
122   modified files.  Ensure that the browser's cache is disabled.