Display a custom response during downtime - Revision history

Th.lauke@arcor.de: typos removed, some reformatting

2024-02-19T12:46:30Z

typos removed, some reformatting

Libjlrs: Update Apache method call (which doesn't exist in modern versions) with newer call to remote_ip

2023-09-07T09:35:00Z

Update Apache method call (which doesn't exist in modern versions) with newer call to remote_ip

← Older revision		Revision as of 09:35, 7 September 2023
Line 36:		Line 36:
	# if you're not sure, ask on the EPrints Tech list first!		# if you're not sure, ask on the EPrints Tech list first!
	if( $repository->config( "maintenance_allowed_ip" ) &&		if( $repository->config( "maintenance_allowed_ip" ) &&
	$~~request->connection~~->remote_ip eq $repository->config( "maintenance_allowed_ip" ) ){		$repository->remote_ip eq $repository->config( "maintenance_allowed_ip" ) ){
	return EP_TRIGGER_OK;		return EP_TRIGGER_OK;
	}		}

Kgoetz: adding categories and link similar page

2018-08-30T06:30:39Z

adding categories and link similar page

← Older revision		Revision as of 06:30, 30 August 2018
Line 1:		Line 1:
			[[Category:Howto]]
			[[Category:Management]]

			See also [[Creating a Maintenance Page]].

	We were recently migrating our database from an old server to a new one - which required a dump + load of data (rather than a replication). This meant we had a period of 3 hours where EPrints wouldn't be accessible.		We were recently migrating our database from an old server to a new one - which required a dump + load of data (rather than a replication). This meant we had a period of 3 hours where EPrints wouldn't be accessible.

Libjlrs: Add details about database downtime

2018-07-30T15:27:06Z

Add details about database downtime

← Older revision		Revision as of 15:27, 30 July 2018
Line 3:		Line 3:
	During this downtime, I wanted to to display a useful message, with a '503 Service unavailable' HTTP response.		During this downtime, I wanted to to display a useful message, with a '503 Service unavailable' HTTP response.
	This is how to achieve this using EPrints triggers:		This is how to achieve this using EPrints triggers:
			'''NOTE''' if you are doing maintenance that means EPrints will not be able to connect to the database, the method below will not work, as EPrints will complain about not being able to connect to the database before processing the trigger. If you maintenance will result in the database being offline (rather than read-only), the maintenance page should be delivered using Apache. Please see https://stackoverflow.com/questions/622466/how-to-put-apache-website-to-503-temporary-down for some examples).

	# Create a file <code>~/archives/ARCHIVEID/cfg/cfg.d/a_MAINTENANCE.pl</code>. The name of the file isn't important - but it should be alphabetically '''before''' any other config file that defined a URL_REWRITE trigger.		# Create a file <code>~/archives/ARCHIVEID/cfg/cfg.d/a_MAINTENANCE.pl</code>. The name of the file isn't important - but it should be alphabetically '''before''' any other config file that defined a URL_REWRITE trigger.

Libjlrs: Created page with "We were recently migrating our database from an old server to a new one - which required a dump + load of data (rather than a replication). This meant we had a period of 3 hou..."

2016-03-14T15:51:36Z

Created page with "We were recently migrating our database from an old server to a new one - which required a dump + load of data (rather than a replication). This meant we had a period of 3 hou..."

New page

We were recently migrating our database from an old server to a new one - which required a dump + load of data (rather than a replication). This meant we had a period of 3 hours where EPrints wouldn't be accessible.

During this downtime, I wanted to to display a useful message, with a '503 Service unavailable' HTTP response.
This is how to achieve this using EPrints triggers:

# Create a file <code>~/archives/ARCHIVEID/cfg/cfg.d/a_MAINTENANCE.pl</code>. The name of the file isn't important - but it should be alphabetically '''before''' any other config file that defined a URL_REWRITE trigger.
# Add the following to the file, altering the <code>maintenance_ip</code>, <code>maintenance_retry_after</code> and <code>maintenance_page_html</code> appropriately. I'd keep the html page quite simple, but with enough info to help a human. Remember to escape any single-quotes in the HTML block with a backslash e.g. BAD: <code>we've</code>; GOOD: <code>we\'ve</code>.:
<source lang="perl">
# Set maintenance to 1 to respond with a 503 for requests, except those from the maintenance_ip.
$c->{maintenance} = 0;
$c->{maintenance_allowed_ip} = '127.0.0.1'; #set this to your IP address

# set to a date/time after your maintenance will have finished,
# or a period (in seconds) that the maintenance will last for
$c->{maintenance_retry_after} = 'Mon, 14 Mar 2016 12:00:00 GMT'; #set to a date/time after your maintenance will have finished

use EPrints::Const;
$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub {
my( %args ) = @_;

# args passed to EP_TRIGGER_URL_REWRITE are:
# request, lang, args, urlpath, cgipath, uri, secure, return_code
my( $repository, $request, $return_code, $uri, $urlpath ) = @args{ qw( repository request return_code uri urlpath ) };

#check we're in maintenance mode
if( $repository->config( "maintenance" ) && $repository->config( "maintenance" ) == 1 ){
# is there an IP we should allow through?
# NB You might need to do other checks - e.g. X-Forwarded-For if you are behind a load-balancer
# or for different versions of Apache (like here: https://github.com/eprints/eprints/issues/214)
# if you're not sure, ask on the EPrints Tech list first!
if( $repository->config( "maintenance_allowed_ip" ) &&
$request->connection->remote_ip eq $repository->config( "maintenance_allowed_ip" ) ){
return EP_TRIGGER_OK;
}
elsif( $uri !~ /^$urlpath\/(style|images)\// ) # allow image/stylesheet requests
# through - so you can display a branded 503 page
{
$request->custom_response( Apache2::Const::HTTP_SERVICE_UNAVAILABLE, $c->{maintenance_page_html} );
if( $repository->config( "maintenance_retry_after" ) ){
$request->err_headers_out->{'Retry-After'} = $repository->config( "maintenance_retry_after" );
}
# set the 503 response
${$return_code} = EPrints::Const::HTTP_SERVICE_UNAVAILABLE;
# and don't process any more EP_TRIGGER_URL_REWRITE triggers.
return EP_TRIGGER_DONE;
}
}
} );

# A simple maintenance page - not using the template (which will probably link to various other pages that aren't
# accessible during the maintenance window
$c->{maintenance_page_html} = '<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<style>
body {
font-family: sans-serif;
margin: 3em;
}
footer {
font-size: 80%;
margin-top:2em;
}
</style>
<title>###REPO NAME### - Maintenance</title>
</head>
<body>
<header>
<img src="/images/sitelogo.png" />
<h1>###REPO NAME### - Maintenance</h1>
</header>
<section>
<p><strong>Date/Time</strong> We\'re currently doing things to the system.<br />
We\'ll be back soon!</p>
<p>If you have any questions, please contact someone@somewhere.blah</p>
</section>
<footer>
<p>###REPO NAME###</p>
</footer>
</body>
</html>';

</source>

# Do a <code>~/bin/epadmin test ARCHIVEID</code> to make sure you haven't done anything silly in the config file.
# Do a <code>~/bin/epafmin reload ARCHIVEID</code> and check that nothing's changed
# When you want to turn the maintenance response on, change set: <code>$c->{maintenance} = 1;</code> and reload the archive.
# Check that you can get in from the IP specified, and that you get the 503 response from other IPs.
# Do a graceful restart of Apache - to stop the noisy 'repository had been reloaded' error messages.
# Do the maintenance, test.
# Change <code>$c->{maintenance} = 0;</code>, graceful restart Apache, test.
# Done!

If you want to include the default CSS files in the 503 page, include <code><link rel="stylesheet" type="text/css" href="/style/auto-3.3.14.css"></code> in the maintenance_html_page -> head section (update it for your version of EPrints!).

← Older revision		Revision as of 12:46, 19 February 2024
Line 6:		Line 6:
	We were recently migrating our database from an old server to a new one - which required a dump + load of data (rather than a replication). This meant we had a period of 3 hours where EPrints wouldn't be accessible.		We were recently migrating our database from an old server to a new one - which required a dump + load of data (rather than a replication). This meant we had a period of 3 hours where EPrints wouldn't be accessible.

	During this downtime, I wanted to to display a useful message, with a '503 Service unavailable' HTTP response.		During this downtime, I wanted to display a useful message, with a '503 Service unavailable' HTTP response.
	This is how to achieve this using EPrints triggers:		This is how to achieve this using EPrints triggers:
	'''NOTE''' if you are doing maintenance ~~that means EPrints will not be able to connect to~~ the database, the method below will not work, as EPrints will complain about not being able to connect to the database before processing the trigger. If ~~you~~ maintenance will result in the database being offline (rather than read-only), the maintenance page should be delivered using Apache. Please see https://stackoverflow.com/questions/622466/how-to-put-apache-website-to-503-temporary-down for some examples).
			'''NOTE''' if you are doing maintenance blocking the database, the '''method below will not work, as EPrints will complain about not being able to connect to the database''' before processing the trigger. If your maintenance will result in the database being offline (rather than read-only), the maintenance page should be delivered using Apache. Please see https://stackoverflow.com/questions/622466/how-to-put-apache-website-to-503-temporary-down for some examples).

	# Create a file <code>~/archives/ARCHIVEID/cfg/cfg.d/a_MAINTENANCE.pl</code>. The name of the file isn't important - but it should be alphabetically '''before''' any other config file that defined a URL_REWRITE trigger.		# Create a file <code>~/archives/ARCHIVEID/cfg/cfg.d/a_MAINTENANCE.pl</code>. The name of the file isn't important - but it should be alphabetically '''before''' any other config file that defined a URL_REWRITE trigger.
	# Add the following to the file, altering the <code>~~maintenance_ip~~</code>, <code>maintenance_retry_after</code> and <code>maintenance_page_html</code> appropriately. I'd keep the html page quite simple, but with enough info to help a human. Remember to escape any single-quotes in the HTML block with a backslash e.g. BAD: <code>we've</code>; GOOD: <code>we\'ve</code>.:		# Add the following to the file, altering the <code>maintenance_allowed_ip</code>, <code>maintenance_retry_after</code> and <code>maintenance_page_html</code> including <code>###REPO NAME###</code>, <code>Date/Time</code> and contact e-mail address appropriately. I'd keep the html page quite simple, but with enough info to help a human. Remember to '''escape any single-quotes''' in the HTML block with a backslash e.g. ''BAD'': <code>we've</code>; ''GOOD'': <code>we\'ve</code>.:
	<source lang="perl">		<source lang="perl">
	# Set maintenance to 1 to respond with a 503 for requests, except those from the ~~maintenance_ip~~.		# Set maintenance to 1 to respond with a 503 for requests, except those from the maintenance_allowed_ip.
	$c->{maintenance} = 0;		$c->{maintenance} = 0;
	$c->{maintenance_allowed_ip} = '127.0.0.1'; #set this to your IP address		$c->{maintenance_allowed_ip} = '127.0.0.1'; #set this to your IP address
Line 91:		Line 92:

	# Do a <code>~/bin/epadmin test ARCHIVEID</code> to make sure you haven't done anything silly in the config file.		# Do a <code>~/bin/epadmin test ARCHIVEID</code> to make sure you haven't done anything silly in the config file.
	# Do a <code>~/bin/~~epafmin~~ reload ARCHIVEID</code> and check that nothing's changed		# Do a <code>~/bin/epadmin reload ARCHIVEID</code> and check that nothing's changed
	# When you want to turn the maintenance response on, change set: <code>$c->{maintenance} = 1;</code> and reload the archive.		# When you want to turn the maintenance response on, change set: <code>$c->{maintenance} = 1;</code> and reload the archive.
	# Check that you can get in from the IP specified, and that you get the 503 response from other IPs.		# Check that you can get in from the IP specified, and that you get the 503 response from other IPs.
	# Do a graceful restart of Apache - to stop the noisy 'repository had been reloaded' error messages.		# Do a graceful restart of Apache (e.g. <code>apachectl graceful</code>) - to stop the noisy 'repository had been reloaded' error messages.
	# Do the maintenance~~, test~~.		# Do the maintenance.
	# Change <code>$c->{maintenance} = 0;</code>, graceful restart Apache~~, test~~.		# Change <code>$c->{maintenance} = 0;</code>, graceful restart Apache (e.g. <code>apachectl graceful</code>).
	# Done!		# Done!

	If you want to include the default CSS files in the 503 page, include <code><link rel="stylesheet" type="text/css" href="/style/auto-3.3.14.css"></code> in the maintenance_html_page -> head section (update it for your version of EPrints!).		If you want to include the default CSS files in the 503 page, include <code><link rel="stylesheet" type="text/css" href="/style/auto-3.3.14.css"></code> in the maintenance_html_page -> head section (update it for your version of EPrints!).