django-maintenance-mode shows a 503 error page when maintenance-mode is on.
Project description
django-maintenance-mode
django-maintenance-mode shows a 503 error page when maintenance-mode is on.
It works at application level, so your django instance should be up.
It doesn’t use database and doesn’t prevent database access.
Requirements
Python 2.7, 3.4, 3.5, 3.6, 3.7
Django 1.7, 1.8, 1.9, 1.10, 1.11, 2.0, 2.1, 2.2
Installation
Run pip install django-maintenance-mode or download django-maintenance-mode and add the maintenance_mode package to your project
Add 'maintenance_mode' to settings.INSTALLED_APPS before custom applications
Add 'maintenance_mode.middleware.MaintenanceModeMiddleware' to settings.MIDDLEWARE_CLASSES/settings.MIDDLEWARE as last middleware
Add 'maintenance_mode.context_processors.maintenance_mode' to settings.CONTEXT_PROCESSORS
Add your custom templates/503.html file
Restart your application server
Configuration (optional)
Settings
All these settings are optional, if not defined in settings.py the default values (listed below) will be used.
# if True the maintenance-mode will be activated
MAINTENANCE_MODE = None
# by default, to get/set the state value a local file backend is used
# if you want to use the db or cache, you can create a custom backend
# custom backends must extend 'maintenance_mode.backends.AbstractStateBackend' class
# and implement get_value(self) and set_value(self, val) methods
MAINTENANCE_MODE_STATE_BACKEND = 'maintenance_mode.backends.LocalFileBackend'
# by default, a file named "maintenance_mode_state.txt" will be created in the maintenance_mode directory
# you can customize the state file path in case the default one is not writable
MAINTENANCE_MODE_STATE_FILE_PATH = 'maintenance_mode_state.txt'
# if True admin site will not be affected by the maintenance-mode page
MAINTENANCE_MODE_IGNORE_ADMIN_SITE = False
# if True anonymous users will not see the maintenance-mode page
MAINTENANCE_MODE_IGNORE_ANONYMOUS_USER = False
# if True authenticated users will not see the maintenance-mode page
MAINTENANCE_MODE_IGNORE_AUTHENTICATED_USER = False
# if True the staff will not see the maintenance-mode page
MAINTENANCE_MODE_IGNORE_STAFF = False
# if True the superuser will not see the maintenance-mode page
MAINTENANCE_MODE_IGNORE_SUPERUSER = False
# list of ip-addresses that will not be affected by the maintenance-mode
# ip-addresses will be used to compile regular expressions objects
MAINTENANCE_MODE_IGNORE_IP_ADDRESSES = ()
# the path of the function that will return the client IP address given the request object -> 'myapp.mymodule.myfunction'
# the default function ('maintenance_mode.utils.get_client_ip_address') returns request.META['REMOTE_ADDR']
# in some cases the default function returns None, to avoid this scenario just use 'django-ipware'
MAINTENANCE_MODE_GET_CLIENT_IP_ADDRESS = None
Retrieve user’s real IP address using django-ipware:
MAINTENANCE_MODE_GET_CLIENT_IP_ADDRESS = 'ipware.ip.get_ip'
# list of urls that will not be affected by the maintenance-mode
# urls will be used to compile regular expressions objects
MAINTENANCE_MODE_IGNORE_URLS = ()
# if True the maintenance mode will not return 503 response while running tests
# useful for running tests while maintenance mode is on, before opening the site to public use
MAINTENANCE_MODE_IGNORE_TESTS = False
# the absolute url where users will be redirected to during maintenance-mode
MAINTENANCE_MODE_REDIRECT_URL = None
# the template that will be shown by the maintenance-mode page
MAINTENANCE_MODE_TEMPLATE = '503.html'
# the path of the function that will return the template context -> 'myapp.mymodule.myfunction'
MAINTENANCE_MODE_GET_TEMPLATE_CONTEXT = None
# the HTTP status code to send
MAINTENANCE_MODE_STATUS_CODE = 503
# the value in seconds of the Retry-After header during maintenance-mode
MAINTENANCE_MODE_RETRY_AFTER = 3600 # 1 hour
URLs
Add maintenance_mode.urls to urls.py if you want superusers able to set maintenance_mode using urls.
urlpatterns = [
# ...
url(r'^maintenance-mode/', include('maintenance_mode.urls')),
# ...
]
Context Processors
Add maintenance_mode.context_processors.maintenance_mode to your context_processors list in settings.py if you want to access the maintenance_mode status in your templates.
TEMPLATES = [
{
# ...
'OPTIONS': {
'context_processors': [
# ...
'maintenance_mode.context_processors.maintenance_mode',
# ...
],
},
# ...
},
]
Views
You can force maintenance mode on/off at view level using view decorators:
from maintenance_mode.decorators import force_maintenance_mode_off, force_maintenance_mode_on
@force_maintenance_mode_off
def my_view_a(request):
# never return 503 response
pass
@force_maintenance_mode_on
def my_view_b(request):
# always return 503 response
pass
Usage
Python
from maintenance_mode.core import get_maintenance_mode, set_maintenance_mode
set_maintenance_mode(True)
if get_maintenance_mode():
set_maintenance_mode(False)
or
from django.core.management import call_command
from django.core.management.base import BaseCommand
class Command(BaseCommand):
def handle(self, *args, **options):
call_command('maintenance_mode', 'on')
# call your command(s)
call_command('maintenance_mode', 'off')
Templates
{% if maintenance_mode %}
<!-- html -->
{% endif %}
Terminal
Run python manage.py maintenance_mode <on|off>
(This is not Heroku-friendly because any execution of heroku run manage.py will be run on a separate worker dyno, not the web one. Therefore the state-file is set but on the wrong machine)
URLs
Superusers can change maintenance-mode using the following urls:
/maintenance-mode/off/
/maintenance-mode/on/
License
Released under MIT License.