Real need for better docs for noobs


  • @julian said:

    @LeeM My apologies for the lack of a response (though of course, it was the weekend for 2/3rds of those days 😉 )

    We do get excited when new people want to try NodeBB, but as others have kindly pointed out, it would be a full-time job if I were to devote my full attention to helping somebody install NodeBB. This is not to say that I actively don't help others, it's just that concessions have to be made if we want to keep developing NodeBB 😄

    This is why I'm especially grateful to the users who spend their time here, donating their time to helping others get up and running. They don't get compensated for their time, so it is very meaningful.


    Now, onto the matter of getting you up and running. I will fully admit that there exists a moderate learning curve, especially if:

    1. You come from a LAMP-stack background, or
    2. You are not technologically inclined (e.g. a computer user, not a developer)

    For those that fall into the second grouping, getting set up is an almost insurmountable task, and I mention this whenever I can:

    WordPress installations weren't always simple one-click affairs. When I first discovered WordPress, or phpBB, or similar softwares, I had to sign up for a host, log in via ssh (what's PuTTY?), install mysql (what's mysql? what's phpmyadmin? what is apt-get?... and apt is the simpler way of installing things...), create a database (how do I do that?), set up apache (what's apache?), finangle the configs until it could serve the right folder, debug for hours as to why it's just showing "It works!", run the install script, and then and only then, start tweaking my install.

    But nowadays, cloud hosting providers have distilled all of this into a single step. We've done the same with NodeBB on our hosting platform, and this is why we recommend going with our hosting if you don't want to deal with the headache of setting NodeBB up.

    As a point of reference, back in those days, it took me hours (spread over days) to get everything set up properly. I was learning then, as you are learning now. Knowledge doesn't come quick, or free!

    Personally, I wish installing NodeBB were easier. However, there are still many prerequisites that we simply cannot get rid of. Knowing what ssh is, and how to use it, is one. Over time these problems will be nullified (much like how Wordpress is a simple one-click install), but until then, you will have to bear with us 🙂

    Many of the installation guides are community-driven. That is, they depend on the hard work of interested parties to ensure that the guide is up to date, and... you know, works. I install NodeBB on DigitalOcean boxes, and (very) occasionally, on Heroku, so those are the two I support.

    Everything else is just a bonus 😄

    Hi Julian, many thanks for taking the time to write such a thoughtful response, of course I appreciate you can't dedicate your time to a single user, but in my defense I wasn't asking for help (though it will be very gratefully received), my intent was to point out the docs deficiencies and so help the project grow by opening it up to a larger audience.

    Other than that thanks for the useful tips, still not entirely sure what a lot of it means but I guess I have to start somewhere, but one thing I'll promise you, if I do manage to work out how it all works I'll create an install guide for apache people.

    best, Lee


  • Some of the responses here sound a little defensive, as if admitting that NodeBB's documentation is in an immature state would be impugning the dignity of the NodeBB team. The first part is true and the second simply doesn't follow.

    @LeeM There's a ton of support available right here. Yes, the documentation could use some "dumbing down" for users at your proficiency level, but the development of NodeBB and the technologies it's built on are all happening very fast right now, and trying to make a comprehensive guide for every possible circumstance would not be very efficient use of time. Instead, if you have problems and can't figure them out from Google, this forum exists to ask for help.

    If you'd like to test the system out locally, I highly recommend doing it on Ubuntu. Redis, node and their various dependencies are just easier to set up there, because it's their native environment. If you're using a Windows desktop, there are free virtualization products you can use to set up a virtual server.

    Windows 7: Download and install Windows Virtual PC from http://www.microsoft.com/en-us/download/details.aspx?id=3702
    Windows 8.1: Install the Hyper-V feature, instructions here: http://windows.microsoft.com/en-us/windows-8/hyper-v-run-virtual-machines
    Or Oracle VirtualBox, found here: https://www.virtualbox.org/wiki/Downloads (you would want the version for Windows hosts)

    When you build a virtual computer with any of the above options, it will ask you to supply installation media for the new VM's operating system. This should be an ISO file for either Ubuntu Desktop (a little easier to use because it includes a GUI) or Ubuntu Server (more suitable for a production server, but not required for testing things out) which you can download here: http://www.ubuntu.com/download

    The installation process for Ubuntu is very straight forward. It will ask you some simple questions and then configure itself appropriately. You can find step-by-step guides to assist you with that on the Internet if you're interested. This whole process might take you two hours (from installing the hypervisor to finishing the installation of your Ubuntu OS), and it doesn't require changing much on your real computer (the hypevisor software has to be installed, but after that all of the changes you make are inside a virtual sandbox and you can destroy it and recreate it any time you want).

    You will need to learn to use the Ubuntu Linux command-line for this, but I promise it's not as daunting as it probably seems. From this point, you just follow the step-by-step guide supplied in the NodeBB docs to get an installation up and running. Again, there will be more questions and responses, but the documentation does tell you what to do and if you get stuck, you can always come back here and ask for help.


  • Also ... Node doesn't need Apache the way PHP does. You can make it run through Apache, by configuring Apache as a reverse proxy (documentation here: https://docs.nodebb.org/en/latest/configuring/proxies/apache.html) but that's just extra work (and another component to break) if you're setting up a test system to play with (and for production, I'd strongly recommend Nginx over Apache).


  • Hey,😄

    oh gosh no .... by no means did I mean any offense to the developers or the software, I think they're both equally amazing, and apologies if that was the impression I gave, my intent is only ever to help improve open source projects.

    Just to reiterate, the documentation is no doubt really good, it just wasn't good for me.

    I was however very fortunate to have received some absolutely amazing support from @a_5mith (who is a complete superstar)and I now have NodeBB setup on DO.

    Thank you for our useful tips 😄


  • @julian said:

    sudo apt-get install git nodejs nodejs-legacy npm redis-server imagemagick build-essential

    Can I ask why nodejs-legacy is included there? My understanding is that it's just a symbolic link to make typeing "node" work on Ubuntu instead of typing "nodejs" and NodeBB doesn't seem to require it. I just set up a new virtual server this weekend and didn't install it and it's working fine for me.

    Also, it might make sense to break that line down into separate commands for the less Linux proficient. I know I really had no clue what I was doing the first time I installed multiple packages this way and the barrage of output you get is pretty overwhelming.

    @LeeM I didn't mean you, but I'm glad to hear @a_5mith helped you out. He's answered many questions for me, too. NodeBB's documentation is sufficient for people who are proficient with the technologies it uses and there's definitely a gap that can be filled in there, either by having better deployment tools (which sounds pretty good, @pitaj) or by more "tutorial" like guides. But it's brand-spankin'-new and it will take some time to get to the level you're familiar with from phpBB (which is now nearly 15-years old and has barely been modified in the last 8 or so).

    I started with NodeBB 0.4.something, I think, less than a year ago and we're already looking at 0.7.0 with tons of changes happening nearly daily. There's a level of proficiency that is required to be able to manage software that moves that quickly. I'd still recommend you try your hand at setting up a quick Linux system - it's valuable knowledge for a lot of things.

  • Admin

    Time for me to finally pitch in (sorry been busy trying to push out the new theme this weekend)

    My dummies guide is really out of date, although @Ted has been working on a new one that hopefully is more user friendly.

    Most of the above statements are very true, we are moving as fast as possible to get NodeBB to 1.0 which means installation instructions break occasionally and our time is imbalanced spending more time on dev, theming, and the paying customers that help us pay the bills.

    To echo @julian's sentiment, I'm really grateful to our community members that do take the time to help other new users 🙂


  • You might try checking out my guide here.

    It was written to be more friendly to beginners. It should get you running on v0.6x which is the latest stable release. This forum is presently operating out of the master repo, which has experimental and bleeding edge features. My time to dedicate to NodeBB has been lacking of late, but I'll be keeping that guide updated.


  • What can I say other than WOW, five days of excruciating agony getting the software to work was absolutely worth it, NodeBB is amazing in every respect, loving the ACP functionality, is very easy to use and customize, and if you're a noob here looking to see if it's worth the effort, I'd say go for it, you will not be disappointed!

    Aside from the installation (which I still never managed myself) NodeBB is in a class of its own, it looks fantastic, and I have no doubt it will become the forum of choice for all modern communities.

    A huge thank you to @julian , @psychobunny for creating a complete masterpiece and big thanks to @a_5mith for installing NodeBB for me.

  • Admin

    Haha don't forget @baris NodeBB's server side maestro


  • @psychobunny is a real superstar, but the community as a whole (users/developers) is real good one. Which is why I personally would stay with NodeBB over say Discourse, which I would say would be NodeBB's only real competitor.

Suggested Topics

| |