README.apache_frontend.txt 4.88 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
apache_frontend
===============

Frontend system using Apache, allowing to rewrite and proxy URLs like
myinstance.myfrontenddomainname.com to real IP/URL of myinstance.

apache_frontend works using the master instance / slave instance design.
It means that a single main instance of Apache will be used to act as frontend
for many slaves.


How to use
==========

First, you will need to request a "master" instance of Apache Frontend with
16 17 18 19 20 21
"domain" parameter, like::
  <?xml version='1.0' encoding='utf-8'?>
  <instance>
   <parameter id="domain">moulefrite.org</parameter>
   <parameter id="port">443</parameter>
  </instance>
22 23 24

Then, it is possible to request many slave instances
(currently only from slapconsole, UI doesn't work yet)
25 26 27 28 29 30 31
of Apache Frontend, like::
  instance = request(
    software_release=apache_frontend,
    partition_reference='frontend2',
    shared=True,
    partition_parameter_kw={"url":"https://[1:2:3:4]:1234/someresource"}
  )
32 33 34 35
Those slave instances will be redirected to the "master" instance,
and you will see on the "master" instance the associated RewriteRules of
all slave instances.

36 37
Finally, the slave instance will be accessible from:
https://someidentifier.moulefrite.org.
38 39 40 41 42 43 44 45 46

Instance Parameters
===================

Master Instance Parameters
--------------------------

domain
~~~~~~
47 48 49 50
name of the domain to be used (example: mydomain.com). Subdomains of this
domain will be used for the slave instances (example:
instance12345.mydomain.com). It is then recommended to add a wildcard in DNS
for the subdomains of the chosen domain like::
51 52 53 54 55 56
  *.mydomain.com. IN A 123.123.123.123
Using the IP given by the Master Instance.
"domain" is a mandatory Parameter.

port
~~~~
57
Port used by Apache. Optional parameter, defaults to 4443.
58

59 60 61
plain_http_port
Port used by apache to serve plain http (only used to redirect to https).
Optional parameter, defaults to 8080.
62 63 64 65 66 67 68 69

Slave Instance Parameters
-------------------------

url
~~~
url of backend to use.
"url" is a mandatory parameter.
70
Example: http://mybackend.com/myresource
71 72 73 74

cache
~~~~~
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 82 83
Specify if slave instance will redirect to a zope backend. If specified, Apache
RewriteRule will use Zope's Virtual Host Daemon.
Possible values: "zope", "default".
84
"type" is an optional parameter. Defaults to "default".
85
Example: zope
86 87 88 89

custom_domain
~~~~~~~~~~~~~
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 93 94
Example: www.mycustomdomain.com


95 96 97 98 99 100 101 102 103 104 105
path
~~~~
Only used if type is "zope".

Will append the specified path to the "VirtualHostRoot" of the zope's
VirtualHostMonster.

"path" is an optional parameter, ignored if not specified.
Example of value: "/erp5/web_site_module/hosting/"


106 107 108
Simple Example
==============

109 110
Request slave frontend instance so that https://[1:2:3:4:5:6:7:8]:1234 will be
redirected and accessible from the proxy::
111 112 113 114 115 116 117 118 119 120 121 122 123
  instance = request(
    software_release=apache_frontend,
    partition_reference='my frontend',
    shared=True,
    partition_parameter_kw={
        "url":"https://[1:2:3:4:5:6:7:8]:1234",
    }
  )


Zope Example
============

124 125 126
Request slave frontend instance using a Zope backend so that
https://[1:2:3:4:5:6:7:8]:1234 will be redirected and accessible from the
proxy::
127 128 129 130 131 132 133 134 135 136 137
  instance = request(
    software_release=apache_frontend,
    partition_reference='my frontend',
    shared=True,
    partition_parameter_kw={
        "url":"https://[1:2:3:4:5:6:7:8]:1234",
        "type":"zope",
    }
  )


138 139 140 141
Advanced example
================

Request slave frontend instance using a Zope backend, with Varnish activated,
142 143 144
listening to a custom domain and redirecting to /erp5/ so that
https://[1:2:3:4:5:6:7:8]:1234/erp5/ will be redirected and accessible from
the proxy::
145 146
  instance = request(
    software_release=apache_frontend,
147
    partition_reference='my frontend',
148 149
    shared=True,
    partition_parameter_kw={
150
        "url":"https://[1:2:3:4:5:6:7:8]:1234",
151 152
        "cache":"true",
        "type":"zope",
153
        "path":"/erp5",
154 155 156
        "custom_domain":"mycustomdomain.com",
    }
  )
157 158 159 160 161 162 163

Notes
=====

It is not possible with slapos to listen to port <= 1024, because process are
not run as root. It is a good idea then to go on the node where the instance is
and set some iptables rules like (if using default ports)::
164 165 166

  iptables -t nat -A PREROUTING -p tcp -d {public_ipv4} --dport 443 -j DNAT --to-destination {listening_ipv4}:4443
  iptables -t nat -A PREROUTING -p tcp -d {public_ipv4} --dport 80 -j DNAT --to-destination {listening_ipv4}:8080
167 168 169

Where {public ip} is the public IP of your server, or at least the LAN IP to where your NAT will forward to.
{listening ip} is the private ipv4 (like 10.0.34.123) that the instance is using and sending as connection parameter.