search

ahwayakchih / openshift-nodebb

**CLOSED** HOWTO install NodeBB in the OpenShift cloud.
17 stars 9 forks source link

readme

NodeBB in the OpenShift v2 cloud

NOT MAINTAINED: [2018-03-15] this guide was created when OpenShift v2 was available, which is not longer true. New version of OpenShift changed a lot of things, and information found in this guide will not work with it.

This document will guide you through the process of installing NodeBB (http://www.nodebb.org) in the OpenShift cloud (https://www.openshift.com/). It will also let you know how to keep NodeBB updated afterwards.

Before continuing, you should know how to open and use command line on your system. This guide does not describe how to do that.

Prerequisites

First of all, you will need an OpenShift account. If you do not have one yet, now is the time to register at https://www.openshift.com/app/account/new.

Next, install rhc application, as described at https://developers.openshift.com/en/managing-client-tools.html. Make sure to follow the steps described in the "Setting up Your Machine" section relevant for your operating system.

After that, you should have working rhc and git available on your system. If you had to install git, or never used it before, make sure that you configured your identity, as described at: https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup#Your-Identity.

Installation

To install NodeBB, follow these steps (they were tested using bash shell), without omitting any of them (unless stated otherwise), on your local system (NOT on the OpenShift side, through SSH).

1. Creating a new application

Make sure that there is no local "nodebb" directory already there. If there is, either move it somewhere else or change its name. You can also use different name than "nodebb" for your application. In such case, be sure to replace the word "nodebb" (but only if it is all in small caps, and not part of another word) in every command mentioned in this guide.

This will create the application in the OpenShift cloud.

rhc app create --no-scaling nodebb https://raw.githubusercontent.com/icflorescu/openshift-cartridge-nodejs/master/metadata/manifest.yml NODE_VERSION_URL=https://semver.io/node/resolve/0.10

It should create your local copy of your OpenShift repository in a directory called "nodebb". If it does not, check if there were some errors in the output and maybe try again before continuing. Without that directory, rest of the steps will not work as they should.

2. Adding database cartridge

NodeBB supports both Redis and MongoDB databases. It's up to you to decide which one to use. If you to not know anything about that, just select first one.

To use MongoDB local to OpenShift server, run:

rhc cartridge add https://raw.githubusercontent.com/icflorescu/openshift-cartridge-mongodb/master/metadata/manifest.yml -a nodebb

To use Redis local to OpenShift server, run:

rhc cartridge add http://cartreflect-claytondev.rhcloud.com/github/transformatordesign/openshift-redis-cart -a nodebb

To use third party MongoDB Database-as-a-Service from MongoLab, go to https://marketplace.openshift.com/login, add MongoLab subscription and connect it to the nodebb application (read more about that at https://developers.openshift.com/en/marketplace-mongolab.html).

Only one of them is needed, there is no point in adding more than one database.

3. Add NodeBB repository

This will change current working directory to the one used for NodeBB.

cd nodebb

This will attach remote NodeBB repository to your local repository.

git remote add upstream -m master https://github.com/NodeBB/NodeBB.git

4. Import NodeBB code to application

This will clean up directory from example stuff that node js cartridge created.

rm -rf `ls` .eslintrc && git commit -a -m 'Cleaned up for NodeBB'

This will import source code of NodeBB v0.9.x. To import different version instead, go to https://github.com/NodeBB/NodeBB, see what version branches are available and replace "v0.9.x" with selected version number.

git pull --no-edit -s recursive -X theirs upstream v0.9.x

This guide was tested with v0.6.x, v0.7.x, v0.8.x, and v0.9.x branches.

5. Add OpenShift-NodeBB repository

This will allow to import patches and action_hooks needed to use NodeBB without worrying too much about dynamic IP and/or port number changes or files uploaded by users disappearing.

git remote add openshift -m master https://github.com/ahwayakchih/openshift-nodebb.git

6. Import OpenShift-NodeBB

This will import scripts and patches mentioned in previous step.

git pull --no-edit -s recursive -X theirs openshift master

7. Configure administrator e-mail

This will set NodeBB administrator e-mail address to youremail@example.com. Please change it to the one you want to be used by your NodeBB installation.

rhc env set NODEBB_ADMIN_EMAIL=youremail@example.com -a nodebb

8. Push everything to application repository

This will push everything to OpenShift servers, deploy and start NodeBB.

git push origin master

9. That's it!

After a while, you should be able to see something like this near the end of a long text output from previous command:

    .-============================================-.
    .  Setup Finished.
    .
    .  New administrator user has been created:
    .
    .    email   : youremail@example.com
    .    login   : nodebb
    .    password: 9D7u-KAtN-76Kz-TCyX
    .
    .  Please wait for NodeBB to start.
    .
    .  WARNING: Be sure to change admin password
    .           after first log in!
    ^-============================================-^

And then:

    .-============================================-.
    .  NodeBB is ready.
    .
    .  You can visit it at:
    .  https://nodebb-youropenshiftusername.rhcloud.com/
    .
    .  You can log in to it at:
    .  https://nodebb-youropenshiftusername.rhcloud.com/login
    ^-============================================-^

Use that new admin login and password to log in to your new NodeBB installation, and change them to something suitable for you.

Updates

From now on, every time you want to update NodeBB, you can simply follow three steps. Follow them on your local system (NOT on the OpenShift side, through SSH).

1. Pull changes

This will change current working directory to the one used for NodeBB. 

cd nodebb

Update NodeBB source code:

git pull --no-edit -s recursive -X theirs upstream v0.9.x

You can jump to a new version by replacing "v0.9.x" with another branch name. Before you do that, run full update of your currently installed version, and only after that, repeat update process with new version.

Keep in mind, however, that switching to a new version will work only for an uprade, e.g., from v0.8.x to v0.9.x.

Update OpenShift-NodeBB patches:

git pull --no-edit -s recursive -X theirs openshift master

2. Push changes

git push origin master

3. That's it!

After a while (sometimes quite a long while), you should be able to see something like this near the end of a long text output from previous command:

    .-============================================-.
    .  Setup Finished.
    .
    .  Please wait for NodeBB to start.
    ^-============================================-^

And then:

    .-============================================-.
    .  NodeBB is ready.
    .
    .  You can visit it at:
    .  https://nodebb-youropenshiftusername.rhcloud.com/
    .
    .  You can log in to it at:
    .  https://nodebb-youropenshiftusername.rhcloud.com/login
    ^-============================================-^

Plugins

If you just want to test things and look around, you can simply install/enable plugins through administration pages.

If you want to keep NodeBB running in the OpenShift cloud, you should add plugins through your repository instead. That is because OpenShift may erase all the files on server whenever you push changes to your repository. NodeBB can install plugins, but it will not add them to the "package.json" file, nor it will commit changes to your repository.

To keep plugins installed and working between updates, you can install them using npm. Follow these steps on your local system (NOT on the OpenShift side, through SSH).

1. Install plugin locally

This will change current working directory to the one used for NodeBB. 

cd nodebb

As an example, this will install "Question and Answer" plugin (https://github.com/psychobunny/nodebb-plugin-question-and-answer).

npm install --production --save nodebb-plugin-question-and-answer

Plugin will be installed locally and information about it will be saved to the "package.json" file.

Change the name of the module (nodebb-plugin-question-and-answer in the example above) to install plugin of your choice. Just remember to keep the npm install --production --save part of the command intact.

2. Commit changes

This will commit modifications to your local repository.

git commit -a -m 'Added QA plugin'

Of course, instead of Added QA plugin you can write any other one-liner that explains what was changed.

3. Push changes

git push origin master

Custom domain name

If you want to use your own domain name, instead of subdomain in domain provided by OpenShift, you can add alias to your application. There is only one ceveat: to use HTTPS with your own domain name, you have to upgrade your OpenShift plan. Otherwise there is no way to set up correct SSL certificate and you will keep bumping into problems.

So in short, here is when you can use HTTPS:

You can read more about that at https://developers.openshift.com/en/managing-domains-ssl.html

There's no known way for NodeBB to work 100% correctly with both HTTPS and custom domain name on a free plan. CloudFlare does not seem to provide support for SSL websockets for anything below Enterprise plan.

As usual, follow these steps on your local system (NOT on the OpenShift side, through SSH).

1. Add domain name to application

rhc alias add nodebb example.com

Of course, instead of example.com enter your own domain name.

2. Add domain name to NodeBB

This will make NodeBB installation work correctly with your custom domain name.

rhc env set OPENSHIFT_APP_DNS_ALIAS=example.com -a nodebb

Again, use your own domain name in place of example.com.

3. Optional SSL

If your account is on one of paid "premium" plans, you can add SSL certificate to enable valid usage of HTTPS with your custom domain name. You can get free, widely accepted certificates from https://letsencrypt.org/.

Once you have a key and a certificate, this will add them to application:

rhc alias update-cert nodebb example.com --certificate cert_file --private_key key_file

Use your own domain name in place of example.com, and correct files in place of cert_file and key_file. Read more about setting up SSL at https://developers.openshift.com/en/managing-domains-ssl.html#_command_line_rhc_3

You can add certificates at some point in future. Just remember to restart application after that.

4. Restart NodeBB

This will restart your NodeBB installation, so it can use updated configuration variables.

rhc app restart nodebb

5. Configure DNS

Last thing to do is to configure DNS for your domain name to point to your OpenShift domain name. You can read more about that at https://developers.openshift.com/en/managing-domains-ssl.html#_step_2_configure_your_dns_host_records.

Please note that some DNS changes may take up to 24 hours before propagating, so if your NodeBB site is not accessible through custom domain name, it may just be that you have to wait a bit before it starts working.

If later you decide to change the domain name, simply repeat steps 1 to 5.

Troubleshooting

1. Installation/Update error

When something goes wrong with installation or update, you should see something like this near the end of a long text output:

    .-============================================-.
    .  Setup failed.
    .
    .  There was a problem completing NodeBB setup.
    .
    .  Check logfile for more information:
    .  logs/openshift-nodebb-setup.log
    ^-============================================-^

It may be either "Setup failed" or "NodeBB failed to start".

Path to logfile is local to OpenShift server, so to check that file you can either log in to server through SSH or copy file to your local directory.

This will copy log file from OpenShift server to your local directory.

rhc scp nodebb download ./ app-root/repo/logs/openshift-nodebb-setup.log

Use whatever path was mentioned in error message in place of "logs/logs/openshift-nodebb-setup.log".

Once you have the log file, you can either check it yourself or post an issue at https://github.com/ahwayakchih/openshift-nodebb/issues (describing the steps you made and copying and pasting content of the logfile).

2. Restart application

From time to time something may go wrong while OpenShift tries to restart application, e.g., after its repository is updated. In such case, your NodeBB site may not work as it should. Sometimes that can be fixed with a simple command:

rhc app restart

3. Add missing "origin" remote

It looks like sometimes, for reasons unknown at the moment of writing this text, remote "origin" is missing. In such case you can run:

cd nodebb

and then:

git remote add origin `rhc app show nodebb | grep -oh "ssh://\S\{1,\}\.rhcloud.com/~/git/\S*"`

This should configure remote "origin" in your local git repository to point to your git repository located on the OpenShift servers.

4. Remove custom domain name

If you want to remove custom domain name, this will stop NodeBB from using it:

rhc env unset OPENSHIFT_APP_DNS_ALIAS

If you did add certificate, this will remove it:

rhc alias delete-cert nodebb example.com

Finally, this will stop OpenShift from using your domain name:

rhc alias remove nodebb example.com

Acknowledgments

This guide wouldn't be possible without instructions from https://github.com/NodeBB/nodebb-english/blob/master/installing/cloud/openshift.rst and OpenShift documentation and examples from https://developers.openshift.com/en/managing-action-hooks.html

It also wouldn't be created if not for numerous questions and conversations with Sylwester Cyba from http://nhl.pl/.

Part describing custom domain setup was created thanks to Benderwan (https://github.com/Benderwan) reporting problem and testing solutions (https://github.com/ahwayakchih/openshift-nodebb/issues/7).