Difference between revisions of "Creating a Maintenance Page"

From EPrints Documentation
Jump to: navigation, search
m (adding categories)
m (typos correct, formatting harmonised)
Line 2: Line 2:
 
[[Category:Management]]
 
[[Category:Management]]
  
Sometimes there is a need to be able to completely disable access to content on your repository but you want users to be aware that the repository is just unavailable temporarily for scheduled maintenance, which turning off you web server would not be possible.  A common situation where you may want to do this is when you need to make alterations to the database and you want to ensure this does not otherwise change whilst you are making these alterations.  The best way of doing this is to create a maintenance page, for which requests to you repository will be redirected.   
+
Sometimes there is a need to be able to completely disable access to content on your repository, but you want users to be aware that the repository is just unavailable temporarily for scheduled maintenance, which turning off your web server would not be possible.  A common situation where you may want to do this is when you need to make alterations to the database and you want to ensure this does not otherwise change whilst you are making these alterations.  The best way of doing this is to create a maintenance page, for which requests to your repository will be redirected.   
  
The following guide provides instructions on how to produce a fully branded maintenance page.  It is based on an approach originally developed for the CentOS 7 Linux but should work more generally, however, file paths are liable to be different. Similarly, if you running Apache 2.2, then the '''Require all granted''' line will be different (see [https://httpd.apache.org/docs/2.4/upgrading.html])
+
The following guide provides instructions on how to produce a fully branded maintenance page.  It is based on an approach originally developed for the CentOS 7 Linux but should work more generally, however, file paths are liable to be different. Similarly, if you are running Apache 2.2, then the '''Require all granted''' line will be different (see [https://httpd.apache.org/docs/2.4/upgrading.html#access Apache's Upgrade Note]).
  
1. On the repository's server, as root create a sy the who of the archive's '''cfg/static/''' directory to '''/var/www/maintenance'''. E.g.
+
<ol><li>
 +
On the repository's server, as root create a copy of the archive's '''cfg/''lang/langID/''static/''' directory to '''/var/www/maintenance'''. E.g.<br>
  
cp -r /opr/eprints3/archives/example/cfg/static/ /var/www/maintenance
+
<code>cp -r /opt/eprints3/archives/example/cfg/static/ /var/www/maintenance</code>
 +
</li><li>
 +
Move to the '''/var/www/maintenance/''' directory and download the homepage of your repository.  E.g.
  
2. Move to the '''/var/www/maintenance/''' directory and download the homepage of your repostistory.  E.g.
+
<code>wget -O index.html <nowiki>http://eprints.example.org/</nowiki></code>
 
+
</li><li>
wget -O index.html http://eprints.example.org/
+
Edit '''/var/www/maintenance/index.html''' and insert the following HTML markup, adjusting the dates '''DD/MM/YYYY''', time '''HH:MM''' and '''REPOSITORY_NAME''' as appropriate.  Where to put this will vary between repository; it is usually best placed after the title in the main content part of your page.  (It may also be worth removing various parts of this page, such as the Latest Additions, as visitors will not be able to access them):
 
 
3. Edit '''/var/www/maintenance/index.html''' and insert the following HTML markup, adjusting the dates, time and '''REPOSITORY_NAME''' as appropriate.  Where to put this will vary between repository it is usually best placed after the title in the main content part of your page.  (It may also be worth removing various parts of this page, such as the Latest Additions, as visitors will not be able to access them):
 
  
 
  &lt;div class="ep_msg_warning"&gt;
 
  &lt;div class="ep_msg_warning"&gt;
Line 32: Line 33:
 
   &lt;/div&gt;
 
   &lt;/div&gt;
 
  &lt;/div&gt;
 
  &lt;/div&gt;
 
+
</li><li>
4. In '''/root/''' create a file called '''eprints-maintenance.conf''' and add the following contents.  Updating '''ServerName''' and '''ServerAdmin''' as appropriate:
+
Create '''/root/eprints-maintenance.conf''' containing the following lines, while updating '''ServerName''' and '''ServerAdmin''' as appropriate:
  
 
  <VirtualHost *:80>
 
  <VirtualHost *:80>
Line 52: Line 53:
 
     LogLevel warn
 
     LogLevel warn
 
  </VirtualHost>
 
  </VirtualHost>
 
+
</li><li>
5. If your repository uses HTTPS you will also need to create a file called ''eprints-maintenance-ssl.conf''' with the following contents. Updating '''ServerName''', '''ServerAdmin''', '''SSLCertificateFile'', '''SSLCertificateKeyFile''' and ''SSLCertificateChainFile''' as appropriate:
+
If your repository uses '''HTTPS''' you will also need to create a file called '''/root/eprints-maintenance-ssl.conf''' with the following contents. Update '''ServerName''', '''ServerAdmin''', '''SSLCertificateFile''', '''SSLCertificateKeyFile''' and '''SSLCertificateChainFile''' as appropriate:
  
 
  <VirtualHost *:443>
 
  <VirtualHost *:443>
Line 86: Line 87:
 
     LogLevel warn
 
     LogLevel warn
 
  </VirtualHost>
 
  </VirtualHost>
 +
</li><li>
 +
Next you will need to find the line in '''/etc/httpd/''' (On RHEL/CentOS/Fedora) or '''/etc/apache2/''' (on Ubuntu/Debian):
 +
 +
<code> Include /opt/eprints3/cfg/apache.conf</code>
  
6. Next you will need to find the line in ''/etc/httpd/''' (On RHEL/CentOS/Fedora) or '''/etc/apache2/''' (on Ubuntu/Debian):
 
Include /opt/eprints3/cfg/apache.conf
 
 
and comment it out and below put the line:
 
and comment it out and below put the line:
Include /root/eprints-maintenance.conf
 
  
7. Again if you are running HTTPS on your repository you will need to find the following or similar line in ''/etc/httpd/''' or '''/etc/apache2/''':
+
<code> Include /root/eprints-maintenance.conf</code>
Include /opt/eprints3/archives/*/ssl/securevhost.conf
+
</li><li>
 +
Again if you are running HTTPS on your repository you will need to find the following or similar line in '''/etc/httpd/''' or '''/etc/apache2/''':
 +
 
 +
<code> Include /opt/eprints3/archives/*/ssl/securevhost.conf</code>
 +
 
 
and comment it out and below put:
 
and comment it out and below put:
Include /root/eprints-maintenance-ssl.conf
 
 
8. Finally, you will need to restart the web server:
 
  
apachectl restart
+
<code> Include /root/eprints-maintenance-ssl.conf</code>
 +
</li><li>
 +
Finally, you will need to restart the web server:
  
You should now see that any request to your repository is redirected to '''/index.html''' (e.g. http://eprints.example.org/index.html), which displays your maintenance page
+
<code> apachectl graceful</code>
 +
</li>
 +
</ol>
 +
You should now see that any request to your repository is redirected to '''/index.html''' (e.g. <nowiki>http://eprints.example.org/index.html</nowiki>), which displays your maintenance page.
  
Once maintenance is complete all you need to do is uncomment the line(s) commented out in step 6 (and step 7) where appropriate and to save time for future scheduled maintenance, comment out the new lines you added.  Then just restart the web server like in step 8.  
+
Once maintenance is completed all you need to do is uncomment the line(s) commented out in step 6 (and step 7) where appropriate and to save time for future scheduled maintenance, comment out the new lines you added.  Then just restart the web server like in step 8.  
  
If you have planned maintenance again, assuming your branding does not change in the meantime, all you need to do is update the times in '''/var/www/maintenance/index.html''' uncomment and comment out the lines in steps 6 and 7 as appropriate and restart the web server and your maintenance page is backe in place.
+
If you have planned maintenance again, assuming your branding does not change in the meantime, all you need to do is update the times in '''/var/www/maintenance/index.html''' uncomment and comment out the lines in steps 6 and 7 as appropriate and restart the web server and your maintenance page is back in place.

Revision as of 15:36, 30 August 2018


Sometimes there is a need to be able to completely disable access to content on your repository, but you want users to be aware that the repository is just unavailable temporarily for scheduled maintenance, which turning off your web server would not be possible. A common situation where you may want to do this is when you need to make alterations to the database and you want to ensure this does not otherwise change whilst you are making these alterations. The best way of doing this is to create a maintenance page, for which requests to your repository will be redirected.

The following guide provides instructions on how to produce a fully branded maintenance page. It is based on an approach originally developed for the CentOS 7 Linux but should work more generally, however, file paths are liable to be different. Similarly, if you are running Apache 2.2, then the Require all granted line will be different (see Apache's Upgrade Note).

  1. On the repository's server, as root create a copy of the archive's cfg/lang/langID/static/ directory to /var/www/maintenance. E.g.
    cp -r /opt/eprints3/archives/example/cfg/static/ /var/www/maintenance
  2. Move to the /var/www/maintenance/ directory and download the homepage of your repository. E.g.

    wget -O index.html http://eprints.example.org/

  3. Edit /var/www/maintenance/index.html and insert the following HTML markup, adjusting the dates DD/MM/YYYY, time HH:MM and REPOSITORY_NAME as appropriate. Where to put this will vary between repository; it is usually best placed after the title in the main content part of your page. (It may also be worth removing various parts of this page, such as the Latest Additions, as visitors will not be able to access them):

    <div class="ep_msg_warning">
      <div class="ep_msg_warning_content">
        <table style="padding:5px">
          <tr>
            <td style="padding-right: 10px; padding-top: 5px; vertical-align: top;">
              <img alt="Warning" src="/style/warning.png" />
            </td>
            <td>
              <h3 style="padding: 10px 0 5px; 0; margin: 0;">Notice of Scheduled Maintenance</h3>
              <p>Please note that REPOSITORY_NAME will be unavailable from HH:MM on DD/MM/YYYY until 
              HH:MM on DD/MM/YYYY due to scheduled maintenance.  We apologise for any inconvenience.</p>
            </td>
          </tr>
        </table>
      </div>
    </div>
    
  4. Create /root/eprints-maintenance.conf containing the following lines, while updating ServerName and ServerAdmin as appropriate:

    <VirtualHost *:80>
        ServerName eprints.example.org
        ServerAdmin eprints@example.org
    
        DocumentRoot /var/www/maintenance
        <Directory /var/www/maintenance/>
            Options +Indexes +FollowSymLinks +MultiViews
            Require all granted
            RewriteEngine On
            RewriteCond %{REQUEST_URI} !(index|style|javascript|images)
            RewriteRule ^ /index.html [R=302]
        </Directory>
    
        ErrorLog logs/error_log
        TransferLog logs/access_log
        LogLevel warn
    </VirtualHost>
    
  5. If your repository uses HTTPS you will also need to create a file called /root/eprints-maintenance-ssl.conf with the following contents. Update ServerName, ServerAdmin, SSLCertificateFile, SSLCertificateKeyFile and SSLCertificateChainFile as appropriate:

    <VirtualHost *:443>
        ServerName eprints.example.org
        ServerAdmin eprints@example.org
    
        SSLProtocol all -SSLv2 -SSLv3
        SSLHonorCipherOrder on
        SSLCipherSuite HIGH:!aNULL:!eNULL:!kECDH:!aDH:!RC4:!3DES:!CAMELLIA:!MD5:!PSK:!SRP:!KRB5:@STRENGTH
        SSLCertificateFile /opt/eprints3/archives/example/ssl/eprints.example.org.crt
        SSLCertificateKeyFile /opt/eprints3/archives/example/ssl/eprints.example.org.key
        SSLCertificateChainFile /opt/eprints3/archives/example/ssl/eprints.example.org.ca-bundle
    
        DocumentRoot /var/www/maintenance
        <Directory /var/www/maintenance/>
            Options +Indexes +FollowSymLinks +MultiViews
            Require all granted
            RewriteEngine On
            RewriteCond %{REQUEST_URI} !(index|style|javascript|surrey)
            RewriteRule ^ /index.html [R=302]
        </Directory>
    
        SetEnvIf User-Agent ".*MSIE.*" \
            nokeepalive ssl-unclean-shutdown \
            downgrade-1.0 force-response-1.0
    
        CustomLog logs/ssl_request_log \
             "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
    
        ErrorLog logs/ssl_error_log
        TransferLog logs/ssl_access_log
        LogLevel warn
    </VirtualHost>
    
  6. Next you will need to find the line in /etc/httpd/ (On RHEL/CentOS/Fedora) or /etc/apache2/ (on Ubuntu/Debian):

    Include /opt/eprints3/cfg/apache.conf

    and comment it out and below put the line:

    Include /root/eprints-maintenance.conf

  7. Again if you are running HTTPS on your repository you will need to find the following or similar line in /etc/httpd/ or /etc/apache2/:

    Include /opt/eprints3/archives/*/ssl/securevhost.conf

    and comment it out and below put:

    Include /root/eprints-maintenance-ssl.conf

  8. Finally, you will need to restart the web server:

    apachectl graceful

You should now see that any request to your repository is redirected to /index.html (e.g. http://eprints.example.org/index.html), which displays your maintenance page.

Once maintenance is completed all you need to do is uncomment the line(s) commented out in step 6 (and step 7) where appropriate and to save time for future scheduled maintenance, comment out the new lines you added. Then just restart the web server like in step 8.

If you have planned maintenance again, assuming your branding does not change in the meantime, all you need to do is update the times in /var/www/maintenance/index.html uncomment and comment out the lines in steps 6 and 7 as appropriate and restart the web server and your maintenance page is back in place.