/
cookbook_maintenance.txt
143 lines (117 loc) · 5.49 KB
/
cookbook_maintenance.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
== link:index.html[Index] -> link:cookbook.html[Cookbook]
Cookbook: Maintenance
---------------------
This recipe will show how to seamlessly switch the webserver to
maintenance mode. By that it is understood that no existing
connections should be interrupted, but new connections should be
notified of the situation. This could be done serving some generic
static content.
All this is easily achieved by Cherokee thanks to its
link:other_goodies.html#zero-downtime[Zero Downtime] mechanism.
We will be showing a couple of use cases. The first one is mostly to
illustrate the general process and will be set to serve a custom HTTP
Error. It is very simple and straightforward, but is also pretty
useless in a production environment. The second use case will be more
advanced. It will be useful to serve a static maintenance message to
the public while the administrator will retain the ability to see the
actual changes.
[[basic]]
Basic Example
~~~~~~~~~~~~~
The steps are fairly simple:
- Create a new virtual host, a copycat, that can handle the same
domain(s) as the ones managed by the host to be put offline.
+
image::media/images/cookbook_maintenance_copy.png[Copycat]
- Don't forget to set up the domains handled by the virtual host.
+
image::media/images/cookbook_maintenance_domain.png[Domain]
- Also remember setting up whatever response you will be requiring (a
custom error, some static content, and so on). We will be setting up
the link:modules_handlers_custom_error.html[HTTP error] handler to
give a `503: Service unavailable' message.
+
image::media/images/cookbook_maintenance_error.png[HTTP Error]
+
- After setting up this way our sole rule, it should look like this:
+
image::media/images/cookbook_maintenance_rule.png[Rule]
- Make sure the copycat is positioned above the original virtual host,
effectively having a higher priority for it. By default the new
virtual hosts are positioned on top of the rest. Just make sure you
don't inadvertently change the relative priorities.
+
image::media/images/cookbook_maintenance_result.png[Final result]
- Make a *graceful restart*.
This can be done from the SAVE dialog. By doing this, the existing
connections to the original virtual host will be preserved and will
eventually end upon completion. At the same time, new requests will be
delivered to its copycat and will be handled according to its
specified behavior. If you don't want this behavior you can always
make a *hard restart*, effectively shutting down every existing
connection.
By now you are almost done. Now you can make whatever changes were
needed to the original host without affecting the incoming
connections.
Remember to reverse the process once you are done. You'll only have to
delete the copycat or position it below the real virtual host.
[[advanced1]]
Advanced Example: Static message
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- The first two steps are the same: create a copycat, and make it handle
the same domains.
- Our virtual host will have only two rules. The first one will match
against a maintenance directory that will be managed by the "List &
Send" handler. Enabling IO/Cache and Encoding will be a plus here
since the contents are static by definition. You should probably
configure the `Directory indexes` in the `Basics` tab of the virtual
host for the `List & Send` handler to work properly. The second one
will be the the `Default` rule that will be redirecting every
request to the first rule as an internal redirection.
+
image::media/images/cookbook_maintenance_advanced_rules.png[Rules]
- The `Default` rule should be set to redirect more or less like this:
+
image::media/images/cookbook_maintenance_advanced_redir.png[Default]
This set up will result in every request being redirected to the
maintenance directory.
[[advanced2]]
Advanced Example: Staff review
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By now you should be able of switching the server to and from
maintenance mode.
The next essential feature needed is to allow specific users to be
able to access the original site, not the maintenance version, so that
they can view the changes reflected while they are working.
The tweaking here has to take place in the original virtual
server. The steps are also fairly simple.
- In this example we will be adding a new
imaginary domain to the list of domains managed by the virtual
host. This domain should be accessible from our intranet only.
+
image::media/images/cookbook_maintenance_advanced_domains.png[Domains]
+
[NOTE]
As mentioned in the link:config_virtual_servers.html[Virtual Servers]
section, you should keep in mind the way the domain lists are
interpreted. Whenever Cherokee receives a request for a specific
domain, it evaluates the `Domain list` of every defined virtual host
in the order defined by the priorities of such hosts. If no domain
name matches the request, Cherokee re-evaluates the list of virtual
hosts as before, trying to match the request against the `Nicknames`.
Only after failing both with the domain names and the nicknames will
Cherokee issue the failure.
- And we will add this domain to our /etc/hosts file as an alias for
the real server.
+
----
10.0.0.118 intranet_example
----
+
In this case we are using the IP address assigned to the server in our
intranet, and this will grant access from our computer to the original
site whether the copycat is present or not.
+
You might want to reflect such configuration in a private DNS in case
you need more flexibility, restrict access to specific IP ranges and
similar security measures, but the principles are the same.