Designing the First Time Setup Wizard

Update (Dec 18, 2018): This topic was originally to design the Wizard. If you want to know how to use the Wizard to update your site settings, please visit this topic.

One thing we’ve never been 100% happy with on Discourse is our on-boarding experience for new users.

Right now, when a Discourse forum is installed and an admin signs in, they are expected to read the Admin Quick Start Guide. During this process they end up having to jump to the admin section, fill in site settings, upload logos into a topic, then go back into site settings to point at the newly uploaded assets.

I think a much better solution for getting a Discourse forum set up and running is to use a Wizard to guide the forum’s owner through the setup process. I started working on this last week and it’s coming along nicely so I thought I’d share it with you!

The admin user will see a new interface when configuring their site:

(bear in mind the above is a work in progress – we’re likely going to tweak it a lot before it ships!)

Here’s the steps I’m imagining for the minimum viable product:

Rough Outline

Step 1: Language (locale)
Step 2: Forum name and description
Step 3: Privacy Settings
Step 4: Contact information
Step 5: Color Scheme (might just be dark theme / light theme at first)
Step 6: Upload Logos and Favicon
Step 7: Invite Staff Users

Technical Concerns

  • This is a new, full screen ember application. It’s only downloaded when you visit the wizard.

  • Steps can be created programmatically, so plugins will be able to add them.

  • Staff will be able to re-enter the wizard rather than going through Site Settings.


I created a new component to preview the color scheme when selecting it from a drop down. If you select “Dark” from the color scheme the preview below updates automatically!

(The plan is to also move this component to the admin section too when creating color schemes.)


Make sure TOS and Privacy are set up in there as well, with the right “company name”.

We probably also want a plugin to hook into this even in V1 so we know it works. So maybe one of our bundled plugins should “add a step”? Perhaps Akismet, asking for a key so it can function? Or something similar to that.


Not sure how hard it is, but I think being able to select the locale in the wizard is as important as selecting the color scheme.


It also very common for people to put the site in login-required and invite-only mode until they’re ready to launch the site.


Can you elaborate here what you mean by set up? I’m assuming just capturing the company name fields from the TOS and automatically updating the topic should be enough?

1 Like

I’ve made some more progress on this. The first step a user receives is now to select their language (thanks @zogstrip) . If it’s different than the current one, it will refresh the page and the wizard will continue in that language.

Following @neil’s suggestion, there’s now a step to choose the privacy of your new forum:

One of the more challenging parts to implement was the logo uploading, but that’s in place and working now too:

Still to come:

  • Inviting Staff Users
  • Choosing your Company name for the TOS + Privacy

Does the first step (language selection) affect the locale used for importing the database fixtures or do we still need to configure DISCOURSE_DEFAULT_LOCALE in app.yml?

1 Like

Along the same lines as @gerhard’s question, does it affect the setting of allow upper case posts? Because it should.

Should be fine for now. Technically we want to offer site owners choices of default user contributed post licensing, but I’d prefer we “accidentally” defaulted to Creative Commons myself :wink: as we already do anyways…


Unfortunately not. The wizard runs once Discourse has already started up, so the choices you make in it are equivalent to configuring the site settings yourself. You will still need that setting for now.

Having said that, I do think it would be possible to regenerate those fixtures via the wizard. We should revisit at a later date.

Can you elaborate? Is the idea that in some languages upper case is more common, and the setting should change it depending on locale?


Yes, exactly. To quote from the topic I linked to:

1 Like

Right, but what’s not clear to me is how to act on it – which languages require which settings?

I guess @elijah is thinking about locale dependent default settings. Not sure what’s the best way to solve this and it’s probably out of scope for the wizard’s first version.


I’ve confirmed that the API works well from a plugin. Here’s an example from the Akismet plugin:

Basically to add a step from the plugin you do this:


on(:wizard_build) do |wizard|
  wizard.append_step('akismet') do |step|
    step.add_field(id: 'akismet_api_key', type: 'text', value: SiteSetting.akismet_api_key)

    step.on_update do |updater|

You also then have to fill in the translation keys for the step and the labels. This is pretty straightforward but if you want to see an example view the akismet commit.

Notice that this API doesn’t use any Javascript! If you’re just using basic form elements like text fields, drop downs and radio buttons you can just assemble the step using the ruby DSL. If you want to do something more advanced such as the color scheme preview in the screenshots earlier in this topic, you’ll have to write your own Ember component.

If you’re curious how this works: the API creates a bunch of objects that are serialized the JSON. The accompanying Ember app is smart enough to read that JSON and render a multi step wizard, submitting each step to the server as it goes along.


This is a pretty nice API, well done.

So I can add multple steps, handle configuration, etc.

Can I do something (like start a background job) on the on_update callback? (after the apply_settings obviously)


Yup, any valid Ruby code will work in there.


OK! This will be ready for wider testing first thing tomorrow.


And it’s merged! Our initial plan of having 5 steps ballooned up to 13!

I’m quite proud of it already, so I’m excited to hear feedback from the world at large and continue to tweak it even further.

If you’re interested in helping us test the feature, if you are an admin you can access the wizard at the /wizard path even if your forum is already configured – otherwise the first admin who logs in is invited to complete it via a notice.


I’ve fixed a couple of issues:

  • Wizard is restricted to admin now, not staff
  • Color scheme name was showing up as translation missing in admin
  • Tab order was going to “back” before “next”, missing outlines
  • Was broken in subfolder mode