Organiziaton of documentation for installs - docker vs. non-docker / official vs. unofficial


(Dave McClure) #1

A few posts recently have made me wonder whether there are ways that we can better clarify what is supported and not for people who want to install and maintain discourse on their own.

  1. I didn’t see any mention of the DIY install on The closest thing is the $99 install. Is this intentional or an oversight?

  2. There are two copies of the official ‘basic’ install guide. One in github, and one here on meta. They do seem like they are kept well in sync, but should one just be maintained as the ‘official’ guide and the other reference it by URL?

  3. The install guide here on meta doesn’t come up in the top results when you type ‘install’ because ‘deploy’ is used in the title instead.

  4. How should ‘unsupported’ installs be discussed here on meta?

  5. Docker is the only supported install, but there are some places where non-docker install instructions are referenced.

  6. The official guide uses Digital Ocean but more folks seem to be exploring other hosting providers now. Its not perfectly clear what docs they should use.

Here’s a How To from a team member discussing a non-docker install with no strong disclaimer about it being not supported (just hints that the alternative is recommended).

And in the github docs, there is this paragraph, which I find a little confusing:

The only officially supported installs of Discourse are the Docker based beginner and advanced installs. We regret that we cannot support any other methods of installation. (Alternately, you can try the unofficial Heroku install guide, the unofficial Ubuntu install guide, the BitNami Discourse Virtual Machine package or Cloud66.)

Why link to those alternatives at all if they are unsupported? I think it may be better to remove them.

If there is a desire to keep them for the sake of transparency and to help tinkerers then put the links to all of them all in one separate doc specifically stating that reasoning and that everything there is unsupported.

Here’s what I propose:

  1. Put official install docs in Github
  2. Link to them from meta.
    If its worth copying them completely into How To on meta, put the link to the github version at the top and make that official
  3. Make the official ‘basic’ guide agnostic with regards to hosting providers. Link to separate docs for each supported hosting provider to get that initial setup done (even if its just Digital Ocean for now).
  4. On, link to the official install guide where it makes sense.
  5. Move topics out of How To that discuss unsupported installs or put a big disclaimer at the top of them.
  6. For Support topics that discuss non-supported installs the current practice seems fine - just continue the current practice of reminding people who ask those questions that they are not supported and won’t get attention from the team.

(Jeff Atwood) #2

As for the proposals:

  1. Done!

  2. I just deleted that old meta howto topic as it was out of date anyway. So all install docs are on GitHub now.

  3. I think we should alias as to generalize it but I am unsure how to do that.

  4. We already do, I believe. (see image below)

  5. Can you point to howto topics that you think should be moved?

A community effort to improve Discourse's documentation
(Dave McClure) #3

Will do if I see any others… That one you deleted already was the one I noticed that triggered this topic.

Here are two others that look like they could use moving or something:

I will take a closer look at the other changes you mentioned over the weekend and let you know if I have any more specific ideas regarding ‘refactoring’ the cloud / digital ocean install docs or create a PR.

(Kevin P. Fleming) #4

You can ‘alias’ by creating a symlink; Git supports symbolic links. It will make the repo contents unfriendly to Windows users, but since this repo’s contents are already pretty unfriendly to Windows users, that won’t really matter :smile: