Skip to content
Browse files

""

git-svn-id: https://erlyaws.svn.sourceforge.net/svnroot/erlyaws/trunk/yaws@549 9fbdc01b-0d2c-0410-bfb7-fb27d70d8b52
  • Loading branch information...
1 parent ffe65aa commit 503738664a39ceca05e4dde0db6a91cb264856db @klacke committed Nov 24, 2003
Showing with 219 additions and 0 deletions.
  1. +2 −0 www/EXHEAD
  2. +191 −0 www/embed.yaws
  3. +26 −0 www/ybed.erl
View
2 www/EXHEAD
@@ -8,6 +8,8 @@
<td> <A HREF="/query.yaws">Query part of url</a> </td>
<td> <A HREF="/form.yaws">Forms</a> </td>
<td> <A HREF="/redirect.yaws">Redirect</a> </td>
+ <td> <A HREF="/embed.yaws">Embedding Yaws</a> </td>
+
</tr>
<tr border="2">
<td> <A HREF="/arg.yaws">Arg</a> </td>
View
191 www/embed.yaws
@@ -0,0 +1,191 @@
+<erl>
+out(A) -> yaws_api:ssi(A#arg.docroot, ["/HEAD", "/EXHEAD"]).
+</erl>
+
+
+<h1>Running yaws embedded in another larger application</h1>
+<p>
+Yaws is ideal to embed inside another larger erlang application.
+Many typical erlang applications are control applications
+in need of a webgui specific for the actual application.
+
+<p>In order to run Yaws inside another application, we need to
+perform the following steps.
+
+<ol>
+<li> <p>Either integrate yaws into the build system of the
+larger application or specifically provide the ebin path to
+yaws for the larger application.
+
+<li><p> Provide the application environment {embedded, true}
+to Yaws.
+
+<li><p> The large application typically has it's configuration
+data fed from internal databases, anyway it's usually not feasible
+to let Yaws read it's configuration data from /etc/yaws.conf.
+
+<p>To solve this, when Yaws is started in embedded mode, it doesn't
+read it's config from /etc, rather it expects the larger application
+to feed it the Yaws configuration through the function call
+yaws_api:set_conf(GC, Groups)
+
+<p> The two arguments here are
+<ol>
+<li><p>GC is a #gconf{} record. The definition of the
+record is:
+<pre>
+%% global conf
+-record(gconf,{file,
+ yaws_dir,
+ tty_trace = false,
+ trace,
+ debug,
+ logdir,
+ ebin_dir = [],
+ runmods = [],
+ keepalive_timeout = 15000,
+ max_num_cached_files = 400,
+ max_num_cached_bytes = 1000000, %% 1 MEG
+ max_size_cached_file = 8000,
+ large_file_chunk_size = 10240,
+ cache_refresh_secs = 30, % seconds (auto zero when debug)
+ default_type = "text/html",
+ timeout = 30000,
+ include_dir = [],
+ yaws, %% server string
+ username, %% maybe run as a different user than root
+ uid %% unix uid of user that started yaws
+ }).
+</pre>
+
+<p>The easiest way to figure out what the individual record
+fields mean is to have a look in the source file yaws_config.erl
+
+<li><p>Groups, is a list of lists of #sconf records.
+Yaws is capable of listening on several IP address and also
+do Virtual Hosting on each IP address.
+
+<p>Each #sconf{} record describes one web server, whereas a list of
+#sconf{} records describe a web server Virt Hosting several different
+servers.
+
+The sconf record is defined as:
+<pre>
+
+-record(ssl,
+ {
+ keyfile,
+ certfile,
+ verify = 0,
+ depth = 1,
+ password,
+ cacertfile,
+ ciphers,
+ cachetimeout}).
+
+
+
+
+%% a list of lists of #sconfs
+%% one list of #sconf's per listen ip
+
+
+%% server conf
+-record(sconf,
+ {port = 8000, %% which port is this server listening to
+ rhost, %% forced redirect host (+ optional port)
+ rmethod, %% forced redirect method
+ docroot, %% path to the docs
+ access_log = true, %% log acces
+ listen = {127,0,0,1}, %% bind to this IP, {0,0,0,0} is possible
+ servername = "localhost", %% servername is what Host: header is
+ add_port = true, %% add port after reading config
+ ets, %% local store for this server
+ ssl,
+ authdirs = [],
+ partial_post_size = nolimit,
+ appmods = [], %% list of modules for this app
+ errormod_404 = yaws_404, %% the default 404 error module
+ errormod_crash = yaws_404, %% use the same module for crashes
+ arg_rewrite_mod = yaws,
+ tilde_expand = false, %% allow public_html user dirs
+ dir_listings = false, %% allow dir listings
+ opaque = [], %% useful in embedded mode
+ start_mod, %% user provided module to be started
+ allowed_scripts = [yaws]
+ }).
+
+</pre>
+
+</ol>
+</ol>
+
+
+<h2> A very small actual example </h2>
+<p>We provide a minimal example which "embeds" yaws in
+a normal Erlang shell.
+
+<p>We start Erlang as:
+
+<pre>
+# erl -pa /usr/local/lib/yaws/ebin -yaws embedded true -s ybed
+</pre>
+
+<p>The ybed module is very small and is named
+<a href="/code.yaws?file=/ybed.erl">ybed.erl</a>
+
+<p>The above "erl" command line gives:
+
+<pre>
+# erl -pa /usr/local/lib/yaws/ebin -yaws embedded true -s ybed
+Erlang (BEAM) emulator version 5.3.b1 [source] [hipe]
+
+Eshell V5.3.b1 (abort with ^G)
+1>
+=INFO REPORT==== 25-Nov-2003::00:27:18 ===
+Yaws: Listening to 0.0.0.0:8888 for servers
+ - foobar under /tmp
+
+1>
+</pre>
+
+
+<p>The actual web server then runs inside the larger application
+and _all_ that remain is to design a decent web GUI. This is
+harder than it might seem at a first glance. The configuration of the
+web server was programmatically fed into Yaws from the surrounding application,
+in this case, the Erlang shell + the module
+<a href="/code.yaws?file=/ybed.erl">ybed.erl</a>
+
+
+<h2>The opaque field in the sconf structure </h2>
+
+<p>The sconf structure (which is constructed by the program that
+starts and configures Yaws), contains a field, SC#sconf.opaque
+
+<p> This field is passed on into the #arg{} record, so that any application
+specific configuration data which is needed by the .yaws pages that
+make up the web GUI application, is easily available there.
+
+<p>In essence, if we construct the #sconf as
+<pre>
+SC#sconf{opaque = {mystruct, foobar},
+ .....
+</pre>
+
+<p>A .yaws web page, can do:
+<pre>
+out(Arg) ->
+ MyStruct = Arg#arg.opaque
+ .....
+
+</pre>
+
+<p>Thus passing data from the surrounding applications configuration routines
+down to each .yaws web page.
+
+
+
+<erl>
+out(A) -> yaws_api:ssi(A#arg.docroot, ["/END"]).
+</erl>
View
26 www/ybed.erl
@@ -0,0 +1,26 @@
+%%%-------------------------------------------------------------------
+%%% File : ybed.erl
+%%% Author : <klacke@hyber.org>
+%%% Description : Small embedded yaws example
+%%%
+%%% Created : 25 Nov 2003 by <klacke@hyber.org>
+%%%-------------------------------------------------------------------
+-module(ybed).
+-compile(export_all).
+
+-include("/usr/local/lib/yaws/include/yaws.hrl").
+
+start() ->
+ application:start(yaws),
+ GC = yaws_config:make_default_gconf(false),
+ SC = #sconf{access_log = true,
+ port = 8888,
+ servername = "foobar",
+ listen = {0,0,0,0},
+ docroot = "/tmp"},
+ yaws_api:setconf(GC, [[SC]]).
+
+
+
+
+

0 comments on commit 5037386

Please sign in to comment.
Something went wrong with that request. Please try again.