Frontend: Use VirtualHost to separate from custom config, listens to plain http port...
[slapos.git] / software / apache-frontend / README.apache_frontend.txt
1 apache_frontend
2 ===============
3
4 Frontend system using Apache, allowing to rewrite and proxy URLs like
5 myinstance.myfrontenddomainname.com to real IP/URL of myinstance.
6
7 apache_frontend works using the master instance / slave instance design.
8 It means that a single main instance of Apache will be used to act as frontend
9 for many slaves.
10
11
12 How to use
13 ==========
14
15 First, you will need to request a "master" instance of Apache Frontend with
16 "domain" parameter, like::
17   <?xml version='1.0' encoding='utf-8'?>
18   <instance>
19    <parameter id="domain">moulefrite.org</parameter>
20    <parameter id="port">443</parameter>
21   </instance>
22
23 Then, it is possible to request many slave instances
24 (currently only from slapconsole, UI doesn't work yet)
25 of Apache Frontend, like::
26   instance = request(
27     software_release=apache_frontend,
28     partition_reference='frontend2',
29     shared=True,
30     partition_parameter_kw={"url":"https://[1:2:3:4]:1234/someresource"}
31   )
32 Those slave instances will be redirected to the "master" instance,
33 and you will see on the "master" instance the associated RewriteRules of
34 all slave instances.
35
36 Finally, the slave instance will be accessible from:
37 https://someidentifier.moulefrite.org.
38
39 Instance Parameters
40 ===================
41
42 Master Instance Parameters
43 --------------------------
44
45 domain
46 ~~~~~~
47 name of the domain to be used (example: mydomain.com). Subdomains of this
48 domain will be used for the slave instances (example:
49 instance12345.mydomain.com). It is then recommended to add a wildcard in DNS
50 for the subdomains of the chosen domain like::
51   *.mydomain.com. IN A 123.123.123.123
52 Using the IP given by the Master Instance.
53 "domain" is a mandatory Parameter.
54
55 port
56 ~~~~
57 Port used by Apache. Optional parameter, defaults to 4443.
58
59 plain_http_port
60 Port used by apache to serve plain http (only used to redirect to https).
61 Optional parameter, defaults to 8080.
62
63 Slave Instance Parameters
64 -------------------------
65
66 url
67 ~~~
68 url of backend to use.
69 "url" is a mandatory parameter.
70 Example: http://mybackend.com/myresource
71
72 cache
73 ~~~~~
74 Specify if slave instance should use a varnish / stunnel to connect to backend.
75 Possible values: "true", "false".
76 "cache" is an optional parameter. Defaults to "false". 
77 Example: true
78
79 type
80 ~~~~
81 Specify if slave instance will redirect to a zope backend. If specified, Apache
82 RewriteRule will use Zope's Virtual Host Daemon.
83 Possible values: "zope", "default".
84 "type" is an optional parameter. Defaults to "default". 
85 Example: zope
86
87 custom_domain
88 ~~~~~~~~~~~~~
89 Domain name to use as frontend. The frontend will be accessible from this domain.
90 "custom_domain" is an optional parameter. Defaults to
91 [instancereference].[masterdomain]. 
92 Example: www.mycustomdomain.com
93
94
95 Advanced example
96 ================
97
98 Request slave frontend instance using a Zope backend, with Varnish activated,
99 listening to a custom domain::
100   instance = request(
101     software_release=apache_frontend,
102     partition_reference='frontend2',
103     shared=True,
104     partition_parameter_kw={
105         "url":"https://[1:2:3:4]:1234/someresource",
106         "cache":"true",
107         "type":"zope",
108         "custom_domain":"mycustomdomain.com",
109     }
110   )
111
112 Notes
113 =====
114
115 It is not possible with slapos to listen to port <= 1024, because process are
116 not run as root. It is a good idea then to go on the node where the instance is
117 and set some iptables rules like (if using default ports)::
118   iptables -t nat -A PREROUTING -p tcp -d {public ip} --dport 443 -j DNAT --to-destination {listening ip}:4443
119   iptables -t nat -A PREROUTING -p tcp -d {public_ip} --dport 80 -j DNAT --to-destination {listening ip}:8080