Read more

Showing a custom maintenance page while deploying

Pascal Roth
January 25, 2016Software engineer

Note

The maintenance mode is enabled on all application server as soon as the file /public/system/maintenance.html is present.

Installation

Add this line to your application's Gemfile:

 gem 'capistrano', '~> 3.0'
 gem 'capistrano-maintenance', '~> 1.0'
Illustration UI/UX Design

UI/UX Design by makandra brand

We make sure that your target audience has the best possible experience with your digital product. You get:

  • Design tailored to your audience
  • Proven processes customized to your needs
  • An expert team of experienced designers
Read more Show archive.org snapshot

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. The servers must be configured to detect the presence of this file, and if it is present, always display it instead of performing the request.

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.

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.

Pascal Roth
January 25, 2016Software engineer
Posted by Pascal Roth to makandra dev (2016-01-25 12:28)