-
Notifications
You must be signed in to change notification settings - Fork 1
/
index.html
274 lines (208 loc) · 11.2 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>
File: README
— Documentation by YARD 0.9.25
</title>
<link rel="stylesheet" href="css/style.css" type="text/css" />
<link rel="stylesheet" href="css/common.css" type="text/css" />
<script type="text/javascript">
pathId = "README";
relpath = '';
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>
</head>
<body>
<div class="nav_wrap">
<iframe id="nav" src="class_list.html?1"></iframe>
<div id="resizer"></div>
</div>
<div id="main" tabindex="-1">
<div id="header">
<div id="menu">
<a href="_index.html">Index</a> »
<span class="title">File: README</span>
</div>
<div id="search">
<a class="full_list_link" id="class_list_link"
href="class_list.html">
<svg width="24" height="24">
<rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
<rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
</svg>
</a>
</div>
<div class="clear"></div>
</div>
<div id="content"><div id='filecontents'>
<p><a href="https://circleci.com/gh/yalelibrary/yul-dc-blacklight/tree/master"><img src="https://circleci.com/gh/yalelibrary/yul-dc-blacklight/tree/master.svg?style=svg"></a> <img src="https://github.com/yalelibrary/yul-dc-blacklight/workflows/Docker%20Image%20CI/badge.svg"></p>
<h1 id="label-Yale+Digital+Library+Discovery+Application">Yale Digital Library Discovery Application</h1>
<p>This is one of the microservices applications that form the Yale digital library.</p>
<h2 id="label-Development+guide">Development guide</h2>
<h3 id="label-Prerequisites">Prerequisites</h3>
<ul><li>
<p>Download <a href="https://www.docker.com/products/docker-desktop">Docker Desktop</a> and log in</p>
</li></ul>
<h3 id="label-Docker+Development+Setup">Docker Development Setup</h3>
<h4 id="label-If+this+is+your+first+time+working+in+this+repo+or+the+Dockerfile.base+has+been+updated-2C+-28re-29build+the+base+service+-28dependencies-2C+etc.+that+don-27t+change+often-29">If this is your first time working in this repo or the Dockerfile.base has been updated, (re)build the base service (dependencies, etc. that don't change often)</h4>
<pre class="code ruby"><code class="ruby">docker-compose build base
</code></pre>
<h4 id="label-If+this+is+your+first+time+working+in+this+repo+or+the+Dockerfile+has+been+updated+you+will+need+to+-28re-29build+those+services">If this is your first time working in this repo or the Dockerfile has been updated you will need to (re)build those services</h4>
<pre class="code ruby"><code class="ruby">docker-compose build
</code></pre>
<h3 id="label-Starting+the+app">Starting the app</h3>
<ul><li>
<p>Start the blacklight service</p>
</li></ul>
<p><code>bash docker-compose up </code></p>
<ul><li>
<p>Access the blacklight app at <code>http://localhost:3000</code></p>
</li><li>
<p>Access the solr instance at <code>http://localhost:8983</code></p>
</li><li>
<p>Access the image instance at <code>http://localhost:8182</code></p>
</li><li>
<p>Access the manifests instance at <code>http://localhost</code></p>
</li></ul>
<h3 id="label-Accessing+the+blacklight+container">Accessing the blacklight container</h3>
<ul><li>
<p>Navigate to the app root directory in another tab and run:</p>
</li></ul>
<p><code>bash docker-compose exec blacklight bash </code></p>
<ul><li>
<p>You will need to be inside the container to:</p>
</li><li>
<p>Run migrations</p>
</li><li>
<p>Access the seed file</p>
</li><li>
<p>Access the rails console for debugging</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_bundle'>bundle</span> <span class='id identifier rubyid_exec'>exec</span> <span class='id identifier rubyid_rails'>rails</span> <span class='id identifier rubyid_c'>c</span>
</code></pre>
</li><li>
<p>Run rubocop</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_bundle'>bundle</span> <span class='id identifier rubyid_exec'>exec</span> <span class='id identifier rubyid_rubocop'>rubocop</span> <span class='op'>-</span><span class='id identifier rubyid_a'>a</span>
</code></pre>
</li><li>
<p>Run rspec</p>
<pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_bundle'>bundle</span> <span class='id identifier rubyid_exec'>exec</span> <span class='id identifier rubyid_rspec'>rspec</span>
</code></pre>
</li><li>
<p>Rebuild the code documentation</p>
<pre class="code ruby"><code class="ruby">bundle exec rake yale:docs:blacklight
</code></pre>
</li></ul>
<h3 id="label-Indexing+data">Indexing data</h3>
<ul><li>
<p>First, connect to the running management application container:</p>
</li></ul>
<p><code>bash docker-compose exec management bash </code></p>
<ul><li>
<p>Then, on that running management container:</p>
</li></ul>
<p><code>bash SOLR_CORE=blacklight-core bundle exec rake yale:index_fixture_data </code></p>
<h2 id="label-Pushing+new+images+to+Dockerhub">Pushing new images to Dockerhub</h2>
<h3 id="label-If+you-27ve+made+modifications+to+Dockerfile.base-3A">If you've made modifications to Dockerfile.base:</h3>
<ol><li>
<p>Update the base services</p>
</li></ol>
<p><code>bash docker-compose build base </code></p>
<ul><li>
<p>When the base services are finished building the last line should say "Successfully tagged yalelibraryit/dc-blacklight-base:<code><image-name></code>". e.g.:</p>
<pre class="code ruby"><code class="ruby">Successfully tagged yalelibraryit/dc-blacklight-base:v1.0.0
</code></pre>
</li><li>
<p>That tagged image being referenced is the newest image that's currently available on DockerHub. You can verify that by:</p>
<ul><li>
<p>Going to <a href="https://hub.docker.com/orgs/yalelibraryit/repositories">hub.docker.com/orgs/yalelibraryit/repositories</a></p>
</li><li>
<p>Clicking the arrow icon at the far right of the line that says "yalelibraryit / dc-blacklight-base"</p>
</li><li>
<p>Selecting the "Tags" button next to "General"</p>
</li><li>
<p>Sort by "Newest" in the drop down on the right side of the window</p>
</li></ul>
</li><li>
<p>Create a new image tag from the updated base services build</p>
</li><li>
<p>The <code>docker tag</code> command takes 2 arguments:</p>
<ul><li>
<p>The first argument is the newest tag that's currently in DockerHub that you saw above in step 1</p>
</li><li>
<p>The second argument is the tag you want to assign the new image</p>
</li><li>
<p>In order to properly tag the new image, increment the appropriate place value by one. e.g.:</p>
</li></ul>
<p> <code>bash docker tag yalelibraryit/dc-blacklight-base:v1.0.0 yalelibraryit/dc-blacklight-base:v1.0.1 </code></p>
</li><li>
<p>Sign in to Docker from your command line</p>
</li></ul>
<p><code>bash docker login </code></p>
<ul><li>
<p>You'll be prompted to enter your Docker username and password</p>
</li><li>
<p>Push the base image with your incremented version tag. e.g.:</p>
</li></ul>
<p><code>bash docker push yalelibraryit/dc-blacklight-base:v1.0.1 </code></p>
<ol><li>
<p>Build the blacklight services</p>
</li></ol>
<p><code>bash docker-compose build </code></p>
<ul><li>
<p>When the blacklight services are complete there will be a line that says "Successfully tagged yalelibraryit/dc-blacklight:<code><image-name></code>". e.g.:</p>
<pre class="code ruby"><code class="ruby">Successfully tagged yalelibraryit/dc-blacklight:master
</code></pre>
</li><li>
<p>Create a new image tag from the updated blacklight services build</p>
</li><li>
<p>Your first argument is the full tag that you saw in step 5</p>
</li><li>
<p>The secomd argument replaces the <code>master</code> image name, with the image name we used in step 2. e.g.:</p>
<pre class="code ruby"><code class="ruby">docker tag yalelibraryit/dc-blacklight:master yalelibraryit/dc-blacklight:v1.0.1
</code></pre>
</li><li>
<p>Push the blacklight image with your incremented version tag. e.g.:</p>
</li></ul>
<p><code>bash docker push yalelibraryit/dc-blacklight:v1.0.1 </code></p>
<h2 id="label-Using+the+Makefile">Using the Makefile</h2>
<p>You can also use the Makefile to build an image locally, and/or push it to dockerhub:</p>
<pre class="code ruby"><code class="ruby">make build <- build the blacklight image
make push <-push an already build image
make build push <-build and then push the image up to dockerhub
</code></pre>
<p>When you use make build, a new blacklight image is built, and tagged as both :latest, and the current git sha. When pushing to dockerhub, only the git sha version is pushed.</p>
<pre class="code ruby"><code class="ruby">yalelibraryit/dc-blacklight d915b32 <-git sha 1c2d8977cf5b <- note same image id
yalelibraryit/dc-blacklight latest 1c2d8977cf5b
</code></pre>
<p>In the case above, only yalelibraryit/dc-blacklight:d915b32 will be available on dockerhub.</p>
<h2 id="label-Environment+Variables+for+Development">Environment Variables for Development</h2>
<p>Create .env.development to override anything in .env. The following values must be overridden.</p>
<pre class="code ruby"><code class="ruby">SOLR_URL=http://solr:8983/solr/blacklight-core
POSTGRES_HOST=db
IIIF_MANIFESTS_BASE_URL=http://localhost/manifests/
</code></pre>
<h2 id="label-HTTP+password+protection">HTTP password protection</h2>
<p>In order to prevent search engine crawling of the system before it's ready to launch, we use HTTP password protection. This is set via environment variables. Set <code>HTTP_PASSWORD_PROTECT='true'</code> to enable this feature. Set <code>HTTP_PASSWORD_PROTECT='false'</code> to disable this feature. Set the login and password via environment variables <code>HTTP_USERNAME</code> and <code>HTTP_PASSWORD</code></p>
<h1 id="label-Customizing+Blacklight-3A">Customizing Blacklight:</h1>
<p>There are many ways to override specific behaviors and views in Blacklight. Because Blacklight is distributed as a Rails engine-based gem, all customization of Blacklight behavior should be done within your application by overriding Blacklight-provided behaviors with your own.</p>
<ul><li>
<p>To modify this text, you need to <a href="http://guides.rubyonrails.org/engines.html#improving-engine-functionality">override the Blacklight-provided view</a>. You can copy this file, located in the blacklight gem: <code>/usr/local/rvm/gems/ruby-2.6.5/gems/blacklight-7.7.0/app/views/catalog/_home_text.html.erb</code> to your own application: <code>/home/app/webapp/app/views/catalog/_home_text.html.erb</code></p>
</li><li>
<p><a href="https://github.com/projectblacklight/blacklight/wiki/Indexing-your-data-into-solr">Index your own data</a> into Solr</p>
</li><li>
<p><a href="https://github.com/projectblacklight/blacklight/wiki#blacklight-configuration">Configure Blacklight</a> to match your data and user-experience needs</p>
</li></ul>
</div></div>
<div id="footer">
Generated on Wed Jun 3 13:40:44 2020 by
<a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
0.9.25 (ruby-2.6.6).
</div>
</div>
</body>
</html>