-
Notifications
You must be signed in to change notification settings - Fork 81
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #113 from dwatley/ubuntu-guide
Revised Ubuntu guide with more context.
- Loading branch information
Showing
1 changed file
with
163 additions
and
32 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,78 +1,209 @@ | ||
|
|
||
| Ubuntu | ||
| -------------------- | ||
| ====== | ||
|
|
||
| The following installation guide is optimised for Ubuntu LTS versions, and will install NodeBB | ||
| with MongoDB as the data store. Currently at the time of writing, the latest available Ubuntu | ||
| LTS version is **14.04**. | ||
| This installation guide is optimized for **Ubuntu 16.04 LTS** and will install NodeBB with MongoDB as the database. | ||
| Fully patched LTS and equivalent **production** versions of software are assumed and used throughout. | ||
|
|
||
| ---- | ||
| --------------------- | ||
|
|
||
| First, install the LTS version of Node.js (**v4.2 Argon**): | ||
| Install Node.js | ||
| --------------------- | ||
|
|
||
| Naturally, NodeBB is driven by Node.js, and so it needs to be installed. Node.js is a rapidly evolving platform and so | ||
| installation of an LTS version of Node.js is recommended to avoid unexpected breaking changes in the future as part of | ||
| system updates. The `Node.js LTS Plan <https://github.com/nodejs/LTS>`_ details the LTS release schedule including | ||
| projected end-of-life. | ||
|
|
||
| To start, add the nodesource repository per the `Node.js Ubuntu instructions <https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions>`_ | ||
| and install Node.js: | ||
|
|
||
| .. code:: bash | ||
| $ curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash - | ||
| $ curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash - | ||
| $ sudo apt install -y nodejs | ||
| Next, we'll install the dependencies required by NodeBB | ||
| Verify installation of Node.js and npm: | ||
|
|
||
| .. code:: bash | ||
| $ sudo apt-get install -y git nodejs mongodb build-essential | ||
| $ node -v | ||
| $ npm -v | ||
| Install MongoDB | ||
| --------------------- | ||
|
|
||
| MongoDB is the default database for NodeBB. As noted in the `MongoDB Support Policy <https://www.mongodb.com/support-policy>`_ | ||
| versions older than **3.x** are officially **End of Life** as of October 2016. This guide assumes installation of | ||
| **3.2.x**. If `Redis <https://redis.io>`_ or another database instead of MongoDB the | ||
| :doc:`Configuring Databases <../../configuring/databases>` section has more information. | ||
|
|
||
| If you want to use Redis or another database instead of MongoDB please look at the :doc:`Configuring Databases <../../configuring/databases>` section. | ||
| Up to date detailed installation instructions can be found in the `MongoDB manual <https://docs.mongodb.com/v3.2/tutorial/install-mongodb-on-ubuntu/>`_. | ||
| Although out of scope for this guide, some MongoDB production deployments leverage clustering, sharding and replication | ||
| for high availibility and performance reasons. Please refer to the MongoDB `Replication <https://docs.mongodb.com/v3.2/replication/>`_ | ||
| and `Sharding <https://docs.mongodb.com/v3.2/sharding/>`_ topics for further reading. | ||
|
|
||
| Abbreviated instructions below: | ||
|
|
||
| .. code:: bash | ||
| Next, clone NodeBB into your desired location. If you don't know where, your home directory is acceptable: | ||
| $ sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv EA312927 | ||
| $ echo "deb http://repo.mongodb.org/apt/ubuntu xenial/mongodb-org/3.2 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.2.list | ||
| $ sudo apt update && sudo apt install -y mongodb-org | ||
| Start the service and verify service status: | ||
|
|
||
| .. code:: bash | ||
| $ cd ~ # Optional | ||
| $ git clone -b v1.x.x https://github.com/NodeBB/NodeBB.git nodebb | ||
| $ sudo service mongod start | ||
| $ sudo service mongod status | ||
| To track the latest weekly build of NodeBB, substitute `weekly` in place of `v1.x.x` | ||
| If everything has been installed correctly the service status should show as ``active (running)``. | ||
|
|
||
| Configure MongoDB | ||
| --------------------- | ||
|
|
||
| Obtain all of the dependencies required by NodeBB: | ||
| General MongoDB administration is done through the MongoDB Shell ``mongo``. A default installation of MongoDB listens | ||
| on port ``27017`` and is accessible locally. Access the shell: | ||
|
|
||
| .. code:: bash | ||
| $ cd nodebb | ||
| $ npm install --production | ||
| Now, you need to configure your MongoDB database. To do this, refer to :doc:`MongoDB <../../configuring/databases/mongo>`: | ||
| $ mongo | ||
| Switch to the built-in ``admin`` database: | ||
|
|
||
| .. code:: | ||
| > use admin | ||
| Create an administrative user (**not** the ``nodebb`` user) scoped to the ``admin`` database to manage MongoDB once | ||
| authorization has been enabled: | ||
|
|
||
| .. code:: | ||
| > db.createUser( { user: "<Enter a username>", pwd: "<Enter a secure password>", roles: [ { role: "readWriteAnyDatabase", db: "admin" }, { role: "userAdminAnyDatabase", db: "admin" } ] } ) | ||
| To initially create a database that doesn't exist simply ``use`` it. Add a new database called ``nodebb``: | ||
|
|
||
| .. code:: | ||
| > use nodebb | ||
| The database will be created and context switched to ``nodebb``. Next create the `nodebb` user and add the appropriate | ||
| privileges: | ||
|
|
||
| .. code:: | ||
| > db.createUser( { user: "nodebb", pwd: "<Enter a secure password", roles: [ { role: "readWrite", db: "nodebb" }, { role: "clusterMonitor", db: "admin" } ] } ) | ||
| The ``readWrite`` permission allows NodeBB to store and retrieve data from the ``nodebb`` database. The | ||
| ``clusterMonitor`` permission provides NodeBB read-only access to query database server statistics which are then | ||
| exposed in the NodeBB Administrative Control Panel (ACP). | ||
|
|
||
| Exit the Mongo Shell: | ||
|
|
||
| .. code:: | ||
| Start the NodeBB Web Installer, and continue setup at http://127.0.0.1:4567, and select "MongoDB" | ||
| as your database type. | ||
| > quit() | ||
| Enable database authorization in the MongoDB configuration file ``/etc/mongod.conf`` by uncommenting the line | ||
| ``security`` and enabling authorization: | ||
|
|
||
| .. code:: yaml | ||
| security: | ||
| authorization: enabled | ||
| Restart MongoDB and verify the administrative user created earlier can connect: | ||
|
|
||
| .. code:: bash | ||
| $ npm start | ||
| $ sudo service mongod restart | ||
| $ mongo -u your_username -p your_password --authenticationDatabase=admin | ||
| If everything is configured correctly the Mongo Shell will connect. Exit the shell. | ||
|
|
||
| ---- | ||
| Install NodeBB | ||
| --------------------- | ||
|
|
||
| **Alternatively**: Initiate the setup script by running the app with the ``setup`` flag: | ||
| First, the remaining dependencies should be installed if not already present: | ||
|
|
||
| .. code:: bash | ||
| $ sudo apt-get install -y git build-essential | ||
| Next, clone NodeBB into an appropriate location. Here the ``opt`` directory is used: | ||
|
|
||
| .. code:: bash | ||
| $ ./nodebb setup | ||
| $ cd /opt | ||
| $ sudo git clone -b v1.x.x https://github.com/NodeBB/NodeBB.git nodebb | ||
| This clones the NodeBB repository from the ``v1.x.x`` branch to ``/opt/nodebb``. A list of alternative branches are | ||
| available in the `NodeBB Branches <https://github.com/NodeBB/NodeBB/branches>`_ GitHub page. | ||
|
|
||
| Obtain all of the dependencies required by NodeBB and initiate the setup script: | ||
|
|
||
| .. code:: bash | ||
| $ cd nodebb | ||
| $ sudo npm install --production | ||
| $ sudo ./nodebb setup | ||
| The default settings are for a local server running on the default port, with a redis store on the same machine/port. | ||
| A series of questions will be prompt with defaults in parenthesis. The default settings are for a local server listening | ||
| on the default port ``4567`` with a MongoDB instance listening on port ``27017``. When prompted be sure to configure the | ||
| MongoDB username and password that was configured earlier for NodeBB. Once connectivity to the database is confirmed the | ||
| setup will prompt that initial user setup is running. Since this is a fresh NodeBB install a forum administrator must be | ||
| configured. Enter the desired administrator information. This will culminate in a ``NodeBB Setup Completed.`` message. | ||
|
|
||
| Lastly, we run the forum. | ||
| A configuration file :doc:`config.json <../../configuring/config>` will be created in the root of the nodebb directory, | ||
| in this case ``/opt/nodebb/config.json``. This file can be modified should you need to make changes such as changing the | ||
| database location or credentials used to access the database. | ||
|
|
||
| Next create a ``nodebb`` system user and give the account permissions over the ``/opt/nodebb`` folder and all | ||
| subdirectories. This will ensure that NodeBB can configure plugins and update. | ||
|
|
||
| .. code:: bash | ||
| $ ./nodebb start | ||
| $ sudo adduser --system --group nodebb | ||
| $ sudo chown -R nodebb:nodebb /opt/nodebb | ||
| The last setup item is to configure NodeBB to start automatically. Modern linux systems have adopted | ||
| `systemd <https://en.wikipedia.org/wiki/Systemd>`_ as the default init system. Configure nodebb to start via a systemd | ||
| unit file at the location ``/lib/systemd/system/nodebb.service``: | ||
|
|
||
| .. code:: | ||
| [Unit] | ||
| Description=NodeBB forum for Node.js. | ||
| Documentation=http://nodebb.readthedocs.io/en/latest/ | ||
| After=system.slice multi-user.target | ||
| [Service] | ||
| Type=simple | ||
| User=nodebb | ||
| NodeBB can also be started with helper programs, such as ``forever``. :doc:`Take a look at the options here <../../running/index>`. | ||
| StandardOutput=syslog | ||
| StandardError=syslog | ||
| SyslogIdentifier=nodebb | ||
| Environment=NODE_ENV=production | ||
| WorkingDirectory=/opt/nodebb | ||
| ExecStart=/usr/bin/node loader.js --no-daemon --no-silent | ||
| Restart=always | ||
| [Install] | ||
| WantedBy=multi-user.target | ||
| Finally, enable and start NodeBB: | ||
|
|
||
| .. code:: bash | ||
| ---- | ||
| $ sudo systemctl enable nodebb | ||
| $ sudo service nodebb start | ||
| $ sudo service nodebb status | ||
| If you receive an error stating ``Error: Cannot find module '../build/Release/magic'``, run ``npm i mmmagic`` | ||
| and continue as before. | ||
| If everything has been installed and configured correctly the service status should show as ``active``. Assuming this | ||
| install was done on a Ubuntu Server edition without a desktop, launch a web browser from another host and navigate to | ||
| the address that was configured during the NodeBB setup via IP address or domain name. The default forum should load and | ||
| be ready for general usage and customization. |