Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 285 lines (228 sloc) 8.677 kB
5037386 @klacke ""
authored
1 <erl>
bea8261 @klacke added log_wrap_size, configurable wrap size for all logs, fixed a bug…
authored
2 out(A) ->
20ece13 @klacke more css hackery
authored
3 {ssi, "TAB.inc", "%%",[{"embed", "choosen"}]}.
5037386 @klacke ""
authored
4 </erl>
5
6
bea8261 @klacke added log_wrap_size, configurable wrap size for all logs, fixed a bug…
authored
7 <div id="entry">
8
9
e35a591 @klacke more w3c compliance
authored
10 <h1>Running yaws embedded in another larger application</h1>
11 <p>
12 Yaws is ideal to embed inside another larger erlang application.
13 Many typical erlang applications are control applications
14 in need of a webgui specific for the actual application.
15 </p>
16
17 <p>In order to run Yaws inside another application, we need to
18 perform the following steps.
19 </p>
20
21 <ol>
22 <li> <p>Either integrate yaws into the build system of the
23 larger application or specifically provide the ebin path to
24 yaws for the larger application. </p>
25 </li>
26
27 <li><p> Provide the application environment {embedded, true}
28 to Yaws.</p>
29 </li>
30 </ol>
31
32 <p> The large application typically has it's configuration
33 data fed from internal databases, anyway it's usually not feasible
49fc86f @klacke docs and also don't fail if authmod:get_headers() don't exist
authored
34 to let Yaws read it's configuration data from /etc/yaws/yaws.conf.</p>
e35a591 @klacke more w3c compliance
authored
35
36 <p>To solve this, when Yaws is started in embedded mode, it doesn't
49fc86f @klacke docs and also don't fail if authmod:get_headers() don't exist
authored
37 read it's config from /etc/yaws/yaws.conf, rather it expects the larger application
e35a591 @klacke more w3c compliance
authored
38 to feed it the Yaws configuration through the function call
885ee41 @klacke monor doc errors
authored
39 yaws_api:setconf(GC, Groups)
e35a591 @klacke more w3c compliance
authored
40 </p>
41
42 <p> The two arguments here are</p>
43 <ol>
44 <li><p>GC is a #gconf{} record. The definition of the
45 record is:</p>
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
46
0be3c7e @klacke untabified all of yaws
authored
47 <div class="box">
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
48 <verbatim>
5037386 @klacke ""
authored
49 %% global conf
50 -record(gconf,{file,
0be3c7e @klacke untabified all of yaws
authored
51 yaws_dir,
52 tty_trace = false,
53 trace,
54 debug,
55 logdir,
56 ebin_dir = [],
57 runmods = [],
58 keepalive_timeout = 15000,
59 max_num_cached_files = 400,
60 max_num_cached_bytes = 1000000, %% 1 MEG
61 max_size_cached_file = 8000,
62 large_file_chunk_size = 10240,
63 cache_refresh_secs = 30, % seconds (auto zero when debug)
64 default_type = "text/html",
65 timeout = 30000,
66 include_dir = [],
d508b52 @klacke added mnesia_dir support to the gconf record as per patch BY Richard …
authored
67 mnesia_dir = [],
0be3c7e @klacke untabified all of yaws
authored
68 yaws, %% server string
69 username, %% maybe run as a different user than root
70 uid %% unix uid of user that started yaws
71 }).
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
72 </verbatim>
73 </div>
5037386 @klacke ""
authored
74
e35a591 @klacke more w3c compliance
authored
75 <p>The easiest way to figure out what the individual record
76 fields mean is to have a look in the source file yaws_config.erl</p>
77 </li>
5037386 @klacke ""
authored
78
79
e35a591 @klacke more w3c compliance
authored
80 <li><p>Groups, is a list of lists of #sconf records.
81 Yaws is capable of listening on several IP address and also
82 do Virtual Hosting on each IP address.
83 </p>
84 <p>Each #sconf{} record describes one web server, whereas a list of
85 #sconf{} records describe a web server Virt Hosting several different
86 servers.
87 </p>
88 <p>
89 The sconf record is defined as:</p>
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
90 <div class="box">
91 <verbatim>
5037386 @klacke ""
authored
92
93 -record(ssl,
0be3c7e @klacke untabified all of yaws
authored
94 {
95 keyfile,
96 certfile,
97 verify = 0,
98 depth = 1,
99 password,
100 cacertfile,
101 ciphers,
102 cachetimeout}).
5037386 @klacke ""
authored
103
104
105
106
107 %% a list of lists of #sconfs
108 %% one list of #sconf's per listen ip
109
110
111 %% server conf
112 -record(sconf,
0be3c7e @klacke untabified all of yaws
authored
113 {port = 8000, %% which port is this server listening to
114 rhost, %% forced redirect host (+ optional port)
115 rmethod, %% forced redirect method
116 docroot, %% path to the docs
117 access_log = true, %% log acces
118 listen = {127,0,0,1}, %% bind to this IP, {0,0,0,0} is possible
119 servername = "localhost", %% servername is what Host: header is
5037386 @klacke ""
authored
120 add_port = true, %% add port after reading config
0be3c7e @klacke untabified all of yaws
authored
121 ets, %% local store for this server
122 ssl,
123 authdirs = [],
124 partial_post_size = nolimit,
b7656de @klacke Added support for excluding dirs from an appmod. This is useful for /…
authored
125 appmods = [], %% list of appmod specs
0be3c7e @klacke untabified all of yaws
authored
126 errormod_404 = yaws_404, %% the default 404 error module
127 errormod_crash = yaws_404, %% use the same module for crashes
128 arg_rewrite_mod = yaws,
129 tilde_expand = false, %% allow public_html user dirs
130 dir_listings = false, %% allow dir listings
131 opaque = [], %% useful in embedded mode
132 start_mod, %% user provided module to be started
133 allowed_scripts = [yaws]
134 }).
5037386 @klacke ""
authored
135
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
136 </verbatim>
137 </div>
e35a591 @klacke more w3c compliance
authored
138 </li>
139 </ol>
5037386 @klacke ""
authored
140
141
a3f0f90 Updated to reflect the yaws:start_embedded/N functions.
Tobbe Tornquist authored
142 <h2>The quick and easy way to get in the air</h2>
707d272 Reworked the start_embedded functions into three functions.
Tobbe Tornquist authored
143 <p>The following three functions yaws:start_embedded/1,2,3
144 will start Yaws in embedded mode
a3f0f90 Updated to reflect the yaws:start_embedded/N functions.
Tobbe Tornquist authored
145 and provide the minimal information that Yaws requires.</p>
146 <p>NB: With this method you don't need to specify any -yaws switches
147 to your (system) start script.</p>
148 <p>The only thing that you really need to specify is the "DocRoot", i.e
149 the directory path to where your .html and .yaws files lives.
707d272 Reworked the start_embedded functions into three functions.
Tobbe Tornquist authored
150 You will then get the same default values for all the other configuration
151 parameters as you can find in the <i>yaws.hrl</i> header file. So, for
152 example: your server name will be: <i>localhost</i>, listen port: <i>8000</i>,
153 etc.</p>
154 <p>By using yaws:start_embedded/2 you can set some other values
155 than the default ones for the server configuration (#sconf{}), and with
156 yaws:start_embedded/3 you also can specify global configuration (#gconf{}.
157 See the example below:</p>
a3f0f90 Updated to reflect the yaws:start_embedded/N functions.
Tobbe Tornquist authored
158 <div class="box">
159 <pre>
160 %%
707d272 Reworked the start_embedded functions into three functions.
Tobbe Tornquist authored
161 %% Check with inet:i(). that you are listening to port 8000!
a3f0f90 Updated to reflect the yaws:start_embedded/N functions.
Tobbe Tornquist authored
162 %%
163 1> yaws:start_embedded("/home/tobbe/docroot").
164
165 %%
707d272 Reworked the start_embedded functions into three functions.
Tobbe Tornquist authored
166 %% Alternative ways
a3f0f90 Updated to reflect the yaws:start_embedded/N functions.
Tobbe Tornquist authored
167 %%
707d272 Reworked the start_embedded functions into three functions.
Tobbe Tornquist authored
168 1> yaws:start_embedded("/home/tobbe/docroot", [{servername, "sej"}, {listen, {0,0,0,0}}]).
169
170 1> yaws:start_embedded("/home/tobbe/docroot",
171 [{servername, "sej"}, {listen, {0,0,0,0}}],
172 [{auth_log, false}, {copy_errlog, false}]).
173
a3f0f90 Updated to reflect the yaws:start_embedded/N functions.
Tobbe Tornquist authored
174 </pre>
175 </div>
176
177 <p>If you need more control on how to setup Yaws in embedded mode,
178 then read on.</p>
179
180
e35a591 @klacke more w3c compliance
authored
181 <h2> A very small actual example </h2>
182 <p>We provide a minimal example which "embeds" yaws in
183 a normal Erlang shell.
184 </p>
185 <p>We start Erlang as:
186 </p>
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
187 <div class="box">
e35a591 @klacke more w3c compliance
authored
188 <pre>
5037386 @klacke ""
authored
189 # erl -pa /usr/local/lib/yaws/ebin -yaws embedded true -s ybed
e35a591 @klacke more w3c compliance
authored
190 </pre>
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
191 </div>
5037386 @klacke ""
authored
192
e35a591 @klacke more w3c compliance
authored
193 <p>The ybed module is very small and is named
194 <a href="code.yaws?file=/ybed.erl">ybed.erl</a>
195 </p>
5037386 @klacke ""
authored
196
e35a591 @klacke more w3c compliance
authored
197 <p>The above "erl" command line gives:
198 </p>
5037386 @klacke ""
authored
199
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
200 <div class="box">
201 <verbatim>
5037386 @klacke ""
authored
202 # erl -pa /usr/local/lib/yaws/ebin -yaws embedded true -s ybed
203 Erlang (BEAM) emulator version 5.3.b1 [source] [hipe]
204
205 Eshell V5.3.b1 (abort with ^G)
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
206 1>
5037386 @klacke ""
authored
207 =INFO REPORT==== 25-Nov-2003::00:27:18 ===
208 Yaws: Listening to 0.0.0.0:8888 for servers
209 - foobar under /tmp
210
211 1>
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
212 </verbatim>
213 </div>
5037386 @klacke ""
authored
214
215
216 <p>The actual web server then runs inside the larger application
217 and _all_ that remain is to design a decent web GUI. This is
218 harder than it might seem at a first glance. The configuration of the
219 web server was programmatically fed into Yaws from the surrounding application,
220 in this case, the Erlang shell + the module
8e69e2c @klacke first almost working vsn of revproxy
authored
221 <a href="code.yaws?file=/ybed.erl">ybed.erl</a>
e35a591 @klacke more w3c compliance
authored
222 </p>
5037386 @klacke ""
authored
223
224
225 <h2>The opaque field in the sconf structure </h2>
226
227 <p>The sconf structure (which is constructed by the program that
228 starts and configures Yaws), contains a field, SC#sconf.opaque
e35a591 @klacke more w3c compliance
authored
229 </p>
230
5037386 @klacke ""
authored
231
232 <p> This field is passed on into the #arg{} record, so that any application
233 specific configuration data which is needed by the .yaws pages that
234 make up the web GUI application, is easily available there.
e35a591 @klacke more w3c compliance
authored
235 </p>
236
5037386 @klacke ""
authored
237
e35a591 @klacke more w3c compliance
authored
238 <p>In essence, if we construct the #sconf as</p>
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
239
240 <div class="box">
241 <verbatim>
5037386 @klacke ""
authored
242 SC#sconf{opaque = {mystruct, foobar},
243 .....
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
244 </verbatim>
245 </div>
246
5037386 @klacke ""
authored
247
e35a591 @klacke more w3c compliance
authored
248 <p>A .yaws web page, can do:</p>
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
249
250 <div class="box">
251 <verbatim>
5037386 @klacke ""
authored
252 out(Arg) ->
253 MyStruct = Arg#arg.opaque
254 .....
255
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored
256 </verbatim>
257 </div>
5037386 @klacke ""
authored
258
259 <p>Thus passing data from the surrounding applications configuration routines
e35a591 @klacke more w3c compliance
authored
260 down to each .yaws web page.</p>
5037386 @klacke ""
authored
261
885ee41 @klacke monor doc errors
authored
262 <p>Another important fact to consider when choosing weather to run your yaws
d07115c @klacke Several cleanups due to dialyzer, also moved the control file into us…
authored
263 application as an embedded yaws app or not is that all the yaws control
264 functions are disabled when we use yaws as an embedded web server. I.e
265 yaws --ls, yaws --stop etc. This under the assumption that you already have support for this type of functionality in your application.
266 </p>
5037386 @klacke ""
authored
267
b7656de @klacke Added support for excluding dirs from an appmod. This is useful for /…
authored
268 <p>Finally, an interesting appmod definition that may apply to many embedded yaws installations is that / appmod with a set of exclude dirs. Here is an example:
269 </p>
270 <div class="box">
271 <verbatim>
272 SC#sconf{.....
273 appmods = {"/", myapp, [["js"], ["top", "static"], ["icons"]]},
274 ....
275 </verbatim>
276 </div>
277
5037386 @klacke ""
authored
278
bea8261 @klacke added log_wrap_size, configurable wrap size for all logs, fixed a bug…
authored
279 </div>
280
281
5037386 @klacke ""
authored
282 <erl>
bea8261 @klacke added log_wrap_size, configurable wrap size for all logs, fixed a bug…
authored
283 out(A) -> {ssi, "END2",[],[]}.
5037386 @klacke ""
authored
284 </erl>
Something went wrong with that request. Please try again.