Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 182 lines (166 sloc) 7.915 kb
f52ef4a added yapp_intro.yaws
Mikael Karlsson authored
1
2 <erl>
3
4
5 box(Str) ->
6 {'div',[{class,"box"}],
7 {pre,[], yaws_api:htmlize(Str)}}.
8
9 tbox(T) ->
10 box(lists:flatten(io_lib:format("~p",[T]))).
11
12
13 out(A) ->
14 [{ssi, "TAB.inc", "%%",[{"yapp_intro", "choosen"}]},
15 {ehtml,
16 {'div', [{id, "entry"}],
17
18 [{h1, [], "Yaws applications - Yapps"},
19
0be3c7e @klacke untabified all of yaws
authored
20 {p, [],
21 "Yaws applications, Yapps, are actually ordinary Erlang/OTP "
22 "applications with some optional information in their "
23 ".app files and the web pages in the priv/docroot directory "
24 "as default. The Yaws applications handler takes care of adding, "
25 "and removing, the applications into a running server. "
26 " When anyone access the server with an URL that matches the path for an "
27 " added application, the docroot will be temporarily switched to where the web "
28 " pages for that application are located."},
29
30 {h2,[], "Using the application handler"},
31 {h3,[], "Installing"},
32 {p, [],
33 ["The application handler is named just yapp and is located in the "
34 "directory yaws/applications/yapp. Yaws itself should have been built first, "
35 "then in the yapp directory we do",
36 {ol, [],[
37 {li,[],{pre,[], "make"}},
38 {li,[],[{pre,[], "make docs"}," - if we want documentation"]},
39 {li,[],[{pre,[], "make install"}," - unless yaws was installed with make local_install"]}
40 ]
41 }]},
42
43 {h3,[], "Setting up yaws.conf"},
44 {p,[], "First we include the ebin directory of the yapp handler "
45 "application by adding the line "
46 },
47 box("ebin_dir = /<yaws_root>/{applications,lib}/yapp/ebin"),
48 {p,[],
49 "The \"applications\" part is used for a local_installed Yaws, and \"lib\""
50 " for a real installed one. Then we make sure that the yapp handler "
51 " application is started when Yaws is started, by using the runmod directive"},
52 box("runmod = yapp"),
53 {p,[],
54 "For every virtual server that we want to use yapps we add yapp as an "
55 "arg_rewrite_mod and set the opaque parameter yapp_server_id to a unique "
56 "name."},
57 box("
f52ef4a added yapp_intro.yaws
Mikael Karlsson authored
58 <server myexternalserver>
0be3c7e @klacke untabified all of yaws
authored
59 port = 8000
60 listen = 0.0.0.0
61 docroot = /yawsdocrootpath/www
62 arg_rewrite_mod = yapp
63 <opaque>
64 yapp_server_id = edo
f52ef4a added yapp_intro.yaws
Mikael Karlsson authored
65 </opaque>
66 </server>
67 "),
0be3c7e @klacke untabified all of yaws
authored
68 {p,[],
69 "The web applications that are configured in the Yapp registry will be loaded "
70 "into Yaws configuration when the yapp application is started. A prerequisite "
71 "is that the applications are found in the Erlang code loader path. There is "
72 "also an option to define yapps in yaws.conf for every server directly by using "
73 "the opaque parameter bootstrap_yapps = webapp1, webapp2 etc. "},
74 {p,[],
75 "For instance the yapp handler application (named yapp) is a yapp in itself, "
76 "got it?, that provides a web gui to list active yapps and add/remove yapps "
77 "from the registry. But since we can not add itself to the registry before it "
78 "is added we have to bootstrap into the server when Yaws is started. "},
79 box("
f52ef4a added yapp_intro.yaws
Mikael Karlsson authored
80 <server myinternalserver>
0be3c7e @klacke untabified all of yaws
authored
81 port = 8001
82 listen = 0.0.0.0
83 docroot = /docrootpath/www
84 arg_rewrite_mod = yapp
85 <opaque>
86 yapp_server_id = ido
87 bootstrap_yapps = yapp
f52ef4a added yapp_intro.yaws
Mikael Karlsson authored
88 </opaque>
89 </server>"
0be3c7e @klacke untabified all of yaws
authored
90 ),
91 {h3,[],"Executing"},
92 {p,[],
93 "The current default Yapp registry implementation uses Mnesia, we have made "
94 "it easy to plug in other future registry implementations by configuring the "
95 "yapp.app file, but Mnesia is recommended to be future proof for clustered "
96 "application servers. In order to use mnesia one has to prepare a schema, "
97 "we start an erlang shell with the same node name as Yaws is using: "},
98 {p,[],{pre,[],
99 "erl -sname node_name
f52ef4a added yapp_intro.yaws
Mikael Karlsson authored
100 1> mnesia:create_schema([node()])."}},
0be3c7e @klacke untabified all of yaws
authored
101 {p,[],["(we can leave out the -sname options, then the mnesia schema name will "
102 "be \"nonode@nohost\") then we exit and start yaws with the same name: ",
103 {pre,[],"yaws -sname node_name"}]},
104 {p,[],["Now we can access the yapp handler web console from a browser with url:",
105 {pre,[],"http://myinternalserver:8001/yapp/"}]},
f52ef4a added yapp_intro.yaws
Mikael Karlsson authored
106
0be3c7e @klacke untabified all of yaws
authored
107 {h2,[],"Making yapps"},
108 {p,[],
109 [ "In order to make a \"yapp\" we need to know how to make an ordinary Erlang "
110 "application, that is we will need a directory layout as specified by the ",
111 {a,[{href,"http://www.erlang.org/doc/doc-5.5.1/doc/design_principles/part_frame.html"}],
112 "design principles"},
113 " and a proper appname.app file in the ebin directory. "
114 "Yaws itself or yapp are standard applications and can serve as introductionary "
115 "examples. "]},
116 {h3,[], "Internal paths"},
117 {p,[],
118 "Making paths to other documents in the same web application using root paths "
119 "like href=\"/doc2.html\" will not work since a yapp is always below the top. "
120 "Instead use relative paths href=\"doc2.html\" or use the prepath library "
121 "function in any .yaws file: href=yapp:prepath(A) ++ \"doc2.html\", "
122 "where A is a <code>#arg</code> record."},
123 {h3,[],"Appmods"},
124 {p,[],
125 "The yapp handler takes care of throwing in \"private\" appmods for a yapp "
126 "when it is accessed. The appmods modules are put in the applications ebin "
127 "directory as any other Erlang module and configured in the .app file "
128 "with the the environment variable yapp_appmods. For instance; if we "
129 "have a yapp named yappx with root path \"/yappx\" and add: "},
130 box("
f52ef4a added yapp_intro.yaws
Mikael Karlsson authored
131 {env, [
132 {yapp_appmods,[{\"/ctrl\",yappx_controller}]}
133 ]},
134 "),
0be3c7e @klacke untabified all of yaws
authored
135 {p,[],"to the env part in the yappx.app file, an access to the URL "
136 "http://servername/yappx/ctrl will cause a call to the "
137 "yappx_controller:out/1 function, while http://servername/yappy/ctrl "
138 "will not do it. "
139 },
140 {h3,[],"Opaque variables"},
141 {p,[],[
142 "In a similar way the yapp handler adds \"private\" opaques for a yapp "
155abfa Added handling of opaque variables so that ErlyWab apps can be made into...
Mikael Karlsson authored
143 "with the the environment variable yapp_opaque. "
0be3c7e @klacke untabified all of yaws
authored
144 "As an example ", {a,[{href,"http://erlyweb.org/"}], "ErlyWeb "},
145 "applications uses both appmods and opaques in yaws.conf. These can "
146 "be put in the .app file instead if one makes a yapp of it:"]},
147 box("
155abfa Added handling of opaque variables so that ErlyWab apps can be made into...
Mikael Karlsson authored
148 {application, myapp1,
149 [{description,\"myapp1 is an erlyweb yapp\"},
150 {vsn,\"0.1\"},
151 {modules,[]},
152 {registered, []},
b866cf9 fixed yapp dependencies to vdir handling, added local stylesheet and upd...
Mikael Karlsson authored
153 % {mod,{myapp1_app,[]}}, %% Only needed if the application needs to be started
155abfa Added handling of opaque variables so that ErlyWab apps can be made into...
Mikael Karlsson authored
154 {env, [
0be3c7e @klacke untabified all of yaws
authored
155 {yapp_docroot,\"www\"},
d7fce38 updated yapp documentation and startup sequence of yapp to avoid
Mikael Karlsson authored
156 {yapp_appmods,[{\"/erlyweb\",erlyweb}]},
0be3c7e @klacke untabified all of yaws
authored
157 {yapp_opaque,[{\"appname\",\"myapp1\"}]}
155abfa Added handling of opaque variables so that ErlyWab apps can be made into...
Mikael Karlsson authored
158 ]},
159 {applications,[kernel,stdlib]}]}.
160 "),
0be3c7e @klacke untabified all of yaws
authored
161 {p,[],"Also note that the docroot is www instead of the default priv/docroot in "
155abfa Added handling of opaque variables so that ErlyWab apps can be made into...
Mikael Karlsson authored
162 "ErlyWeb applications."},
163
0be3c7e @klacke untabified all of yaws
authored
164 {h2,[],"Problems"},
165 {p,[],"Embedded ssi directives in ehtml parts will not work for now."},
f52ef4a added yapp_intro.yaws
Mikael Karlsson authored
166
0be3c7e @klacke untabified all of yaws
authored
167 {h2,[],"Future"},
168 {p,[],
169 "It may look as an extra complexity to use Erlang applications but in this way "
170 "we can benefit from Erlangs own framework for application handling. For instance, "
171 "in the future we hope to add features for release handling to "
172 "add/remove/upgrade/downgrade yapps on a running Yaws server, or even many clustered "
173 "servers. "}
f52ef4a added yapp_intro.yaws
Mikael Karlsson authored
174 ]
175 }
176 },
177 {ssi, "END2",[],[]}
178 ].
179
180 </erl>
181
Something went wrong with that request. Please try again.