Initial setup for Wagtail

Similar to the Wordpress install, adapted for Wagtail. Runs for superusers when they log in to the admin.

Things that need setting up

The default Site instance used for this deployment: URL, title, etc.
Create a Homepage of the correct page type.
More in the future?

Things that do not need setting up

Database config, other things that belong in settings.py

Technical details

It would be run just after login.

On successful login, check for setup views that need to be run. If there are not any, redirect to the landing page as normal
If there are outstanding setup steps, redirect to /admin/setup/[name]/, and show the setup.
Complete the step, and check for more setup views.
Once all steps are completed, redirect to the dashboard.

Setup views

Registered in apps. They just need a view function and a name:

@setup.register_step(name='my_setup')
def my_setup(request):
    ...

The view would do what ever it needs to do, such as presenting a form and recording details. When all required information had been collected, the setup step should be marked as completed, and the user redirected to the next step:

from wagtail.wagtailadmin import setup

@setup.register_step(name='my_setup')
def my_setup(request):
    if request.method == 'POST':
        form = MySetupForm(request.POST)
        if form.is_valid():
            form.save()
            setup.complete_step('my_setup')
            return setup.next_step_redirect()
    else:
        form = MySetupForm()
    return render(request, 'my_app/my_setup.html', {'form': form})

setup.next_step_redirect would check for more setup steps that need to be run, and redirect to them if they exist. If they do not exist, redirect to the default landing page.

Steps can be registered with a priority, allowing developers to order their steps in order of importance. Steps will be registered with a medium priority by default.

@setup.register_step(name='my_setup', priority=setup.PRIORITY_LOW)
def my_setup(request):
    pass

(Alternatively, steps could be dependent on other steps? More complicated, perhaps needlessly so.)

Implementation

Each setup view would register itself:

# wagtail.wagtailadmin.setup

import bisect
from collections import namedtuple

step_queue = []
step_dict = {}
Step = namedtuple('priority name view'.split(' '))

def register_step(name, priority=PRIORITY_MEDIUM):
    def decorator(view):
        step = Step(priority, name, view)
        bisect.insort(step_queue, step)
        step_dict[name] = step
        return view
    return decorator

When a view is completed, this fact would be saved to the database in a CompletedStep model:

# wagtail.wagtailadmin.models

class CompletedStep(models.Model):
    name = models.CharField(max_length=255, unique=True)
    completed_on = models.DateTimeField(auto_now_add=True)

Each call to setup.next_step_redirect would check all registered views, and find any not in the database already:

# wagtail.wagtailadmin.setup

from .models import CompletedStep

def get_next_step():
    completed_steps = CompletedStep.objects.values('name')
    completed_step_names = {step['name'] for step in completed_steps}
    for step in steps:
        if step.name not in completed_step_names:
            return step
    return None

def next_step_redirect():
    next_step = get_next_step()
    if next_step is not None:
        return redirect('wagtailadmin_setup', name=view.name)
    return redirect('wagtailadmin_dashboard')

Getting all results from the database should not be an issue, as there will only be a small, finite number of setup steps.

Marking a step as completed is done via the complete_step function:

# wagtail.wagtailadmin.setup

def complete_step(name):
    CompletedStep.objects.create(name=name)

The actual setup view would be somthing along the lines of:

def setup(request, name):
    # Dont show completed steps twice
    if CompletedStep.objects.filter(name=name).exists():
        messages.warning(request, _("That step has already been completed"))
        return next_step_redirect()

    try:
        step = step_dict[name]
    except KeyError:
        return HttpResponse404()

    return step.view(request)

Potential issues

Normal editors logging in should not be able to run the setup process, only superusers. Setup views are assumed to be a one off thing that may expose internal settings. Normal editors should be blocked from continuing until a superuser finishes the process. As the person installing and setting up the site is assumed to be a superuser (they have command line access to the code, so they can be if they want to be!), it can be assumed they will run this before a normal editor can log in to the site.

Multiple superusers completing the steps at the same time could lead to unexpected results, as steps are assumed to only run once. Again, as the installer is likely to run this as part of the installation process, this should not be a huge issue and may not be worth dealing with.

mx-moth/notes.rst