-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathquickstart.html
296 lines (274 loc) · 18.5 KB
/
quickstart.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
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
<!DOCTYPE html>
<html>
<head>
<meta charset='utf-8'>
<meta http-equiv="X-UA-Compatible" content="chrome=1">
<meta content="True" name="HandheldFriendly">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0">
<meta name="viewport" content="width=device-width">
<meta name="description" content="nginx-clojure.github.io : Nginx module for embedding Clojure / Java / Groovy programs, typically those Ring based handlers">
<link rel="stylesheet" type="text/css" media="screen" href="stylesheets/stylesheet.css">
<!-- bootstrap cdn -->
<!-- Latest compiled and minified CSS -->
<link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css">
<!-- Optional theme -->
<link rel="stylesheet" href="//netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap-theme.min.css">
<script src="//ajax.aspnetcdn.com/ajax/jQuery/jquery-1.11.0.min.js"></script>
<!-- Latest compiled and minified JavaScript -->
<script src="//netdna.bootstrapcdn.com/bootstrap/3.0.0/js/bootstrap.min.js"></script>
<script src="javascripts/fix.js"></script>
<link rel="stylesheet" type="text/css" media="screen" href="stylesheets/my.css">
<title>Quick Start@Nginx-Clojure</title>
</head>
<body>
<div id="header">
<!-- HEADER -->
<nav id="header_wrap" class="" role="navigation">
<header id="header_logo_title" class="inner container">
<ul class="external-link-buttons">
<li>
<a id="forkme_banner" href="https://github.com/nginx-clojure/nginx-clojure" target="_blank">View on GitHub</a>
</li>
<!-- <li>
<a id="google_group_banner" href="https://groups.google.com/forum/#!forum/nginx-clojure" target="_blank">Google Group</a>
</li> -->
</ul>
<div id="project_logo">
<h1 id="project_title">nginx-clojure</h1>
<ul class="social-buttons">
<li>
<iframe class="github-btn" src="github-btn.html?user=nginx-clojure&repo=nginx-clojure&type=watch&count=true" allowtransparency="true" frameborder="0" scrolling="0" width="102px" height="20px"></iframe>
</li>
<li>
<iframe class="github-btn" src="github-btn.html?user=nginx-clojure&repo=nginx-clojure&type=fork&count=true" allowtransparency="true" frameborder="0" scrolling="0" width="100px" height="20px"></iframe>
</li>
</ul></div>
<h6 id="project_tagline">Nginx module for embedding Clojure / Java / Groovy programs, typically those Ring based handlers</h6>
</header>
<div class="btn-group" style="border-top-width: 1px;border-top-color: #fff;">
<a href="index.html" class="btn btn-sample btn-md"><span class="glyphicon glyphicon-home"></span> Home</a>
<a href="quickstart.html" class="btn btn-sample btn-md"><span class="glyphicon glyphicon-flash"></span> Quick Start</a>
<a href="downloads.html" class="btn btn-sample btn-md"><span class="glyphicon glyphicon-download-alt"></span> Downloads</a>
<a href="installation.html" class="btn btn-sample btn-md"><span class="glyphicon glyphicon-hdd"></span> Installation</a>
<div class="btn-group">
<button type="button" class="btn btn-sample btn-md dropdown-toggle" data-toggle="dropdown" id="docDropDownBtn"><span class="glyphicon glyphicon-cog"></span> Configuration <span class="caret"></span></button>
<ul class="dropdown-menu" role="menu">
<li><a href="configuration.html#user-content-21-jvm-path--class-path--other-jvm-options"><span class="glyphicon glyphicon-cog"></span> JVM Path,Class Path & Other JVM Options</a></li>
<li><a href="configuration.html#user-content-22-initialization-handler-for-nginx-worker"><span class="glyphicon glyphicon-cog"></span> Initialization Handler for nginx worker</a></li>
<li><a href="configuration.html#user-content-23-content-ring-handler-for-location"><span class="glyphicon glyphicon-cog"></span> Content Ring Handler for Location</a></li>
<li><a href="configuration.html#user-content-24-chose--coroutine-based-socket-or-asynchronous-socketchannel-or-thread-pool-for-slow-io-operations"><span class="glyphicon glyphicon-cog"></span> Coroutine/Asynchronous Client Channel/Thread Pool </a></li>
<li><a href="configuration.html#user-content-25-nginx-rewrite-handler"><span class="glyphicon glyphicon-cog"></span> Nginx Rewrite Handler</a></li>
<li><a href="configuration.html#user-content-26-nginx-access-handler"><span class="glyphicon glyphicon-cog"></span> Nginx Access Handler</a></li>
<li><a href="configuration.html#user-content-27-nginx-header-filter"><span class="glyphicon glyphicon-cog"></span> Nginx Header Filter</a></li>
<li><a href="configuration.html#user-content-28-nginx-body-filter"><span class="glyphicon glyphicon-cog"></span> Nginx Body Filter</a></li>
<li><a href="configuration.html#user-content-29-nginx-log-handler"><span class="glyphicon glyphicon-cog"></span> Nginx Log Handler</a></li>
</ul>
</div>
<div class="btn-group">
<button type="button" class="btn btn-sample btn-md dropdown-toggle" data-toggle="dropdown" id="docDropDownBtn"><span class="glyphicon glyphicon-book"></span> Documents <span class="caret"></span></button>
<ul class="dropdown-menu" role="menu">
<!-- <li><a href="quickstart.html"><span class="glyphicon glyphicon-flash"></span> Quick Start</a></li> -->
<li><a href="directives.html"><span class="glyphicon glyphicon-th-list text-warning"></span> Directives Reference</a></li>
<li><a href="embed.html"><span class="glyphicon glyphicon-gift"></span> Embedding Nginx-Clojure into A standard App</a></li>
<li><a href="more.html#user-content-34-server-channel-for-long-polling--server-sent-events-sse"><span class="glyphicon glyphicon-envelope"></span> Server Channel for Long Polling & Server Sent Events</a></li>
<li><a href="subpub.html"><span class="glyphicon glyphicon-envelope text-warning"></span> Pub/Sub Among Nginx Worker Processes</a></li>
<li><a href="sharedmap.html"><span class="glyphicon glyphicon-envelope text-warning"></span> Shared Map & Session Store</a></li>
<li><a href="more.html#user-content-36-asynchronous-client-channel"><span class="glyphicon glyphicon-road"></span> Asynchronous Client Channel</a></li>
<li><a href="more.html#user-content-37--about-logging"><span class="glyphicon glyphicon-th-list"></span> About Logging</a></li>
<li><a href="more.html#user-content-38--sever-side-websocket"><span class="glyphicon glyphicon-th-list"></span> Sever Side WebSocket</a></li>
<li><a href="more.html#user-content-39--java-standard-restful-web-services-with-jersey"><span class="glyphicon glyphicon-th-list"></span> Java standard RESTful web services with Jersey</a></li>
<li><a href="more.html#user-content-310-embeding-tomcat"><span class="glyphicon glyphicon-th-list"></span> Embeding Tomcat</a></li>
<li><a href="more.html#user-content-311-more-about-nginx-worker-process"><span class="glyphicon glyphicon-th-list"></span> More about Nginx Worker Process</a></li>
<li><a href="more.html"><span class="glyphicon glyphicon-th-list"></span> More about Nginx-Clojure</a></li>
<li><a href="api/"><span class="glyphicon glyphicon-book text-warning"></span> API Reference (Clojure)</a></li>
</ul>
</div>
<a href="userfullLinks.html" class="btn btn-sample btn-md"><span class="glyphicon glyphicon-share-alt"></span> Useful Links</a>
</div>
</nav>
</div>
<!-- MAIN CONTENT -->
<div id="main_content_wrap" class="outer">
<section id="main_content" class="inner">
<h1>
<a id="user-content-quick-start" class="anchor" href="#quick-start" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Quick Start</h1>
<h2>
<a id="user-content-installation" class="anchor" href="#installation" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Installation</h2>
<ol>
<li>Download the latest binaries release v0.5.3 from <a href="https://sourceforge.net/projects/nginx-clojure/files/" rel="nofollow">here</a>.</li>
<li>Unzip the zip file downloaded then rename the file <code>nginx-${os-arc}</code> to <code>nginx</code>, eg. for linux is <code>nginx-linux-x64</code>
</li>
</ol>
<blockquote>
<p>If you want to compile it with your own nginx please check <a href="installation.html">HERE</a></p>
</blockquote>
<h2>
<a id="user-content-configuration" class="anchor" href="#configuration" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Configuration</h2>
<ol>
<li>
<p>Open conf/nginx.conf file</p>
</li>
<li>
<p>Setting JVM path and class path within <code>http {</code> block in nginx.conf</p>
<div class="highlight highlight-source-nginx"><pre><span class="pl-c">### jvm dynamic library path</span>
<span class="pl-c">### auto or a real path, e,g /usr/lib/jvm/java-8-oracle/jre/lib/amd64/server/libjvm.so</span>
<span class="pl-k">jvm_path</span> auto;
<span class="pl-c">### Set my app jars and resources, it must include nginx-clojure runtime jar,e.g. nginx-clojure-0.5.0.jar and </span>
<span class="pl-c">## for clojure user clojure runtime jar is also needed.</span>
<span class="pl-c">### See http://nginx-clojure.github.io/directives.html#jvm_classpath</span>
<span class="pl-k">jvm_classpath</span> <span class="pl-s">'libs/*'</span>; <span class="pl-c">#windows user should use ';' as the separator</span>
</pre></div>
</li>
<li>
<p>Setting Inline Http Service Handler</p>
</li>
</ol>
<ul>
<li>
<p><strong>Clojure</strong></p>
<div class="highlight highlight-source-nginx"><pre> <span class="pl-c">##Within `server {` block in nginx.conf</span>
<span class="pl-k">location</span> <span class="pl-en">/clojure </span>{
<span class="pl-k">content_handler_type</span> <span class="pl-s">'clojure'</span>;
<span class="pl-k">content_handler_code</span> <span class="pl-s">' </span>
<span class="pl-s"> (fn[req]</span>
<span class="pl-s"> {</span>
<span class="pl-s"> :status 200,</span>
<span class="pl-s"> :headers {"content-type" "text/plain"},</span>
<span class="pl-s"> :body "Hello Clojure & Nginx!"</span>
<span class="pl-s"> })</span>
<span class="pl-s"> '</span>;
}</pre></div>
</li>
<li>
<p><strong>Groovy</strong></p>
<div class="highlight highlight-source-nginx"><pre> <span class="pl-c">##Within `server {` block in nginx.conf</span>
<span class="pl-k">location</span> <span class="pl-en">/groovy </span>{
<span class="pl-k">content_handler_type</span> <span class="pl-s">'groovy'</span>;
<span class="pl-k">content_handler_code</span> <span class="pl-s">' </span>
<span class="pl-s"> import nginx.clojure.java.NginxJavaRingHandler;</span>
<span class="pl-s"> import java.util.Map;</span>
<span class="pl-s"> public class HelloGroovy implements NginxJavaRingHandler {</span>
<span class="pl-s"> public Object[] invoke(Map<String, Object> request){</span>
<span class="pl-s"> return [200, //http status 200</span>
<span class="pl-s"> ["Content-Type":"text/html"], //headers map</span>
<span class="pl-s"> "Hello, Groovy & Nginx!"]; //response body can be string, File or Array/Collection of them</span>
<span class="pl-s"> }</span>
<span class="pl-s"> }</span>
<span class="pl-s"> '</span>;
}</pre></div>
</li>
<li>
<p><strong>Java</strong></p>
<blockquote>
<p><strong>Note:</strong>
So far nginx-clojure has not supported inline java handler, please see the next section to learn how to use an external java handler.</p>
</blockquote>
</li>
</ul>
<ol>
<li>Setting Compojure Router/External Http Service Handler</li>
</ol>
<ul>
<li>
<p><strong>Clojure</strong></p>
<div class="highlight highlight-source-nginx"><pre> <span class="pl-c">##Within `server {` block in nginx.conf</span>
<span class="pl-k">location</span> <span class="pl-en">/ </span>{
<span class="pl-k">content_handler_type</span> clojure;
<span class="pl-k">content_handler_name</span> <span class="pl-s">'example/my-app'</span>;
}</pre></div>
<p>Make sure that the below source is in the classpath.</p>
<div class="highlight highlight-source-clojure"><pre><span class="pl-c"><span class="pl-c">;</span>;;my_app.clj</span>
(<span class="pl-k">ns</span> <span class="pl-e">example</span>
(<span class="pl-c1">:require</span> [compojure.core <span class="pl-c1">:refer</span> <span class="pl-c1">:all</span>]
[compojure.route <span class="pl-c1">:as</span> route]))
(<span class="pl-k">defroutes</span> <span class="pl-e">my-app</span>
(<span class="pl-en">GET</span> <span class="pl-s"><span class="pl-pds">"</span>/<span class="pl-pds">"</span></span> [] <span class="pl-s"><span class="pl-pds">"</span><h1>Hello World</h1><span class="pl-pds">"</span></span>)
(<span class="pl-en">route/not-found</span> <span class="pl-s"><span class="pl-pds">"</span><h1>Page not found</h1><span class="pl-pds">"</span></span>))</pre></div>
</li>
<li>
<p><strong>Java</strong></p>
<div class="highlight highlight-source-nginx"><pre> <span class="pl-c">##Within `server {` block in nginx.conf</span>
<span class="pl-k">location</span> <span class="pl-en">/java </span>{
<span class="pl-k">content_handler_type</span> <span class="pl-s">'java'</span>;
<span class="pl-k">content_handler_name</span> <span class="pl-s">'mytest.HelloService'</span>;
}
</pre></div>
<p>Make sure that the class of the below source is in the classpath.</p>
<div class="highlight highlight-source-java"><pre> <span class="pl-k">package</span> <span class="pl-smi">mytest</span>;
<span class="pl-k">import</span> <span class="pl-smi">java.util.Map</span>;
<span class="pl-k">import</span> <span class="pl-smi">nginx.clojure.java.ArrayMap</span>;
<span class="pl-k">import</span> <span class="pl-smi">nginx.clojure.java.NginxJavaRingHandler</span>;
<span class="pl-k">import static</span> <span class="pl-smi">nginx.clojure.MiniConstants.*</span>;
<span class="pl-k">public</span> <span class="pl-k">class</span> <span class="pl-en">HelloService</span> <span class="pl-k">implements</span> <span class="pl-e">NginxJavaRingHandler</span> {
<span class="pl-k">@Override</span>
<span class="pl-k">public</span> <span class="pl-k">Object</span>[] <span class="pl-en">invoke</span>(<span class="pl-k">Map<<span class="pl-smi">String</span>, <span class="pl-smi">Object</span>></span> <span class="pl-v">request</span>) {
<span class="pl-k">return</span> <span class="pl-k">new</span> <span class="pl-smi">Object</span>[] {
<span class="pl-c1">NGX_HTTP_OK</span>, <span class="pl-c"><span class="pl-c">//</span>http status 200</span>
<span class="pl-smi">ArrayMap</span><span class="pl-k">.</span>create(<span class="pl-c1">CONTENT_TYPE</span>, <span class="pl-s"><span class="pl-pds">"</span>text/plain<span class="pl-pds">"</span></span>), <span class="pl-c"><span class="pl-c">//</span>headers map</span>
<span class="pl-s"><span class="pl-pds">"</span>Hello, Java & Nginx!<span class="pl-pds">"</span></span> <span class="pl-c"><span class="pl-c">//</span>response body can be string, File or Array/Collection of string or File</span>
};
}
}</pre></div>
</li>
</ul>
<hr>
<blockquote>
<p><strong>Note:</strong>
For more advanced configurations such as enable coroutine based socket, thread pool etc. Please check them from <a href="configuration.html">HERE</a>.</p>
</blockquote>
<h2>
<a id="user-content-start-up" class="anchor" href="#start-up" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Start up</h2>
<div class="highlight highlight-source-nginx"><pre>
$ <span class="pl-k">cd</span> nginx-clojure-0.5.3
$ ./<span class="pl-k">nginx</span></pre></div>
<p>If everything is ok, we can access our first http service by this url</p>
<div class="highlight highlight-source-nginx"><pre><span class="pl-c">### For Clojure</span>
http://localhost:8080/<span class="pl-k">clojure</span>
<span class="pl-c">### For Clojure Compojure Router</span>
http://localhost:<span class="pl-k">8080</span>
<span class="pl-c">### For Groovy</span>
http://localhost:8080/<span class="pl-k">groovy</span>
<span class="pl-c">### For Java</span>
http://localhost:8080/<span class="pl-k">java</span></pre></div>
<p>We can check the logs/error.log to see error information.</p>
<h2>
<a id="user-content-reload" class="anchor" href="#reload" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Reload</h2>
<p>If we change some settings we can reload the settings without stopping our services.</p>
<div class="highlight highlight-source-nginx"><pre>$ ./<span class="pl-k">nginx</span> -s reload</pre></div>
<h2>
<a id="user-content-stop" class="anchor" href="#stop" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Stop</h2>
<div class="highlight highlight-source-nginx"><pre>$ ./<span class="pl-k">nginx</span> -s stop</pre></div>
<h2>
<a id="user-content-examples" class="anchor" href="#examples" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a>Examples</h2>
<h3>
<a id="user-content-clojure-web-example" class="anchor" href="#clojure-web-example" aria-hidden="true"><span aria-hidden="true" class="octicon octicon-link"></span></a><a href="https://github.com/nginx-clojure/nginx-clojure/tree/master/example-projects/clojure-web-example">clojure-web-example</a>
</h3>
<p>A basic example about nginx-clojure & clojure web dev. It uses:</p>
<ul>
<li>
<a href="https://github.com/weavejester/compojure">Compojure</a> (for uri routing)</li>
<li>
<a href="https://github.com/weavejester/hiccup">Hiccup</a> (for html rendering)</li>
<li>
<a href="http://nginx-clojure.github.io/more.html#38--sever-side-websocket" rel="nofollow">Websocket API</a> & <a href="">Sub/Pub API</a> (to demo a simple chatroom)</li>
<li>ring.middleware.reload (for auto-reloading modified namespaces in dev environments)</li>
</ul>
<p>See it on <a href="https://github.com/nginx-clojure/nginx-clojure/tree/master/example-projects/clojure-web-example">github</a>.</p>
</section>
</div>
<div id="footer">
<!-- FOOTER -->
<div id="footer_wrap" class="outer">
<footer class="inner">
<p>
Powered by <a href="http://getbootstrap.com/">Twitter Bootstrap</a>
</p>
</footer>
</div>
</div>
<script type="text/javascript">
//$("a[href^='http']").attr("target","_blank");
//setTimeout("fixNavbarIssue();", 1000);
</script>
</body>
</html>