Note
Maintenance mode is enabled on application server as soon as the file
/public/system/maintenance.htmlis present.Note that the servers must be configured accordingly.
Installation
Add this line to your application's Gemfile:
gem 'capistrano', '~> 3.0'
gem 'capistrano-maintenance', '~> 1.0'
Add this line to you application's Capfile:
require 'capistrano/maintenance'
Enable task
Present a maintenance page to visitors. Disables your application's web interface by writing a #{maintenance_basename}.html file to each web server.
By default, the maintenance page will just say the site is down for "maintenance", and will be back "shortly", but you can customize the page by specifying the REASON and UNTIL environment variables:
cap maintenance:enable REASON="hardware upgrade" UNTIL="12pm Central Time"
You can use a different template for the maintenance page by setting the :maintenance_template_path variable in your deploy.rb file. The template file should either be a plaintext or an erb file:
set :maintenance_template_path, 'public/maintenance.html.erb'
The erb file can look like this file:
<html>
<head>
<meta content='text/html; charset=UTF-8' http-equiv='Content-Type'>
<title>Anwendung wird gewartet</title>
<style>
body { text-align: center; margin: 100px 20px; }
h1 { font-size: 50px; }
body { font: 20px Helvetica, sans-serif; color: #333; }
article { display: block; text-align: left; max-width: 650px; margin: 0 auto; }
a { color: #dc8100; text-decoration: none; }
a:hover { color: #333; text-decoration: none; }
</style>
</head>
<body>
<article>
<h1>Wartungsarbeiten</h1>
<p>
Diese Anwendung wird <%= reason %> gerade gewartet und ist <%= deadline || 'in Kürze' %> wieder verfügbar.
</p>
<p>
Wir bitten um Ihr Verständnis.
</p>
</article>
</body>
Further customization will require that you write your own task.
The path for the maintenance.html is /var/www/<project>/shared/public/system
Disable task
cap maintenance:disable
Makes the application web-accessible again. Removes the #{maintenance_basename}.html page generated by maintenance:disable, which will make your application web-accessible again.
Styling and page contents
Mind that you should inline any styles, scripts, or images (base64-encoded or <svg>) so that the maintenance page contains anything required to render properly.
Localization
If your application is localized, you may also want your maintenance page to be localized.
With the outlined approach, only a single file is served -- but you can still work with that.
It can be fine to put messages in all languages into a single page at once (hint: the lang attribute is also allowed on elements like a <div>).
You can easily enhance that with some JavaScript which looks at navigator.language and hides all messages but one.
Unpoly or other libraries that replace parts of the DOM
If your application replaces only fragments of them document on user interaction, you may run into edge cases.
For example, when always replacing the <main> element, users may see your maintenance page's <main> content while the application's remaining layout (navigation, etc.) stays unchanged. Whether this is fine or not depends on your application and your maintenance page's structure.
We recommend you verify how the application behaves when the maintenance page is enabled while a user interacts.
Manual steps
If you are still on capistrano 1, you can enable and disable the maintenance page manually.
First, prepare a maintenance.html, for example by using the template above.
Then, to enable maintenance mode, copy this file using scp to /public/system/maintenance.html on the server. Since the directory lives in gluster, you do not have to upload it to each server individually.
To disable maintenance mode, delete the file.