Skip to content
Newer
Older
100644 269 lines (213 sloc) 7.42 KB
5037386 @klacke ""
authored Nov 24, 2003
1 <erl>
bea8261 @klacke added log_wrap_size, configurable wrap size for all logs, fixed a bug…
authored Nov 19, 2004
2 out(A) ->
20ece13 @klacke more css hackery
authored Dec 2, 2004
3 {ssi, "TAB.inc", "%%",[{"embed", "choosen"}]}.
5037386 @klacke ""
authored Nov 24, 2003
4 </erl>
5
6
bea8261 @klacke added log_wrap_size, configurable wrap size for all logs, fixed a bug…
authored Nov 19, 2004
7 <div id="entry">
8
9
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
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
34 to let Yaws read it's configuration data from /etc/yaws.conf.</p>
35
36 <p>To solve this, when Yaws is started in embedded mode, it doesn't
37 read it's config from /etc, rather it expects the larger application
38 to feed it the Yaws configuration through the function call
39 yaws_api:set_conf(GC, Groups)
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 Dec 10, 2004
46
47 <div class="box">
48 <verbatim>
5037386 @klacke ""
authored Nov 24, 2003
49 %% global conf
50 -record(gconf,{file,
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 = [],
67 yaws, %% server string
68 username, %% maybe run as a different user than root
69 uid %% unix uid of user that started yaws
70 }).
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored Dec 10, 2004
71 </verbatim>
72 </div>
5037386 @klacke ""
authored Nov 24, 2003
73
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
74 <p>The easiest way to figure out what the individual record
75 fields mean is to have a look in the source file yaws_config.erl</p>
76 </li>
5037386 @klacke ""
authored Nov 24, 2003
77
78
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
79 <li><p>Groups, is a list of lists of #sconf records.
80 Yaws is capable of listening on several IP address and also
81 do Virtual Hosting on each IP address.
82 </p>
83 <p>Each #sconf{} record describes one web server, whereas a list of
84 #sconf{} records describe a web server Virt Hosting several different
85 servers.
86 </p>
87 <p>
88 The sconf record is defined as:</p>
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored Dec 10, 2004
89 <div class="box">
90 <verbatim>
5037386 @klacke ""
authored Nov 24, 2003
91
92 -record(ssl,
93 {
94 keyfile,
95 certfile,
96 verify = 0,
97 depth = 1,
98 password,
99 cacertfile,
100 ciphers,
101 cachetimeout}).
102
103
104
105
106 %% a list of lists of #sconfs
107 %% one list of #sconf's per listen ip
108
109
110 %% server conf
111 -record(sconf,
112 {port = 8000, %% which port is this server listening to
113 rhost, %% forced redirect host (+ optional port)
114 rmethod, %% forced redirect method
115 docroot, %% path to the docs
116 access_log = true, %% log acces
117 listen = {127,0,0,1}, %% bind to this IP, {0,0,0,0} is possible
118 servername = "localhost", %% servername is what Host: header is
119 add_port = true, %% add port after reading config
120 ets, %% local store for this server
121 ssl,
122 authdirs = [],
123 partial_post_size = nolimit,
124 appmods = [], %% list of modules for this app
125 errormod_404 = yaws_404, %% the default 404 error module
126 errormod_crash = yaws_404, %% use the same module for crashes
127 arg_rewrite_mod = yaws,
128 tilde_expand = false, %% allow public_html user dirs
129 dir_listings = false, %% allow dir listings
130 opaque = [], %% useful in embedded mode
131 start_mod, %% user provided module to be started
132 allowed_scripts = [yaws]
133 }).
134
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored Dec 10, 2004
135 </verbatim>
136 </div>
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
137 </li>
138 </ol>
5037386 @klacke ""
authored Nov 24, 2003
139
140
a3f0f90 Updated to reflect the yaws:start_embedded/N functions.
Tobbe Tornquist authored Sep 5, 2006
141 <h2>The quick and easy way to get in the air</h2>
707d272 Reworked the start_embedded functions into three functions.
Tobbe Tornquist authored Sep 5, 2006
142 <p>The following three functions yaws:start_embedded/1,2,3
143 will start Yaws in embedded mode
a3f0f90 Updated to reflect the yaws:start_embedded/N functions.
Tobbe Tornquist authored Sep 5, 2006
144 and provide the minimal information that Yaws requires.</p>
145 <p>NB: With this method you don't need to specify any -yaws switches
146 to your (system) start script.</p>
147 <p>The only thing that you really need to specify is the "DocRoot", i.e
148 the directory path to where your .html and .yaws files lives.
707d272 Reworked the start_embedded functions into three functions.
Tobbe Tornquist authored Sep 5, 2006
149 You will then get the same default values for all the other configuration
150 parameters as you can find in the <i>yaws.hrl</i> header file. So, for
151 example: your server name will be: <i>localhost</i>, listen port: <i>8000</i>,
152 etc.</p>
153 <p>By using yaws:start_embedded/2 you can set some other values
154 than the default ones for the server configuration (#sconf{}), and with
155 yaws:start_embedded/3 you also can specify global configuration (#gconf{}.
156 See the example below:</p>
a3f0f90 Updated to reflect the yaws:start_embedded/N functions.
Tobbe Tornquist authored Sep 5, 2006
157 <div class="box">
158 <pre>
159 %%
707d272 Reworked the start_embedded functions into three functions.
Tobbe Tornquist authored Sep 5, 2006
160 %% Check with inet:i(). that you are listening to port 8000!
a3f0f90 Updated to reflect the yaws:start_embedded/N functions.
Tobbe Tornquist authored Sep 5, 2006
161 %%
162 1> yaws:start_embedded("/home/tobbe/docroot").
163
164 %%
707d272 Reworked the start_embedded functions into three functions.
Tobbe Tornquist authored Sep 5, 2006
165 %% Alternative ways
a3f0f90 Updated to reflect the yaws:start_embedded/N functions.
Tobbe Tornquist authored Sep 5, 2006
166 %%
707d272 Reworked the start_embedded functions into three functions.
Tobbe Tornquist authored Sep 5, 2006
167 1> yaws:start_embedded("/home/tobbe/docroot", [{servername, "sej"}, {listen, {0,0,0,0}}]).
168
169 1> yaws:start_embedded("/home/tobbe/docroot",
170 [{servername, "sej"}, {listen, {0,0,0,0}}],
171 [{auth_log, false}, {copy_errlog, false}]).
172
a3f0f90 Updated to reflect the yaws:start_embedded/N functions.
Tobbe Tornquist authored Sep 5, 2006
173 </pre>
174 </div>
175
176 <p>If you need more control on how to setup Yaws in embedded mode,
177 then read on.</p>
178
179
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
180 <h2> A very small actual example </h2>
181 <p>We provide a minimal example which "embeds" yaws in
182 a normal Erlang shell.
183 </p>
184 <p>We start Erlang as:
185 </p>
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored Dec 10, 2004
186 <div class="box">
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
187 <pre>
5037386 @klacke ""
authored Nov 24, 2003
188 # erl -pa /usr/local/lib/yaws/ebin -yaws embedded true -s ybed
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
189 </pre>
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored Dec 10, 2004
190 </div>
5037386 @klacke ""
authored Nov 24, 2003
191
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
192 <p>The ybed module is very small and is named
193 <a href="code.yaws?file=/ybed.erl">ybed.erl</a>
194 </p>
5037386 @klacke ""
authored Nov 24, 2003
195
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
196 <p>The above "erl" command line gives:
197 </p>
5037386 @klacke ""
authored Nov 24, 2003
198
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored Dec 10, 2004
199 <div class="box">
200 <verbatim>
5037386 @klacke ""
authored Nov 24, 2003
201 # erl -pa /usr/local/lib/yaws/ebin -yaws embedded true -s ybed
202 Erlang (BEAM) emulator version 5.3.b1 [source] [hipe]
203
204 Eshell V5.3.b1 (abort with ^G)
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored Dec 10, 2004
205 1>
5037386 @klacke ""
authored Nov 24, 2003
206 =INFO REPORT==== 25-Nov-2003::00:27:18 ===
207 Yaws: Listening to 0.0.0.0:8888 for servers
208 - foobar under /tmp
209
210 1>
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored Dec 10, 2004
211 </verbatim>
212 </div>
5037386 @klacke ""
authored Nov 24, 2003
213
214
215 <p>The actual web server then runs inside the larger application
216 and _all_ that remain is to design a decent web GUI. This is
217 harder than it might seem at a first glance. The configuration of the
218 web server was programmatically fed into Yaws from the surrounding application,
219 in this case, the Erlang shell + the module
8e69e2c @klacke first almost working vsn of revproxy
authored Dec 15, 2003
220 <a href="code.yaws?file=/ybed.erl">ybed.erl</a>
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
221 </p>
5037386 @klacke ""
authored Nov 24, 2003
222
223
224 <h2>The opaque field in the sconf structure </h2>
225
226 <p>The sconf structure (which is constructed by the program that
227 starts and configures Yaws), contains a field, SC#sconf.opaque
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
228 </p>
229
5037386 @klacke ""
authored Nov 24, 2003
230
231 <p> This field is passed on into the #arg{} record, so that any application
232 specific configuration data which is needed by the .yaws pages that
233 make up the web GUI application, is easily available there.
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
234 </p>
235
5037386 @klacke ""
authored Nov 24, 2003
236
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
237 <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 Dec 10, 2004
238
239 <div class="box">
240 <verbatim>
5037386 @klacke ""
authored Nov 24, 2003
241 SC#sconf{opaque = {mystruct, foobar},
242 .....
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored Dec 10, 2004
243 </verbatim>
244 </div>
245
5037386 @klacke ""
authored Nov 24, 2003
246
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
247 <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 Dec 10, 2004
248
249 <div class="box">
250 <verbatim>
5037386 @klacke ""
authored Nov 24, 2003
251 out(Arg) ->
252 MyStruct = Arg#arg.opaque
253 .....
254
f875c2b @klacke added <verbatim> tag for .yaws files, It works as the pre (or the cod…
authored Dec 10, 2004
255 </verbatim>
256 </div>
5037386 @klacke ""
authored Nov 24, 2003
257
258 <p>Thus passing data from the surrounding applications configuration routines
e35a591 @klacke more w3c compliance
authored Dec 9, 2004
259 down to each .yaws web page.</p>
5037386 @klacke ""
authored Nov 24, 2003
260
261
262
bea8261 @klacke added log_wrap_size, configurable wrap size for all logs, fixed a bug…
authored Nov 19, 2004
263 </div>
264
265
5037386 @klacke ""
authored Nov 24, 2003
266 <erl>
bea8261 @klacke added log_wrap_size, configurable wrap size for all logs, fixed a bug…
authored Nov 19, 2004
267 out(A) -> {ssi, "END2",[],[]}.
5037386 @klacke ""
authored Nov 24, 2003
268 </erl>
Something went wrong with that request. Please try again.