Difference between revisions of "Creating a Maintenance Page"

From EPrints Documentation
Jump to: navigation, search
m
(Added ErrorDocument for 503 so it uses homepage)
 
(16 intermediate revisions by 3 users not shown)
Line 1: Line 1:
−
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. 
+
[[Category:Howto]]
 +
[[Category:Management]]
  
−
The following gufile paths ide provides instructions on how to produce a fully branded scheduled maintenance page.  It is based on approach originally developed for the CentOS 7 Linux but should work more generally but file paths are liable to be different. Simarly, 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])
+
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.
  
−
1. On the repository's server, as root copy the who of the archive's '''cfg/static/''' directory to '''/var/www/html/maintenance'''. E.g.
+
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.
  
−
  cp -r /opr/eprints3/archives/example/cfg/static/ /var/www/maintenance
+
1. Create a directory to host your maintenance page:
 +
  mkdir /var/www/maintenance
  
−
2. Move to the '''/var/www/maintenance/''' directory and download the homepage of your repostistory. E.g.
+
2. Copy the images, javascript and style directories from your archive's HTML cache directory to the maintenance page directory:
 +
cp -rf /opt/eprints3/archives/example/html/en/images /var/www/maintenance/
 +
cp -rf /opt/eprints3/archives/example/html/en/javascript /var/www/maintenance/
 +
  cp -rf /opt/eprints3/archives/example/html/en/style /var/www/maintenance/
  
−
  wget -O index.html http://eprints.example.org/
+
3. Download the homepage of your repository.  E.g.
−
 
+
  wget -O /var/www/maintenance/index.html <nowiki>http://eprints.example.org/</nowiki>
−
3. Edit '''/var/www/maintenance/index.html''' and insert the following HTML markup, adjustting 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 od you page:
 
  
 +
4. Edit '''/var/www/maintenance/index.html''' and update the '''auto-X.Y.Z.css''' and '''auto-X.Y.Z.js''' with '''auto.css''' and '''auto.js'''. Then 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):
 
  &lt;div class="ep_msg_warning"&gt;
 
  &lt;div class="ep_msg_warning"&gt;
 
   &lt;div class="ep_msg_warning_content"&gt;
 
   &lt;div class="ep_msg_warning_content"&gt;
Line 18: Line 23:
 
       &lt;tr&gt;
 
       &lt;tr&gt;
 
         &lt;td style="padding-right: 10px; padding-top: 5px; vertical-align: top;"&gt;
 
         &lt;td style="padding-right: 10px; padding-top: 5px; vertical-align: top;"&gt;
−
           &lt;img alt="Warning" src="/style/warning.png" /&gt;
+
           &lt;img alt="Warning" src="/style/images/warning.png" /&gt;
 
         &lt;/td&gt;
 
         &lt;/td&gt;
 
         &lt;td&gt;
 
         &lt;td&gt;
 
           &lt;h3 style="padding: 10px 0 5px; 0; margin: 0;"&gt;Notice of Scheduled Maintenance&lt;/h3&gt;
 
           &lt;h3 style="padding: 10px 0 5px; 0; margin: 0;"&gt;Notice of Scheduled Maintenance&lt;/h3&gt;
−
           &lt;p&gt;Please note that REPOSITORY_NAME will be unavailable from XX:XX on DD/MM/YYYY until  
+
           &lt;p&gt;Please note that REPOSITORY_NAME will be unavailable from HH:MM on DD/MM/YYYY until  
−
           XX:XX on DD/MM/YYYY due to scheduled maintenance.  We apologise for any inconvenience.&lt;/p&gt;
+
           HH:MM on DD/MM/YYYY due to scheduled maintenance.  We apologise for any inconvenience.&lt;/p&gt;
 
         &lt;/td&gt;
 
         &lt;/td&gt;
 
       &lt;/tr&gt;
 
       &lt;/tr&gt;
Line 30: Line 35:
 
  &lt;/div&gt;
 
  &lt;/div&gt;
  
−
4. In '''/root/''' create a file called '''eprints-maintenance.conf''' and add the follwoing contents.  Updating '''ServerName'' and '''ServerAdmin''' as appropriate:
+
5. Create '''/root/eprints-maintenance.conf''' containing the following lines, while updating '''ServerName''' and '''ServerAdmin''' as appropriate:
−
 
 
 
  <VirtualHost *:80>
 
  <VirtualHost *:80>
−
 
 
     ServerName eprints.example.org
 
     ServerName eprints.example.org
 
     ServerAdmin eprints@example.org
 
     ServerAdmin eprints@example.org
 
   
 
   
 
     DocumentRoot /var/www/maintenance
 
     DocumentRoot /var/www/maintenance
 +
    ErrorDocument 503 /index.html
 
     <Directory /var/www/maintenance/>
 
     <Directory /var/www/maintenance/>
 
         Options +Indexes +FollowSymLinks +MultiViews
 
         Options +Indexes +FollowSymLinks +MultiViews
Line 43: Line 47:
 
         RewriteEngine On
 
         RewriteEngine On
 
         RewriteCond %{REQUEST_URI} !(index|style|javascript|images)
 
         RewriteCond %{REQUEST_URI} !(index|style|javascript|images)
−
         RewriteRule ^ /index.html [R=302]
+
         RewriteRule ^ /index.html [R=503]
 
     </Directory>
 
     </Directory>
−
+
   
 
     ErrorLog logs/error_log
 
     ErrorLog logs/error_log
 
     TransferLog logs/access_log
 
     TransferLog logs/access_log
Line 51: Line 55:
 
  </VirtualHost>
 
  </VirtualHost>
  
−
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'' and '''ServerAdmin''' as appropriate:
+
6. Assuming 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 57: Line 61:
 
     ServerAdmin eprints@example.org
 
     ServerAdmin eprints@example.org
 
   
 
   
−
     SSLProtocol all -SSLv2 -SSLv3
+
    SSLEngine on
 +
     SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
 
     SSLHonorCipherOrder on
 
     SSLHonorCipherOrder on
−
     SSLCipherSuite HIGH:!aNULL:!eNULL:!kECDH:!aDH:!RC4:!3DES:!CAMELLIA:!MD5:!PSK:!SRP:!KRB5:@STRENGTH
+
    SSLCompression off
 +
    SSLSessionTickets off
 +
     SSLCipherSuite ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA2
 
     SSLCertificateFile /opt/eprints3/archives/example/ssl/eprints.example.org.crt
 
     SSLCertificateFile /opt/eprints3/archives/example/ssl/eprints.example.org.crt
 
     SSLCertificateKeyFile /opt/eprints3/archives/example/ssl/eprints.example.org.key
 
     SSLCertificateKeyFile /opt/eprints3/archives/example/ssl/eprints.example.org.key
Line 65: Line 72:
 
   
 
   
 
     DocumentRoot /var/www/maintenance
 
     DocumentRoot /var/www/maintenance
 +
    ErrorDocument 503 /index.html
 
     <Directory /var/www/maintenance/>
 
     <Directory /var/www/maintenance/>
 
         Options +Indexes +FollowSymLinks +MultiViews
 
         Options +Indexes +FollowSymLinks +MultiViews
 
         Require all granted
 
         Require all granted
 
         RewriteEngine On
 
         RewriteEngine On
−
         RewriteCond %{REQUEST_URI} !(index|style|javascript|surrey)
+
         RewriteCond %{REQUEST_URI} !(index|style|javascript|images)
−
         RewriteRule ^ /index.html [R=302]
+
         RewriteRule ^ /index.html [R=503]
 
     </Directory>
 
     </Directory>
 
   
 
   
Line 85: Line 93:
 
  </VirtualHost>
 
  </VirtualHost>
  
−
6. Next you will need to find the line in ''/etc/httpd/''' (On RHEL/CentOS/Fedora) or '''/etc/apache2/''' (on Ubuntu/Debian):
+
7. Next you will need to find the first line below in '''/etc/httpd/''' (On RHEL/CentOS/Fedora) or '''/etc/apache2/''' (on Ubuntu/Debian) and comment it out and add the second line:
 
  Include /opt/eprints3/cfg/apache.conf
 
  Include /opt/eprints3/cfg/apache.conf
−
and comment it out and below put the line:
 
 
  Include /root/eprints-maintenance.conf
 
  Include /root/eprints-maintenance.conf
  
−
7. Again if you are running HTTPS on you repository you will need to find the following or similar line in ''/etc/httpd/''' or '''/etc/apache2/''':
+
8. Assuming you are running HTTPS on your repository you will need to find the first line of something in '''/etc/httpd/''' or '''/etc/apache2/''' and comment it out and then add the second line:
 
  Include /opt/eprints3/archives/*/ssl/securevhost.conf
 
  Include /opt/eprints3/archives/*/ssl/securevhost.conf
−
and comment it out and below put:
 
 
  Include /root/eprints-maintenance-ssl.conf
 
  Include /root/eprints-maintenance-ssl.conf
  
−
8. Finally, you will need to restart the webserver:
+
9. Finally, you will need to restart the web server:
−
 
 
 
  apachectl restart
 
  apachectl restart
  
−
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
+
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 webserver like in step 8.  
+
Once maintenance is completed, all you need to do the reverse the commenting out in steps 7 and 8 as appropriate. (Keeping the new lines but commented out will save you time if you need to re-enable the maintenance page in future).  Then just restart the web server again.  
  
−
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 webserver 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 7 and 8 as appropriate and restart the web server and your maintenance page is back in place.

Latest revision as of 15:37, 2 August 2024


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.

1. Create a directory to host your maintenance page: 

mkdir /var/www/maintenance

2. Copy the images, javascript and style directories from your archive's HTML cache directory to the maintenance page directory: 

cp -rf /opt/eprints3/archives/example/html/en/images /var/www/maintenance/
cp -rf /opt/eprints3/archives/example/html/en/javascript /var/www/maintenance/
cp -rf /opt/eprints3/archives/example/html/en/style /var/www/maintenance/

3. Download the homepage of your repository. E.g. 

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

4. Edit /var/www/maintenance/index.html and update the auto-X.Y.Z.css and auto-X.Y.Z.js with auto.css and auto.js. Then 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/images/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>

5. 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
    ErrorDocument 503 /index.html
    <Directory /var/www/maintenance/>
        Options +Indexes +FollowSymLinks +MultiViews
        Require all granted
        RewriteEngine On
        RewriteCond %{REQUEST_URI} !(index|style|javascript|images)
        RewriteRule ^ /index.html [R=503]
    </Directory>
   
    ErrorLog logs/error_log
    TransferLog logs/access_log
    LogLevel warn
</VirtualHost>

6. Assuming 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

    SSLEngine on
    SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
    SSLHonorCipherOrder on
    SSLCompression off
    SSLSessionTickets off
    SSLCipherSuite ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA2
    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
    ErrorDocument 503 /index.html
    <Directory /var/www/maintenance/>
        Options +Indexes +FollowSymLinks +MultiViews
        Require all granted
        RewriteEngine On
        RewriteCond %{REQUEST_URI} !(index|style|javascript|images)
        RewriteRule ^ /index.html [R=503]
    </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>

7. Next you will need to find the first line below in /etc/httpd/ (On RHEL/CentOS/Fedora) or /etc/apache2/ (on Ubuntu/Debian) and comment it out and add the second line: 

Include /opt/eprints3/cfg/apache.conf
Include /root/eprints-maintenance.conf

8. Assuming you are running HTTPS on your repository you will need to find the first line of something in /etc/httpd/ or /etc/apache2/ and comment it out and then add the second line: 

Include /opt/eprints3/archives/*/ssl/securevhost.conf
Include /root/eprints-maintenance-ssl.conf

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

apachectl restart

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 the reverse the commenting out in steps 7 and 8 as appropriate. (Keeping the new lines but commented out will save you time if you need to re-enable the maintenance page in future). Then just restart the web server again.

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 7 and 8 as appropriate and restart the web server and your maintenance page is back in place.

Retrieved from ‘https://wiki.eprints.org/w/index.php?title=Creating_a_Maintenance_Page&oldid=16659’