-
Notifications
You must be signed in to change notification settings - Fork 0
/
install.html
189 lines (187 loc) · 8.62 KB
/
install.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
<!DOCTYPE html>
<html lang="en">
<head>
<title>COLD (Controlled Object List and Datum (Concept))</title>
<link href='https://fonts.googleapis.com/css?family=Open+Sans' rel='stylesheet' type='text/css'>
<link rel="stylesheet" href="https://caltechlibrary.github.io/css/site.css">
</head>
<body>
<header>
<a href="http://library.caltech.edu" title="link to Caltech Library Homepage"><img src="https://caltechlibrary.github.io/assets/liblogo.gif" alt="Caltech Library logo"></a>
</header>
<nav>
<ul>
<li><a href="/">Home</a></li>
<li><a href="index.html">README</a></li>
<li><a href="LICENSE">LICENSE</a></li>
<li><a href="install.html">INSTALL</a></li>
<li><a href="user-manual.html">User Manual</a></li>
<li><a href="about.html">About</a></li>
<li><a href="https://github.com/caltechlibrary/cold">GitHub</a></li>
</ul>
</nav>
<section>
<h1 id="installation-for-development-of-cold">Installation for
development of <strong>cold</strong></h1>
<p><strong>cold</strong> is experimental software for managing
controlled object lists and datum (e.g. controlled vocabularies). It is
built from microservices - Newt, Postgres+PostgREST and Pandoc server.
It can run where those microservices have already been installed.
<strong>cold</strong> provides both a human web interface for managing
objects and datum but also a JSON API for integrating those lists into
other application via HTTP calls.</p>
<p>The main configuration file is cold.yaml which defines the models and
routes needed by Newt. You will also need to create an appropriate
PostgREST configuration file and have a Postgres instance available.
Connection to the PostgREST from Newt is handled by passing environment
variables PG_USER and PG_PASSWORD which is used in forming the calls to
PostgREST to manage and retrieve data.</p>
<p><strong>cold</strong> is intended to run behind a front facing web
server (e.g. Apache 2 or NginX) that access control and authentication.
This can be configured in Apache 2 or NginX by use of Shibboleth or
BasicAuth. An example apache2 configuration block is included in the
source repository for <strong>cold</strong>. It will require adaptation
to your specific web server configuration.</p>
<p><strong>cold</strong> requires access to a PostgreSQL 15 through
PostgREST 11. Both need to be configured. Template rendering is provided
by Pandoc running in server mode. Installation, setup of user accounts
and creating databases is beyond the scope of this documentation but is
require to have a working cold instance.</p>
<p>You will need to build <strong>cold</strong> for your specific system
configuration. You need to rebuild the static web content (very likely)
you’ll need to have Git, GNU Make, Pandoc 3 and available and working on
your system.</p>
<h2 id="required-software">Required software</h2>
<p>Adjusting the web content to your host system requires the
following</p>
<ol type="1">
<li>Git (to clone the cold repository on GitHub)</li>
<li>Newt >= 0.0.5</li>
<li>PostgreSQL >= 15</li>
<li>PostgREST >= 11</li>
<li>Pandoc > 3 (both cli and server)</li>
<li>GNU Make</li>
</ol>
<h2 id="running-newt-on-unix-systems">Running Newt on Unix systems</h2>
<p>Currently Pandoc 2 ships with many packaging systems (e.g. Ubuntu
22.04 LTS). <strong>cold</strong> requires Pandoc 3 and PostrREST 11.
These will need a modern Haskell installed (e.g. via <a
href="https://www.haskell.org/ghcup/">gchup</a>). Included in this
repository is a <a href="cloud-init.yaml">cloud-init.yaml</a> file that
can be used with <a href="https://multipass.run">multipass</a> to build
<strong>cold</strong> is a virtual machine.</p>
<p>Here’s an example of the commands you could use for development.</p>
<pre><code>make htdocs
pandoc server &
postgrest postgrest.conf &
newt cold.yaml</code></pre>
<p>If you update the SQL source or cold.yaml files you will need to
restart PostgREST and Newt. You can connect to Newt on localhost via the
port number found in cold.yaml. You can view the web application by
pointing your browser at that URL.</p>
<h2 id="running-newt-on-windows-11">Running Newt on Windows 11</h2>
<p>The easiest way to run Newt on Windows is via the Linux Subsystem for
Windows. If you installed Newt, Postgres, PostgREST and Pandoc under the
subsystem then you can run normally as you would on any other Unix
system.</p>
<h2 id="building-pandoc-postgrest-on-linuxmacos">Building Pandoc,
PostgREST on Linux/macOS</h2>
<ol type="1">
<li>Install Haskell via <a
href="https://www.haskell.org/ghcup/">ghcup</a></li>
<li>Make sure <code>$HOME/bin</code> exists and is in your path
<ol type="a">
<li><code>mkdir -p $HOME/bin</code></li>
<li>Add it to your .bashrc,
<code>echo 'export PATH="$HOME/bin:$PATH"' >>$HOME.bashrc</code></li>
<li>Source .bashrc if needed <code>source $HOME/.bashrc</code></li>
</ol></li>
<li>Build Pandoc 3 install as pandoc and pandoc-server
<ol type="a">
<li><code>cd</code></li>
<li><code>git clone https://github.com/jgm/pandoc src/github.com/jgm/pandoc</code></li>
<li><code>cd src/github.com/jgm/pandoc</code></li>
<li><code>make</code></li>
<li><code>cp -vi $(find . -type f -name pandoc) $HOME/bin/pandoc-server</code></li>
<li><code>cp -vi $(find . -type f -name pandoc) $HOME/bin/pandoc</code></li>
</ol></li>
<li>Build PostgREST and install
<ol type="a">
<li><code>cd</code></li>
<li><code>git clone https://github.com/PostgREST/postgrest src/postgrest</code></li>
<li><code>cd src/postgrest</code></li>
<li><code>stack build --install-ghc --copy-bins --local-bin-path $HOME/bin</code></li>
</ol></li>
<li>Clone the Git repository for cold and run with Make
<ol type="a">
<li><code>cd</code></li>
<li><code>git clone https://github.com/caltechlibrary/cold src/github.com/caltechlibrary/cold</code></li>
<li><code>cd src/github.com/caltechlibrary/cold</code></li>
<li><code>make</code></li>
</ol></li>
<li>Run PostgREST in the background,
<code>postgrest postgrest.conf &</code></li>
<li>Run Pandoc in server mode in the back ground,
<code>pandoc-server &</code></li>
<li>Run a static web server (e.g. via Python) for the htdocs directory
<ol type="a">
<li>Change into the htdocs directory, <code>cd htdocs</code></li>
<li>Use python to service files,
<code>python3 -m http.server</code></li>
<li>Point your browser at <code>https://localhost:8000</code> and
test.</li>
</ol></li>
</ol>
<p>Here’s an example of the steps I’d take on my M1 Mac Mini.</p>
<pre><code>curl --proto '=https' --tlsv1.2 -sSf https://get-ghcup.haskell.org | sh
source $HOME/.ghcup/env
mkdir -p $HOME/bin
echo 'export PATH="$HOME/bin:$PATH"' >>"$HOME/.bashrc"
source $HOME/.bashrc
cd
git clone https://github.com/jgm/pandoc \
src/github.com/jgm/pandoc
cd src/github.com/jgm/pandoc
make
cp -vi $(find . -type f -name pandoc) $HOME/bin/pandoc
cp -vi $(find . -type f -name pandoc) $HOME/bin/pandoc-server
cd
git clone [email protected]:PostgREST/postgrest \
src/github.com/PostgREST/postgrest
cd src/github.com/PostgREST/postgrest
stack build --install-ghc --copy-bins --local-bin-path $HOME/bin</code></pre>
<p>The cold application is visible to your web browser at</p>
<p>The URL <a href="http://localhost:8000"
class="uri">http://localhost:8000</a></p>
<p>The JSON API is visible from PostgREST at <a
href="http://localhost:3000" class="uri">http://localhost:3000</a></p>
<p>The Pandoc server is visible at <a href="http://localhost:3030"
class="uri">http://localhost:3030</a></p>
<p>To shutdown the running services I do the following</p>
<ul>
<li>Press ctl-c to quick the Python localhost web server</li>
<li>“forground” the pandoc-server with <code>fg</code> and then press
ctl-c</li>
<li>“foreground” the postgrest server with <code>fg</code> and then
press ctl-c</li>
<li>Postgres can be stop using systemctl,
<code>systemctl stop postgres</code></li>
</ul>
<h2
id="building-newt-on-macos-linux-and-linux-subsystem-for-windows">Building
Newt on macOS, Linux and Linux subsystem for Windows</h2>
<p>Newt requires Go 1.20.4 or better to compile. If this is installed
the easiest way to install Newt is with using curl and sh.</p>
<pre><code>curl https://caltechlibrary.github.io/newt/installer.sh | sh</code></pre>
<p>If that does not work you can follow the installation instruction at
<a href="https://caltechlibrary.github.io/newt/INSTALL.html"
class="uri">https://caltechlibrary.github.io/newt/INSTALL.html</a></p>
</section>
<footer>
<span>© 2022 <a href="https://www.library.caltech.edu/copyright">Caltech Library</a></span>
<address>1200 E California Blvd, Mail Code 1-32, Pasadena, CA 91125-3200</address>
<span><a href="mailto:[email protected]">Email Us</a></span>
<span>Phone: <a href="tel:+1-626-395-3405">(626)395-3405</a></span>
</footer>
</body>
</html>