From fbd9ebabea09aadcc7b833af5a8ba0909001e41a Mon Sep 17 00:00:00 2001 From: Daniel Thee Roperto Date: Fri, 16 Dec 2016 19:03:29 +1100 Subject: [PATCH] Added quick guide with step-by-step instructions on how to use this plugin. --- QUICKGUIDE.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 7 +++ 2 files changed, 153 insertions(+) create mode 100644 QUICKGUIDE.md diff --git a/QUICKGUIDE.md b/QUICKGUIDE.md new file mode 100644 index 0000000..0ede83f --- /dev/null +++ b/QUICKGUIDE.md @@ -0,0 +1,146 @@ +# Quick Guide + + * [Installation](#installation) + * [Basic Usage](#basic-usage) + * [IP Blocking](#ip-blocking) + +Installation +------------ + +Please check [README.md](README.md#installation) + +Basic Usage +----------- + +1) Create an outage in the future + + Go to + `Dashboard ► Site administration ► Plugins ► Authentication ► Outage manager ► Manage` + and click `Create outage` to create an outage with the following settings: + + - Outage auto start: `false` + - Warning duration: `1 hour` + - Start date and time: `Somewhere around 2 hours from now` + - Outage duration: `1 hour` + - Title and Description: `Leave default` + + _You should not see any warning message yet._ + +1) Change that outage to activate the warning + + Edit the outage, set: + + - Start date and time: `Sometime in the future but less than 1 hour from now` + + _The warning bar with a countdown is displayed!_ + + **What is happening now?** + Nothing, this is just a warning for all users. + +1) Change that outage so it becomes active + + Edit the outage, set: + + - Start date and time: `Sometime in the past but less than 1 hour ago` + + _The warning changes color and shows the outage estimated end time._ + + **What is happening now?** + Nothing yet, it is just a warning to all users that the system may be unstable but it is still online. + That will change when we are using the IP Blocking feature. + +1) Activate maintenance mode + + **Note:** This step will happen automatically if you create an outage with the option to `Auto start maintenance mode`. + + Execute the following command from your Moodle instalation directory: + + `php admin/cli/maintenance.php --enable` + + _Anyone who tries to use Moodle now will receive a maintenance message._ + +1) Perform the maintenance activities. + + At this point it is safe to perform the required maintenance as no one can use the system, not even admins. + +1) Disable the maintenance mode + + `php admin/cli/maintenance.php --disable` + + _Your site is back, but the outage warning still shows the maintenance (unless the outage ending time has reached)._ + +1) End the outage + + Using the GUI, you can do it in a few different ways (choose one) + - Click 'Finish' at the warning bar + - Click 'Finish' at the outage management page + - Edit the outage and lower the duration so it is finished by now + + _The outage bar should disappear (you may need to refresh the page)._ + + +IP Blocking +----------- + +We will manage outages from the CLI this time, but it does not matter which way you create them. + +Execute the commands from your Moodle instalation directory and leave the browser open so you can see the changes. + +1) Enable IP Blocker and allow your IP Address + + Go to + `Dashboard ► Site administration ► Plugins ► Authentication ► Outage manager ► Settings` + and set `Allowed IP list` to `127.0.0.1` (or your IP address if not local). + +1) Create an outage + + This command will create an outage starting in 30 seconds, with a warning period of 15 seconds. + It will automatically start (trigger maintenance mode). + + `php auth/outage/cli/create.php -w=20 -s=30 --autostart=Y` + + Refresh the page but you will not see anything yet. + +1) Wait until it starts + + Keep refreshing the page, in less than 10 seconds it will display the warning. + + Wait until the outage starts. + +1) Maintenance mode should be active + + You cannot browse anymore because Moodle's maintenance mode is active, no one can use the system until it is manually disabled. + +1) Perform the maintenance activities. + + At this point it is safe to perform the required maintenance as no one can use the system, not even admins. + +1) Disable maintenance mode. + + `php admin/cli/maintenance.php --disable` + +1) Browse with an allowed IP + + **Do not finish the outage yet...** + + Because you are white-listed in the IP Blocking, you can test the site while it is not open for normal users. + +1) Browse with a blocked IP + + Change the IP settings to a different IP (but do not leave it blank, which disables IP Blocking): + + Go to + `Dashboard ► Site administration ► Plugins ► Authentication ► Outage manager ► Settings` + and set `Allowed IP list` to `1.2.3.4` + + Save and refresh. + + _You should see the maintenance page until the outage period is over._ + +1) Finish the outage + + Finish the outage using the CLI: + + `php auth/outage/cli/finish.php --active` + + Now the site is back and available for everyone. diff --git a/README.md b/README.md index fbdb2d0..cf482b8 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ * [Screenshots](#screenshots) * [Installation](#installation) * [How to use](#how-to-use) +* [Quick Guide](#quick-guide) * [Why is it an auth plugin?](#why-it-is-an-auth-plugin) * [Feedback and issues](#feedback-and-issues) @@ -106,6 +107,12 @@ Creates a new outage. -b, --block blocks until outage starts. ``` +Quick Guide +----------- + +Please see [QUICKGUIDE.md](QUICKGUIDE.md) for step-by-step examples on +how to test and use the Outage Manager. + Why it is an auth plugin? -------------------------