├── src ├── templates │ └── installing │ │ ├── os │ │ ├── debian │ │ │ ├── version.txt │ │ │ ├── name.txt │ │ │ ├── mongo │ │ │ │ ├── config.txt │ │ │ │ ├── service │ │ │ │ │ ├── start.txt │ │ │ │ │ ├── status.txt │ │ │ │ │ └── restart.txt │ │ │ │ └── install.md │ │ │ ├── nodebb │ │ │ │ ├── setup.txt │ │ │ │ └── start.txt │ │ │ ├── nginx │ │ │ │ ├── service │ │ │ │ │ ├── reload.txt │ │ │ │ │ ├── start.txt │ │ │ │ │ └── status.txt │ │ │ │ ├── install.md │ │ │ │ └── configs.md │ │ │ ├── git │ │ │ │ └── install.md │ │ │ └── node │ │ │ │ └── install.md │ │ ├── ubuntu │ │ │ ├── name.txt │ │ │ ├── version.txt │ │ │ ├── mongo │ │ │ │ ├── config.txt │ │ │ │ ├── service │ │ │ │ │ ├── start.txt │ │ │ │ │ ├── status.txt │ │ │ │ │ └── restart.txt │ │ │ │ └── install.md │ │ │ ├── nodebb │ │ │ │ ├── setup.txt │ │ │ │ └── start.txt │ │ │ ├── nginx │ │ │ │ ├── service │ │ │ │ │ ├── reload.txt │ │ │ │ │ ├── start.txt │ │ │ │ │ └── status.txt │ │ │ │ ├── install.md │ │ │ │ └── configs.md │ │ │ ├── git │ │ │ │ └── install.md │ │ │ └── node │ │ │ │ └── install.md │ │ └── windows │ │ │ ├── name.txt │ │ │ ├── version.txt │ │ │ ├── nodebb │ │ │ ├── setup.txt │ │ │ └── start.txt │ │ │ ├── mongo │ │ │ ├── config.txt │ │ │ ├── service │ │ │ │ ├── start.txt │ │ │ │ ├── status.txt │ │ │ │ └── restart.txt │ │ │ └── install.md │ │ │ ├── nginx │ │ │ ├── service │ │ │ │ ├── start.txt │ │ │ │ ├── status.txt │ │ │ │ └── reload.txt │ │ │ ├── configs.md │ │ │ └── install.md │ │ │ ├── node │ │ │ └── install.md │ │ │ └── git │ │ │ └── install.md │ │ └── index.js ├── docs │ ├── installing │ │ ├── os │ │ │ ├── .gitignore │ │ │ ├── index.md │ │ │ ├── arch.md │ │ │ ├── freebsd.md │ │ │ ├── centos.md │ │ │ ├── fedora.md │ │ │ ├── smartos.md │ │ │ └── macOS.md │ │ └── cloud │ │ │ ├── cloudron.md │ │ │ ├── index.md │ │ │ ├── nitrous.md │ │ │ ├── elestio.md │ │ │ ├── docker.md │ │ │ ├── heroku.md │ │ │ ├── cloud9.md │ │ │ └── openshift.md │ ├── stylesheets │ │ └── overrides.css │ ├── configuring │ │ ├── proxies │ │ │ ├── index.md │ │ │ ├── apache2.2.md │ │ │ ├── varnish.md │ │ │ ├── caddy.md │ │ │ ├── node.md │ │ │ └── apache.md │ │ ├── databases │ │ │ ├── index.md │ │ │ ├── redis.md │ │ │ └── mongo.md │ │ ├── proxies.rst │ │ ├── plugins │ │ │ ├── search.md │ │ │ ├── emailers.md │ │ │ └── index.md │ │ ├── databases.rst │ │ ├── upgrade.md │ │ ├── running.md │ │ ├── config.md │ │ └── scaling.md │ ├── admin │ │ ├── index.md │ │ ├── uploads.md │ │ └── dashboard.md │ ├── activitypub │ │ ├── fep │ │ │ ├── c0e0.md │ │ │ ├── 7458.md │ │ │ ├── index.md │ │ │ ├── 7888.md │ │ │ └── 1b12.md │ │ ├── prerelease.md │ │ ├── world.md │ │ ├── privileges.md │ │ ├── settings.md │ │ ├── context.md │ │ ├── discovery.md │ │ ├── visibility.md │ │ └── index.md │ ├── development │ │ ├── style-guide.md │ │ ├── plugins │ │ │ ├── libraries.md │ │ │ ├── uncategorized.md │ │ │ ├── parsing.md │ │ │ ├── statics.md │ │ │ ├── plugin.json.md │ │ │ ├── hooks.md │ │ │ └── index.md │ │ ├── index.md │ │ ├── quickstart.md │ │ ├── widgets.md │ │ ├── themes │ │ │ ├── index.md │ │ │ └── templates.md │ │ └── i18n.md │ ├── index.md │ ├── images │ │ ├── nodebb-light.svg │ │ └── nodebb.svg │ └── faq.md └── compile.js ├── .gitignore ├── package.json ├── LICENSE ├── daemon ├── README.md └── mkdocs.yml /src/templates/installing/os/debian/version.txt: -------------------------------------------------------------------------------- 1 | 10 -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/name.txt: -------------------------------------------------------------------------------- 1 | Ubuntu -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/version.txt: -------------------------------------------------------------------------------- 1 | 24.04 -------------------------------------------------------------------------------- /src/templates/installing/os/windows/name.txt: -------------------------------------------------------------------------------- 1 | Windows -------------------------------------------------------------------------------- /src/templates/installing/os/windows/version.txt: -------------------------------------------------------------------------------- 1 | 10 -------------------------------------------------------------------------------- /src/templates/installing/os/debian/name.txt: -------------------------------------------------------------------------------- 1 | Debian 2 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | site/ 2 | node_modules/ 3 | /docs 4 | .cache 5 | -------------------------------------------------------------------------------- /src/templates/installing/os/debian/mongo/config.txt: -------------------------------------------------------------------------------- 1 | /etc/mongod.conf -------------------------------------------------------------------------------- /src/templates/installing/os/debian/nodebb/setup.txt: -------------------------------------------------------------------------------- 1 | ./nodebb setup -------------------------------------------------------------------------------- /src/templates/installing/os/debian/nodebb/start.txt: -------------------------------------------------------------------------------- 1 | ./nodebb start -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/mongo/config.txt: -------------------------------------------------------------------------------- 1 | /etc/mongod.conf -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/nodebb/setup.txt: -------------------------------------------------------------------------------- 1 | ./nodebb setup -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/nodebb/start.txt: -------------------------------------------------------------------------------- 1 | ./nodebb start -------------------------------------------------------------------------------- /src/templates/installing/os/windows/nodebb/setup.txt: -------------------------------------------------------------------------------- 1 | nodebb setup -------------------------------------------------------------------------------- /src/templates/installing/os/windows/nodebb/start.txt: -------------------------------------------------------------------------------- 1 | nodebb start -------------------------------------------------------------------------------- /src/templates/installing/os/windows/mongo/config.txt: -------------------------------------------------------------------------------- 1 | C:\MongoDB\mongod.cfg -------------------------------------------------------------------------------- /src/docs/installing/os/.gitignore: -------------------------------------------------------------------------------- 1 | debian.md 2 | ubuntu.md 3 | windows.md 4 | -------------------------------------------------------------------------------- /src/templates/installing/os/windows/mongo/service/start.txt: -------------------------------------------------------------------------------- 1 | net start MongoDB -------------------------------------------------------------------------------- /src/templates/installing/os/debian/mongo/service/start.txt: -------------------------------------------------------------------------------- 1 | sudo systemctl start mongod -------------------------------------------------------------------------------- /src/templates/installing/os/debian/mongo/service/status.txt: -------------------------------------------------------------------------------- 1 | sudo systemctl status mongod -------------------------------------------------------------------------------- /src/templates/installing/os/debian/nginx/service/reload.txt: -------------------------------------------------------------------------------- 1 | sudo systemctl reload nginx -------------------------------------------------------------------------------- /src/templates/installing/os/debian/nginx/service/start.txt: -------------------------------------------------------------------------------- 1 | sudo systemctl start nginx -------------------------------------------------------------------------------- /src/templates/installing/os/debian/nginx/service/status.txt: -------------------------------------------------------------------------------- 1 | sudo systemctl status nginx -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/mongo/service/start.txt: -------------------------------------------------------------------------------- 1 | sudo systemctl start mongod -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/mongo/service/status.txt: -------------------------------------------------------------------------------- 1 | sudo systemctl status mongod -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/nginx/service/reload.txt: -------------------------------------------------------------------------------- 1 | sudo systemctl reload nginx -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/nginx/service/start.txt: -------------------------------------------------------------------------------- 1 | sudo systemctl start nginx -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/nginx/service/status.txt: -------------------------------------------------------------------------------- 1 | sudo systemctl status nginx -------------------------------------------------------------------------------- /src/templates/installing/os/windows/nginx/service/start.txt: -------------------------------------------------------------------------------- 1 | cd C:\nginx 2 | start nginx -------------------------------------------------------------------------------- /src/templates/installing/os/windows/nginx/service/status.txt: -------------------------------------------------------------------------------- 1 | tasklist | findstr nginx.exe -------------------------------------------------------------------------------- /src/templates/installing/os/debian/mongo/service/restart.txt: -------------------------------------------------------------------------------- 1 | sudo systemctl restart mongod -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/mongo/service/restart.txt: -------------------------------------------------------------------------------- 1 | sudo systemctl restart mongod -------------------------------------------------------------------------------- /src/templates/installing/os/windows/nginx/service/reload.txt: -------------------------------------------------------------------------------- 1 | cd C:\nginx 2 | nginx -s reload -------------------------------------------------------------------------------- /src/templates/installing/os/debian/git/install.md: -------------------------------------------------------------------------------- 1 | ```bash 2 | sudo apt-get install -y git 3 | ``` -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/git/install.md: -------------------------------------------------------------------------------- 1 | ```bash 2 | sudo apt-get install -y git 3 | ``` -------------------------------------------------------------------------------- /src/templates/installing/os/windows/mongo/service/status.txt: -------------------------------------------------------------------------------- 1 | sc query "MongoDB" | findstr STATE -------------------------------------------------------------------------------- /src/templates/installing/os/windows/mongo/service/restart.txt: -------------------------------------------------------------------------------- 1 | net stop MongoDB 2 | net start MongoDB -------------------------------------------------------------------------------- /src/templates/installing/os/debian/nginx/install.md: -------------------------------------------------------------------------------- 1 | ```bash 2 | sudo apt-get install -y nginx 3 | ``` 4 | -------------------------------------------------------------------------------- /src/docs/stylesheets/overrides.css: -------------------------------------------------------------------------------- 1 | .md-header-nav__button.md-logo img, .md-header-nav__button.md-logo svg { 2 | width: unset; 3 | } -------------------------------------------------------------------------------- /src/templates/installing/os/windows/node/install.md: -------------------------------------------------------------------------------- 1 | 1. [Download Node.js {{versions.recommended.node}}](https://nodejs.org) 2 | 2. Execute the installer 3 | -------------------------------------------------------------------------------- /src/templates/installing/os/windows/nginx/configs.md: -------------------------------------------------------------------------------- 1 | However, when installing with the method above, the `server` block config is embedded in `C:\nginx\conf\nginx.conf`. 2 | -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/nginx/install.md: -------------------------------------------------------------------------------- 1 | Switch back to the root user by running `exit` before proceeding. 2 | 3 | ```bash 4 | sudo apt-get install -y nginx 5 | ``` 6 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "dependencies": { 3 | "async": "^2", 4 | "body-parser": "^1.19.0", 5 | "deasync": "^0.1.12", 6 | "express": "^4.19.2", 7 | "klaw": "^2.1.1", 8 | "klaw-sync": "^3.0.2", 9 | "mkdirp": "^0.5.1", 10 | "node-version-data": "^1.0.1" 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /src/templates/installing/os/windows/git/install.md: -------------------------------------------------------------------------------- 1 | 1. Download Git for Windows [here](https://git-scm.com/download/win) 2 | 2. Execute that setup file to install Git 3 | 3. During setup, select the **Use Git from the Windows Command Prompt** option, which will correctly configure your PATH environment to use `git` 4 | -------------------------------------------------------------------------------- /src/docs/configuring/proxies/index.md: -------------------------------------------------------------------------------- 1 | Configuring Web Server / Proxies 2 | ================================ 3 | 4 | Here a few options that you can use to proxy your NodeBB forum. 5 | 6 | - [Nginx](./nginx.md) 7 | - [Apache v2.4.x+](./apache.md) 8 | - [Apache v2.2.x](./apache2.2.md) 9 | - [Varnish Cache](./varnish.md) 10 | - [Node.js](./node.md) 11 | 12 | -------------------------------------------------------------------------------- /src/docs/admin/index.md: -------------------------------------------------------------------------------- 1 | Administrative Functions 2 | ======================== 3 | 4 | The **Administrative Control Panel** (ACP) allows you to alter the behaviour of NodeBB, as well as customise various parts 5 | of its look and feel. Administrative functions such as user and group management are available from here. 6 | 7 | The ACP is only accessible to administrators, and thus should be protected from unauthorised access whenever possible. 8 | 9 | * [Dashboard](./dashboard.md) 10 | -------------------------------------------------------------------------------- /src/templates/installing/os/windows/nginx/install.md: -------------------------------------------------------------------------------- 1 | The following is an abbreviation of the [Windows nginx installation instructions](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/#official-win32-binaries). 2 | 3 | 1. Create a new directory `C:\nginx` 4 | 2. [Download the stable nginx win32 binary](http://nginx.org/en/download.html) 5 | 3. Double click to open the `.zip` file 6 | 4. Double click to open the enclosed `nginx-` directory 7 | 5. Select all of the enclosed files and directories 8 | 6. Copy them to `C:\nginx` 9 | -------------------------------------------------------------------------------- /src/docs/activitypub/fep/c0e0.md: -------------------------------------------------------------------------------- 1 | # c0e0: Emoji reactions 2 | 3 | FEP c0e0 describes the process by which Emoji reactions are implemented via the ActivityPub protocol. 4 | 5 | There are several existing implementations already in-place. 6 | 7 | ## Our implementation 8 | 9 | NodeBB has not implemented this FEP at this time. 10 | 11 | However, the existing functionality is present via [nodebb-plugin-reactions](https://github.com/NodeBB-Community/nodebb-plugin-reactions), and this plugin would likely need to be updated or rewritten in order to support this FEP. -------------------------------------------------------------------------------- /src/templates/installing/index.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | const versions = { 4 | minimum: { 5 | mongo: '5.0', 6 | redis: '7.2', 7 | node: '20.0', 8 | npm: '8.6.0', 9 | }, 10 | recommended: { 11 | mongo: '8.0', 12 | redis: '6.2.6', 13 | node: '22.x', 14 | npm: '10.8.2', 15 | nodebb: '4.x', 16 | }, 17 | }; 18 | 19 | versions.major = Object.keys(versions.recommended).reduce((prev, key) => { 20 | prev[key] = versions.recommended[key].split('.')[0]; 21 | return prev; 22 | }, {}); 23 | 24 | exports.versions = versions; 25 | -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/node/install.md: -------------------------------------------------------------------------------- 1 | Node.js is available from the NodeSource Ubuntu binary [distributions repository](https://github.com/nodesource/distributions?tab=readme-ov-file#using-ubuntu-nodejs-lts). Download the setup script. 2 | 3 | ```sh 4 | sudo apt-get update 5 | sudo apt-get install -y ca-certificates curl gnupg 6 | curl -fsSL https://deb.nodesource.com/setup_lts.x -o nodesource_setup.sh 7 | ``` 8 | 9 | Run the script and install Node.js. 10 | 11 | ```sh 12 | sudo -E bash nodesource_setup.sh 13 | sudo apt-get install -y nodejs 14 | ``` 15 | -------------------------------------------------------------------------------- /src/docs/configuring/databases/index.md: -------------------------------------------------------------------------------- 1 | Configuring Databases 2 | ===================== 3 | 4 | NodeBB has a Database Abstraction Layer (DBAL) that allows one to write 5 | drivers for their database of choice. Currently we have the following 6 | options: 7 | 8 | - [Mongo](./mongo.md) (default, [see installation guides](../../installing/os/index.md)) 9 | - [Redis](./redis.md) 10 | 11 | > **Note** 12 | > 13 | > If you would like to write your own database driver for NodeBB, please 14 | > visit our [community forum](https://community.nodebb.org) and we can 15 | > point you in the right direction. 16 | -------------------------------------------------------------------------------- /src/templates/installing/os/debian/nginx/configs.md: -------------------------------------------------------------------------------- 1 | When installing with the ppa above, the best way to install new nginx configs is to add new files in `/etc/nginx/sites-available` (like `/etc/nginx/sites-available/forum.example.org`). You then must link these files from `sites-available` to `sites-enabled`. 2 | 3 | The following demonstrates a typical series of commands when creating a new nginx config: 4 | 5 | ```bash 6 | cd /etc/nginx/sites-available 7 | sudo nano forum.example.com # config entered into file and saved 8 | cd ../sites-enabled 9 | sudo ln -s ../sites-available/forum.example.com 10 | ``` -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/nginx/configs.md: -------------------------------------------------------------------------------- 1 | When installing with the ppa above, the best way to install new nginx configs is to add new files in `/etc/nginx/sites-available` (like `/etc/nginx/sites-available/forum.example.org`). You then must link these files from `sites-available` to `sites-enabled`. 2 | 3 | The following demonstrates a typical series of commands when creating a new nginx config: 4 | 5 | ```bash 6 | cd /etc/nginx/sites-available 7 | sudo nano forum.example.com # config entered into file and saved 8 | cd ../sites-enabled 9 | sudo ln -s ../sites-available/forum.example.com 10 | ``` -------------------------------------------------------------------------------- /src/docs/configuring/proxies.rst: -------------------------------------------------------------------------------- 1 | Configuring Web Server / Proxies 2 | ================================ 3 | 4 | Here a few options that you can use to proxy your NodeBB forum. 5 | 6 | .. toctree:: 7 | :hidden: 8 | :maxdepth: 0 9 | 10 | Nginx 11 | Apache 12 | Apache v2.2.x 13 | Varnish Cache 14 | Node.js 15 | 16 | * :doc:`Nginx ` 17 | * :doc:`Apache v2.4.x+ ` 18 | * :doc:`Apache v2.2.x ` 19 | * :doc:`Varnish Cache ` 20 | * :doc:`Node.js ` -------------------------------------------------------------------------------- /src/docs/configuring/plugins/search.md: -------------------------------------------------------------------------------- 1 | # Search Plugins 2 | 3 | NodeBB comes bundled with the "dbsearch" engine, which does basic fulltext search using the database itself. Other search engines are available for download as third-party plugins, for Solr and Elasticsearch. 4 | 5 | You can find these plugins available for install in the "Extend -> Plugins" page. In nearly all cases, after installation, activation, and a NodeBB restart, you will need to enter the plugin's configuration page to enter some configuration info before searching will work. If you have existing content already, you may want to clear the search index and re-index the content. -------------------------------------------------------------------------------- /src/docs/development/style-guide.md: -------------------------------------------------------------------------------- 1 | # NodeBB Style Guide 2 | 3 | Core developers follow the [AirBnB Javascript Style Guide](https://github.com/airbnb/javascript/blob/master/README.md). This is enforced through the use of automatic eslint validation on push to the remote repository. 4 | 5 | As a developer you must follow this style guide for all pull requests, or they will not be merged. 6 | 7 | Third-party developers working on plugins and themes are free to disregard this style guide, although we encourage following it as a matter of best practice. 8 | 9 | * __Note:__ client-side code must stick with ES5 spec to be minified properly. 10 | -------------------------------------------------------------------------------- /src/docs/activitypub/prerelease.md: -------------------------------------------------------------------------------- 1 | ActivityPub integration is currently in development by the NodeBB team, and is slated for inclusion in the v4 major release of NodeBB. 2 | 3 | ## Development Roadmap 4 | 5 | Developed in public, the roadmap for integration can be found at the following GitHub projects: 6 | 7 | * [Road to Alpha](https://github.com/orgs/NodeBB/projects/1) 8 | * [Road to Beta](https://github.com/orgs/NodeBB/projects/2) 9 | 10 | ## Try out ActivityPub 11 | 12 | The easiest way to obtain the latest development code for v4 is to switch to the `activitypub` branch of the NodeBB project. 13 | 14 | ``` bash 15 | git fetch 16 | git checkout activitypub 17 | ./nodebb upgrade 18 | ``` -------------------------------------------------------------------------------- /src/docs/configuring/databases.rst: -------------------------------------------------------------------------------- 1 | Configuring Databases 2 | ===================== 3 | 4 | NodeBB has a Database Abstraction Layer (DBAL) that allows one to write drivers for their database of choice. Currently we have the following options: 5 | 6 | .. toctree:: 7 | :hidden: 8 | :maxdepth: 0 9 | 10 | MongoDB 11 | LevelDB 12 | 13 | * Redis (default, see :doc:`installation guides <../installing/os>`) 14 | * :doc:`Mongo ` 15 | 16 | .. note:: 17 | 18 | If you would like to write your own database driver for NodeBB, please visit our `community forum `_ and we can point you in the right direction. 19 | 20 | -------------------------------------------------------------------------------- /src/docs/installing/os/index.md: -------------------------------------------------------------------------------- 1 | NodeBB Installation by OS 2 | ========================= 3 | 4 | ### Hardware requirements (minimum) 5 | - 512MB RAM 6 | 7 | ### Guide 8 | 9 | The following are step-by-step guides to help you get up and running on various operating systems. 10 | 11 | - [Arch Linux](./arch.md) 12 | - [CentOS](./centos.md) 13 | - [Debian](./debian.md) 14 | - [Fedora](./fedora.md) 15 | - [FreeBSD](./freebsd.md) 16 | - [macOS](./macOS.md) 17 | - [SmartOS](./smartos.md) 18 | - [Ubuntu](./ubuntu.md) 19 | - [Windows](./windows.md) 20 | 21 | **Note** 22 | If your operating system is not listed here, please feel free to request a guide on our [community](https://community.nodebb.org) or better yet, submit one here. 23 | -------------------------------------------------------------------------------- /src/docs/admin/uploads.md: -------------------------------------------------------------------------------- 1 | Image Hosting APIs 2 | ================== 3 | 4 | Enabling Imgur Image Uploads 5 | ---------------------------- 6 | 7 | To enable post image attachments, install nodebb-plugin-imgur: 8 | 9 | ``` bash 10 | $ npm install nodebb-plugin-imgur 11 | ``` 12 | 13 | Follow the instructions on the plugin page: 14 | 15 | 16 | Uploading to Amazon S3 17 | ---------------------- 18 | 19 | To enable automatic Amazon S3 file storage, install 20 | nodebb-plugin-s3-uploads-updated 21 | 22 | ``` bash 23 | $ npm i @nodebb-community/nodebb-plugin-s3-uploads-updated 24 | ``` 25 | 26 | Follow the instructions on the plugin page: 27 | 28 | -------------------------------------------------------------------------------- /src/docs/installing/cloud/cloudron.md: -------------------------------------------------------------------------------- 1 | Cloudron 2 | ======== 3 | 4 | The following are installation instruction for the [Cloudron](https://cloudron.io). 5 | Cloudron is a platform for self-hosting web applications. 6 | 7 | NodeBB is available on the [Cloudron Store](https://cloudron.io/appstore.html). 8 | 9 | [![Install on Cloudron](https://cloudron.io/img/button.svg)](https://cloudron.io/button.html?app=org.nodebb.cloudronapp) 10 | 11 | Your NodeBB installation is backed up and kept up-to-date automatically. 12 | 13 | Demo 14 | ---- 15 | 16 | You can try NodeBB on our [demo](https://my.demo.cloudron.io) installation (username: `cloudron` password: `cloudron`) 17 | 18 | Code 19 | ---- 20 | 21 | The source code for the package is available [here](https://git.cloudron.io/cloudron/nodebb-app). 22 | -------------------------------------------------------------------------------- /src/templates/installing/os/debian/node/install.md: -------------------------------------------------------------------------------- 1 | Node.js is available from the NodeSource Debian binary distributions repository. 2 | 3 | 1. Download and import the Nodesource GPG key 4 | 5 | ```sh 6 | sudo apt-get update 7 | sudo apt-get install -y ca-certificates curl gnupg 8 | sudo mkdir -p /etc/apt/keyrings 9 | curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg 10 | ``` 11 | 12 | 2. Create deb repository 13 | 14 | ```sh 15 | echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_{{versions.major.node}}.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list 16 | ``` 17 | 18 | 3. Run Update and Install 19 | 20 | ```sh 21 | sudo apt-get update 22 | sudo apt-get install nodejs -y -------------------------------------------------------------------------------- /src/docs/activitypub/world.md: -------------------------------------------------------------------------------- 1 | # The `/world` page 2 | 3 | In addition to other sites being able to remotely view and respond to your content, you can also discover new content from NodeBB. This is established by "following" other users, similar to how you can follow users locally on NodeBB. [See "Content Discovery"](./discovery.md). 4 | 5 | The main difference between following a local user and a remote user is that **you are not notified of new content from remote users**. Instead, that content is added to the `/world` page, which is your personal curated list of content from users you follow, and content from other users shared by followed users. 6 | 7 | This page is structured like a regular category, with tools to filter down and sort topics. Incoming content is sorted into new or existing topics based on resolved context. -------------------------------------------------------------------------------- /src/templates/installing/os/debian/mongo/install.md: -------------------------------------------------------------------------------- 1 | The following is an abbreviation of the official [MongoDB installation guide for Debian](https://docs.mongodb.com/manual/tutorial/install-mongodb-on-debian/). If you're having issues, fall back to using that guide instead. 2 | 3 | ```bash 4 | sudo apt-get install gnupg curl 5 | curl -fsSL https://pgp.mongodb.com/server-{{versions.recommended.mongo}}.asc | \ 6 | sudo gpg -o /usr/share/keyrings/mongodb-server-{{versions.recommended.mongo}}.gpg \ 7 | --dearmor 8 | echo "deb [ signed-by=/usr/share/keyrings/mongodb-server-{{versions.recommended.mongo}}.gpg ] http://repo.mongodb.org/apt/debian bullseye/mongodb-org/{{versions.recommended.mongo}} main" | sudo tee /etc/apt/sources.list.d/mongodb-org-{{versions.recommended.mongo}}.list 9 | sudo apt-get update 10 | sudo apt-get install -y mongodb-org 11 | ``` 12 | -------------------------------------------------------------------------------- /src/docs/configuring/proxies/apache2.2.md: -------------------------------------------------------------------------------- 1 | # Configuring Apache v2.2.x as a reverse proxy to NodeBB 2 | 3 | Prerequisites: 4 | * `build-essential` 5 | * `automake` 6 | * `libtool` 7 | * [You can install these packages via `apt`](https://help.ubuntu.com/community/AptGet/Howto#Installation_commands) 8 | 9 | You need to manually compile and add the module `mod_proxy_wstunnel` to the Apache 2.2 branch. 10 | If you're running Ubuntu (prior to 14.04) or Debian, you're likely on the 2.2 branch of code. 11 | 12 | ### [Please use this guide to backport the `mod_proxy_wstunnel` module into the 2.2 code base of Apache](http://www.amoss.me.uk/2013/06/apache-2-2-websocket-proxying-ubuntu-mod\_proxy\_wstunnel/) 13 | 14 | *Note: On ubuntu, if you’re missing the ./configure file, you need to first run `./buildconf`. After this is complete, you will then be able to use `./configure`. 15 | -------------------------------------------------------------------------------- /src/templates/installing/os/ubuntu/mongo/install.md: -------------------------------------------------------------------------------- 1 | The following is an abbreviation of the official [MongoDB installation guide for Ubuntu](https://docs.mongodb.com/manual/tutorial/install-mongodb-on-ubuntu/). If you're having issues, fall back to using that guide instead. 2 | 3 | ```bash 4 | sudo apt-get install gnupg curl 5 | curl -fsSL https://www.mongodb.org/static/pgp/server-{{versions.recommended.mongo}}.asc | \ 6 | sudo gpg -o /usr/share/keyrings/mongodb-server-{{versions.recommended.mongo}}.gpg \ 7 | --dearmor 8 | echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-{{versions.recommended.mongo}}.gpg ] https://repo.mongodb.org/apt/ubuntu noble/mongodb-org/{{versions.recommended.mongo}} multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-{{versions.recommended.mongo}}.list 9 | sudo apt-get update 10 | sudo apt-get install -y mongodb-org 11 | ``` 12 | -------------------------------------------------------------------------------- /src/docs/activitypub/fep/7458.md: -------------------------------------------------------------------------------- 1 | # 7458: Using the replies collection 2 | 3 | NodeBB has elected to partially follow FEP 7458 for maintenance of the `replies` collection. 4 | 5 | ## Our implementation 6 | 7 | A `replies` route is available for every local post in NodeBB. This route resolves to an `OrderedCollection` containing a chronologically-ordered list of `Note` objects who have identified as being `inReplyTo` the requested post. 8 | 9 | In NodeBB, they are considered "direct replies". 10 | 11 | Please note that the replies route is always present even if there are no direct replies to the post. 12 | 13 | ## Partial Implementation 14 | 15 | FEP 7458 lays out the foundational elements related to cross-checking an incoming object for presence in the `inReplyTo.replies` collection. 16 | 17 | At this time NodeBB does not satisfy this requirement. All incoming objects are parsed, assuming they satisfy the internal check for an existing relation. -------------------------------------------------------------------------------- /src/docs/installing/cloud/index.md: -------------------------------------------------------------------------------- 1 | Installing NodeBB on the Cloud 2 | ============================== 3 | 4 | The following are step-by-step guides to help you get up and running on the cloud using popular PaaS solutions. 5 | 6 | NodeBB does not endorse nor provide maintenance and support for these services. Please contact the platform provider for additional assistance. 7 | 8 | * [Cloud9](https://community.nodebb.org/topic/7983/setting-up-nodebb-on-cloud-9) (external) 9 | * [Cloudron.io](./cloudron.md) 10 | * [DigitalOcean](http://www.blogsynthesis.com/install-nodebb-on-digitalocean/) (external) 11 | * [Heroku](./heroku.md) 12 | * [Jelastic](http://docs.jelastic.com/nodebb) (external) 13 | * [Nitrous.IO](./nitrous.md) 14 | * [Openshift](./openshift.md) 15 | * [Elestio](./elestio.md) 16 | * RoseHosting.com 17 | * [CentOS](https://www.rosehosting.com/blog/how-to-install-nodebb-on-a-centos-7-vps/) (external) 18 | * [Ubuntu](https://www.rosehosting.com/blog/install-and-setup-nodebb-with-redis-and-nginx-on-ubuntu-12-04/) (external) -------------------------------------------------------------------------------- /src/docs/configuring/proxies/varnish.md: -------------------------------------------------------------------------------- 1 | Configuring Varnish Cache 2 | ========================= 3 | 4 | To be sure Varnish will work properly with NodeBB check that your 5 | configuration `/etc/varnish/default.vcl` is optimized for 6 | **websockets**. 7 | 8 | ``` 9 | backend nodebb { 10 | .host = "127.0.0.1"; # your nodebb host 11 | .port = "4567"; # your nodebb port 12 | } 13 | 14 | sub vcl_recv { 15 | 16 | # Pipe websocket connections directly to Node.js 17 | if (req.http.Upgrade ~ "(?i)websocket") { 18 | set req.backend = nodebb; 19 | return (pipe); 20 | } 21 | 22 | # NodeBB 23 | if (req.http.host == "forum.yourwebsite.com") { # change this to match your host 24 | if (req.url ~ "^/socket.io/") { 25 | set req.backend = nodebb; 26 | return (pipe); # return pass seems not working for websockets 27 | } 28 | return (pass); # don't cache 29 | } 30 | 31 | } 32 | 33 | sub vcl_pipe { 34 | # Need to copy the upgrade header 35 | if (req.http.upgrade) { 36 | set bereq.http.upgrade = req.http.upgrade; 37 | } 38 | } 39 | ``` 40 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 NodeBB 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /src/docs/installing/os/arch.md: -------------------------------------------------------------------------------- 1 | Arch Linux 2 | ========== 3 | 4 | First, we install our base software stack. Be sure to `pacman -Syu` first 5 | to make sure you've synced with the repositories and all other packages 6 | are up to date. 7 | 8 | ``` 9 | $ sudo pacman -S git nodejs npm redis imagemagick icu 10 | ``` 11 | 12 | If you want to use MongoDB, LevelDB, or another database instead of 13 | Redis please look at the 14 | [Configuring Databases](../../configuring/databases/index.md) section. 15 | 16 | Next, clone this repository: 17 | 18 | ``` 19 | $ git clone -b v2.x https://github.com/NodeBB/NodeBB.git nodebb 20 | $ cd nodebb 21 | ``` 22 | 23 | Initiate the setup script by running the app with the `setup` flag: 24 | 25 | ``` 26 | $ ./nodebb setup 27 | ``` 28 | 29 | The default settings are for a local server running on the default port, 30 | with a redis store on the same machine/port. 31 | 32 | Lastly, we run the forum. 33 | 34 | ``` 35 | $ ./nodebb start 36 | ``` 37 | 38 | NodeBB can also be started with helper programs, such as `supervisor` 39 | and `forever`. 40 | Take a look at the options [here](../../configuring/running.md). 41 | -------------------------------------------------------------------------------- /src/docs/configuring/plugins/emailers.md: -------------------------------------------------------------------------------- 1 | # Emailer Plugins 2 | 3 | NodeBB will elect to send mail via the local mail service installed on the server if possible. If you are not receiving emails, then it may be a result of the mail service not being installed or configured, or that the receiving mail server has rejected it as it may have been classified as spam. 4 | 5 | We recommend utilising third-party emailer systems as they have been sending out emails for much longer than your server, and have built a reputation that you can utilise to ensure that emails you send end up in the inboxes of your recipients. 6 | 7 | Any plugins that begin with "nodebb-plugin-emailer" are emailer plugins that override the default behaviour of NodeBB and send mail through the plugin's service. For example, `nodebb-plugin-emailer-sendgrid` will allow you to send emails via the [SendGrid](//sendgrid.com) service. 8 | 9 | You can find these plugins available for install in the "Extend -> Plugins" page. In nearly all cases, after installation, activation, and a NodeBB restart, you will need to enter the plugin's configuration page to enter some sort of API key before it will send emails. -------------------------------------------------------------------------------- /src/docs/installing/cloud/nitrous.md: -------------------------------------------------------------------------------- 1 | Nitrous.IO 2 | ========== 3 | 4 | The following are installation instructions for the [Nitrous.IO](http://nitrous.io). 5 | 6 | **Step 1:** Create a new application in boxes with NodeJS : 7 | 8 | 9 | 10 | **Step 2:** Open terminal / SSH to the application / Open IDE 11 | 12 | **Step 3:** Get the files of NodeBB, unzip, delete master.zip and cd to 13 | the folder 14 | 15 | ``` 16 | wget https://github.com/NodeBB/NodeBB/archive/v2.x.zip && unzip NodeBB-v2.x.zip && rm NodeBB-v2.x.zip && cd NodeBB-v2.x 17 | ``` 18 | 19 | **Step 4:** Install Redis 20 | 21 | ``` 22 | parts install redis 23 | ``` 24 | 25 | **Step 5:** Setup NodeBB 26 | 27 | ``` 28 | ./nodebb setup 29 | ``` 30 | 31 | Leave everything as default but you can change yourself. 32 | 33 | I recommend the port number to bind : 8080 34 | 35 | **Step 6:** And the last one, start NodeBB 36 | 37 | ``` 38 | ./nodebb start 39 | ``` 40 | 41 | And then open the "Preview URI" without port if you have put for port : 42 | 8080. 43 | 44 | Note 45 | ---- 46 | 47 | You can expand the resources of the application : 48 | . 49 | -------------------------------------------------------------------------------- /src/docs/installing/os/freebsd.md: -------------------------------------------------------------------------------- 1 | FreeBSD 2 | ======= 3 | 4 | This guide is for FreeBSD 10.1-RELEASE. It should work, with slight 5 | modifications, for all other relatively modern versions. 6 | 7 | Make sure you are up to date, by running: 8 | 9 | ``` 10 | freebsd-update fetch 11 | freebsd-update install 12 | ``` 13 | 14 | Install Redis: 15 | 16 | ``` 17 | pkg install redis 18 | ``` 19 | 20 | Follow the regular steps to run Redis at the runlevel, and start it. 21 | 22 | Install gcc5: 23 | 24 | ``` 25 | pkg install gcc5 26 | ``` 27 | 28 | Install Node: 29 | 30 | ``` 31 | pkg install node 32 | ``` 33 | 34 | Clone NodeBB repo (this assumes you have git installed, otherwise use 35 | pkg to install it): 36 | 37 | ``` 38 | git clone -b v2.x https://github.com/NodeBB/NodeBB.git 39 | ``` 40 | 41 | Enter directory: 42 | 43 | ``` 44 | cd nodebb 45 | ``` 46 | 47 | Run interactive installation: 48 | 49 | ``` 50 | ./nodebb setup 51 | ``` 52 | 53 | You may leave all of the options as default. 54 | 55 | You are finished! After the installation, run: 56 | 57 | ``` 58 | ./nodebb start 59 | ``` 60 | 61 | Visit your forum at `http://FQDN:4567/` to finish configuration and 62 | setup. FQDN is the server fully qualified domain name. 63 | -------------------------------------------------------------------------------- /src/docs/configuring/plugins/index.md: -------------------------------------------------------------------------------- 1 | # Plugins 2 | 3 | NodeBB itself is designed to be lean, with a minimal feature set of core functionality that most (if not all) users will find useful. Additional esoteric features and behavioural changes may be added via the use of third-party plugins. 4 | 5 | Plugins themselves are hosted on npm, and are created by third-party developers and in some cases, the NodeBB developers themselves. 6 | 7 | ## Installing Plugins 8 | 9 | You are encouraged to install plugins that appear in the admin control panel, as those are plugins that have been cleared for installation with the current version of NodeBB you have installed. You can access this menu by navigating to "Extend -> Plugins" from the Administrative Control Panel, in order to browse the list of supported plugins. 10 | 11 | Plugins that are publicly hosted but do not appear in this list may not be compatible, but can still be installed via the command line: 12 | 13 | ``` 14 | $ npm install nodebb-plugin-someplugin 15 | ``` 16 | 17 | However, we do not recommend doing so as incompatiblities may result in the crashing of your NodeBB forum. If this occurs, you'll want to deactivate the plugin: 18 | 19 | ``` 20 | $ ./nodebb reset -p nodebb-plugin-someplugin 21 | ``` -------------------------------------------------------------------------------- /src/docs/admin/dashboard.md: -------------------------------------------------------------------------------- 1 | # ACP / Dashboard 2 | 3 | The dashboard shows an at-a-glance overview of your NodeBB, including pageviews collated by time and day, and other interesting metrics such as current active user count and user location. 4 | 5 | ### System Control 6 | 7 | The "Reload", "Restart", and "Maintenance Mode" buttons allow you to administer the running process of NodeBB. 8 | 9 | * **Reload** - refreshes all stylesheets, js files, and templates. Clears caches if there are any. The NodeBB server is kept running. 10 | * **Restart** - Brings down the NodeBB server and starts it up again. Refreshes all assets and clears all caches. A restart is recommended if you have activated or deactivated plugins. 11 | * **Maintenace Mode** - Brings you to the maintenance mode page, allowing you to temporarily restrict access to your forum. 12 | 13 | ### Updates 14 | 15 | The updates section queries the NodeBB project for a new version of NodeBB, and determines whether you are up-to-date. There is no requirement to update NodeBB, although it is usually recommended in order to obtain the latest features and bug fixes. 16 | 17 | ### Notices 18 | 19 | The notices allows NodeBB and various plugins to quickly determine if action is required (e.g. if a restart is required). -------------------------------------------------------------------------------- /daemon: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | 3 | 'use strict'; 4 | 5 | const path = require('path'); 6 | const express = require('express'); 7 | const bodyParser = require('body-parser'); 8 | const crypto = require('crypto'); 9 | const execFile = require('child_process').execFile; 10 | const async = require('async'); 11 | 12 | const app = express(); 13 | 14 | app.use(bodyParser.json({ 15 | verify: function (req, res, buf, encoding) { 16 | let hash = crypto.createHmac('sha1', process.env.SECRET); 17 | hash.update(buf); 18 | let digest = hash.digest('hex'); 19 | 20 | res.locals.verified = String('sha1=' + digest) === req.headers['x-hub-signature']; 21 | } 22 | })); 23 | 24 | app.post('/github', function (req, res) { 25 | var headers = req.headers; 26 | let shasum = crypto.createHash('sha1'); 27 | 28 | // Basic sanity checks 29 | if (!req.body || req.headers['x-github-event'] !== 'push' || !res.locals.verified) { 30 | return res.sendStatus(400); 31 | } 32 | 33 | execFile('/bin/bash', [path.join(__dirname, 'build.sh')], function (err) { 34 | res.sendStatus(err ? 500 : 200); 35 | 36 | if (err) { 37 | console.error('Docs build failed @ ' + new Date().toISOString(), err.stack); 38 | } else { 39 | console.log('Docs build completed @ ' + new Date().toISOString()); 40 | } 41 | }); 42 | }); 43 | 44 | app.listen(8001); 45 | -------------------------------------------------------------------------------- /src/docs/activitypub/privileges.md: -------------------------------------------------------------------------------- 1 | Fine-grained privileges are available for all NodeBB categories, allowing for user actions such as upvotes, replies, and even viewership access to be gated to certain user groups. 2 | 3 | Likewise, fine-grained control over federation is available at the category-level, and is exposed as the "fediverse" pseudo-group in each category's privilege table. 4 | 5 | The "fediverse" pseudo-group is a catch-all that encompasses all remote users, and the privileges available dictate whether received activities from the fediverse are accepted by NodeBB. The privileges are self-explanatory (e.g. "Edit Posts" privilege governs whether remote users are allowed to update their posts.), but several have additional effects or whose effects are not immediately apparent. 6 | 7 | These effects are listed below: 8 | 9 | * Global 10 | * View Users (`view:users`) 11 | * Whether a remote user can retrieve a local user's profile and/or follow them. 12 | * *N.B. "guests" will also need the `view:users` privilege for profiles to be retrievable via the fediverse* 13 | * Per category 14 | * Find Category (`find`) 15 | * Whether a category can be retrieved via the fediverse 16 | * Access Category (`read`) 17 | * Whether a category can be followed by a remote user 18 | * Access Topics (`topics:read`) 19 | * Also controls whether local replies are federated out 20 | * Create Topics (`topics:create`) 21 | * Whether a remote user can create a topic in that category by mentioning it 22 | -------------------------------------------------------------------------------- /src/docs/development/plugins/libraries.md: -------------------------------------------------------------------------------- 1 | # Using Third-Party Libraries 2 | 3 | Plugins are able to define libraries for use on the client side through use of the `scripts` property in `plugin.json`, 4 | but occasionally, you may want to include a dependent script that you did not write. Oftentimes, these scripts are 5 | written in AMD-style, and can be used by a module loader such as [require.js](//requirejs.org), but NodeBB is unable 6 | to load them because they are not also often defined by name. 7 | 8 | You may see errors like this: 9 | 10 | `Uncaught Error: Mismatched anonymous define() module ...` 11 | 12 | This is a common error with anonymous modules, [as is explained in this help article](http://requirejs.org/docs/errors.html#mismatch). 13 | In a nutshell, because we minify all javascript files defined in `scripts` or `acpScripts`, there is no context left for require.js to 14 | determine where a file is in relation to where it is called from. 15 | 16 | In NodeBB, you'll want to use the `modules` property in `plugin.json` to properly name these modules so they can be referenced and linked properly: 17 | 18 | **plugin.json** 19 | 20 | ``` 21 | { 22 | ... 23 | "modules": { 24 | "jquery.js": "/path/to/jquery.js" 25 | }, 26 | ... 27 | } 28 | ``` 29 | 30 | From your client-side scripts, you can then load the jQuery module via require.js as follows: 31 | 32 | ``` 33 | require(['jquery'], function ($) { 34 | $('.someClass').addClass('someotherclass'); 35 | }); 36 | ``` 37 | 38 | Keep in mind this is a contrived example, as jQuery is already available globally in NodeBB. 39 | -------------------------------------------------------------------------------- /src/templates/installing/os/windows/mongo/install.md: -------------------------------------------------------------------------------- 1 | The following is an abbreviation of the official [MongoDB installation guide for Windows](https://docs.mongodb.com/manual/tutorial/install-mongodb-on-windows/). 2 | 3 | #### Go to the [MongoDB Download Center](https://www.mongodb.com/download-center#production) and download the appropriate setup file 4 | 5 | #### Locate the downloaded `.msi` file and execute it to start the installer 6 | 7 | The default installation location is `C:\Program Files\MongoDB\Server\{{versions.recommended.mongo}}` 8 | 9 | #### Add the MongoDB binaries to your PATH 10 | 1. Find the `bin` directory under your MongoDB installation 11 | The default path is `C:\Program Files\MongoDB\Server\{{versions.recommended.mongo}}\bin` 12 | 2. Type PATH into the Start Menu search bar 13 | 3. Open **Edit environment variables for your account** 14 | 4. Under **User variable for [your username]**, click on `Path` 15 | 5. Click the **Edit...** button 16 | 6. Click the **New** button on the right 17 | 7. Type or paste in the full path to the `bin` directory 18 | 19 | #### Configure a service for the `mongod` server 20 | 21 | 1. Open an administrator command prompt 22 | 23 | 2. Create two directories for your database and log files. We'll use `C:\MongoDB\data\db` and `C:\MongoDB\logs` 24 | 25 | 3. Create a config file (`{{mongo.config}}`) defining those paths 26 | 
systemLog:
27 |     destination: file
28 |     path: C:\MongoDB\logs\mongod.log
29 | storage:
30 |     dbPath: C:\MongoDB\data\db
 31 | 32 | 4. Install the MongoDB service 33 | 
mongod.exe --config "{{mongo.config}}" --install
 34 | -------------------------------------------------------------------------------- /src/docs/development/plugins/uncategorized.md: -------------------------------------------------------------------------------- 1 | # Uncategorized (`cid -1`) 2 | 3 | `Availability: >4.0.0` 4 | 5 | When categories are created, they are assigned a numeric category id (or `cid`). NodeBB's initial setup populates four categories, which take up cids 1 through 4. 6 | 7 | Additionally, there is a pseudo-category present in the UI with the cid `-1`. This is the "uncategorized" pseudo-category that does not strictly exist in the database as an editable category. 8 | 9 | ## How it is used 10 | 11 | It is used by the ActivityPub integration to automatically slot received content that was not addressed to a specific category. Due to its rather free-for-all nature, content in cid `-1` is also subject to regular pruning. 12 | 13 | ## How it can be used 14 | 15 | There is no restriction on the usage of cid `-1`. You may post topics into that category just like any other; by passing in `-1` to the `cid` property when calling `api.topics.create`. 16 | 17 | *N.B. As content pruning only applies to topics with no engagement from local users, any topics created by local users are automatically exempt from pruning.* 18 | 19 | This can be a useful construct for plugins that wish to take advantage of the pre-existing structure of topics and posts, without having to create their own data structures from scratch. 20 | 21 | For example, a plugin exposing the capability for users to self-journal could utilise the existing internal API and post journal entries (aka topics) into cid `-1`. In that scenario, the only thing required would be to maintain a list of journal entries (tids) by user, as opposed to building out the entire model and controller for saving journal entries into the database. -------------------------------------------------------------------------------- /src/docs/configuring/proxies/caddy.md: -------------------------------------------------------------------------------- 1 | From [caddyserver.com](//caddyserver.com): 2 | > Caddy 2 is a powerful, enterprise-ready, open source web server with automatic HTTPS written in Go 3 | 4 | The configurations here assume you have installed Caddy [via package manager](https://caddyserver.com/docs/install#debian-ubuntu-raspbian), and are using [systemd to run Caddy](https://caddyserver.com/docs/running). 5 | 6 | ---- 7 | 8 | Here is a dead-simple way to have Caddy act as a reverse-proxy in front of NodeBB: 9 | 10 | ``` 11 | caddy reverse_proxy --from example.org --to localhost:4567 12 | ``` 13 | 14 | **That was fast!** – but we'll probably want something more permanent. 15 | 16 | ---- 17 | 18 | To use a `Caddyfile` instead (which you probably do), here is that same setup: 19 | 20 | ``` 21 | example.org 22 | reverse_proxy localhost:4567 23 | ``` 24 | 25 | Save those two lines into `/etc/caddy/Caddyfile` and reload Caddy (`systemctl reload caddy`). This configuration will work even if you have configured NodeBB's `url` to contain a subfolder. 26 | 27 | ---- 28 | 29 | If you want a more robust setup with compression and direct file-serving for built assets (as mentioned in [Scaling NodeBB](../scaling.md)): 30 | 31 | ``` 32 | example.org { 33 | encode zstd gzip 34 | root * /path/to/nodebb 35 | 36 | handle_path /assets/* { 37 | try_files /build/public/{path} /public/{path} 38 | file_server 39 | } 40 | 41 | handle { 42 | reverse_proxy localhost:4567 43 | } 44 | } 45 | ``` 46 | 47 | **Neat!** 48 | 49 | In this example, you'll need to modify `/path/to/nodebb` to point to your NodeBB installation. If you are configuring a subfolder install, prepend the folder name to `/assets` (e.g. `/forum/assets/*`). -------------------------------------------------------------------------------- /src/docs/installing/cloud/elestio.md: -------------------------------------------------------------------------------- 1 | Elestio 2 | ====== 3 | 4 | 5 | Initiate Deployment 6 | --------------------- 7 | 8 | Begin by clicking the "Deploy" button below to kickstart the deployment process. This will set up NodeBB on Elestio seamlessly. 9 | 10 | [![Deploy on Elestio](https://elest.io/images/logos/deploy-to-elestio-btn.png)](https://elest.io/open-source/nodebb) 11 | 12 | Choose Your Providers 13 | --------------------- 14 | 15 | 1. Select the cloud service provider of your choice. 16 | 17 | 2. Choose the region that aligns with your preferences. 18 | 19 | 3. Opt for a service plan based on your needs, with details such as CPU and RAM provided. 20 | 21 | 4. Confirm your selections and proceed to the next step by clicking "Next." 22 | 23 | 24 | Configuration 25 | -------------- 26 | 27 | 1. Choose the support level that suits your requirements. 28 | 29 | 2. Provide a name for your application. 30 | 31 | 3. Add an admin email for accessibility. 32 | 33 | 4. Click "Create Service" to initialize the setup. 34 | 35 | 5. Optionally, copy your Terraform config for future reference. 36 | 37 | Utilize NodeBB 38 | -------------- 39 | 40 | 1. Click on "Display Admin UI." 41 | 2. Access the Admin UI using the link provided. 42 | 3. Enter the username and password provided on the dashboard. 43 | 44 | 45 | Keep NodeBB Updated 46 | ------------------- 47 | 48 | 1. Navigate to the Overview section within your NodeBB service. 49 | 50 | 2. Click "Change version" in the Software section. 51 | 52 | 3. Choose the latest version or your preferred version. 53 | 54 | 4. Optionally, update configurations or restart the instance with a single click under the same section. 55 | 56 | 57 | Congratulations! Your NodeBB instance on Elestio is now successfully deployed and configured. Feel free to explore and utilize its capabilities or update as needed. -------------------------------------------------------------------------------- /src/docs/activitypub/fep/index.md: -------------------------------------------------------------------------------- 1 | # Fediverse Enhancement Proposals 2 | 3 | While the ActivityPub protocol enables NodeBB to connect to the wider fediverse, there have been additional proposals that make the integration richer, both for developers and end-users alike. 4 | 5 | There [are many proposals currently listed](https://codeberg.org/fediverse/fep/src/branch/main), and not all of them apply to NodeBB or fit with our current roadmap. A list of relevant FEPs, their integration state (if any), and our general sentiment towards them are listed here. 6 | 7 | This page is styled in a manner similar to [Mozilla's Specification Positions](https://mozilla.github.io/standards-positions/) page. We will use the same terms: "positive", "neutral", "defer", and "negative". 8 | 9 | | Identifier | Proposal | Position | Implemented | More 10 | |-|-|-|-|-| 11 | | [1b12](./1b12.md) | Group Federation | positive | yes | [Proposal](https://w3id.org/fep/1b12) 12 | | 171b | Conversation Containers | positive | no | *TBD* 13 | | 400e | Publicly-appendable ActivityPub collections | neutral | partial | [Proposal](https://w3id.org/fep/400e) 14 | | [7458](./7458.md) | Using the replies collection | positive | partial | [Proposal](https://w3id.org/fep/7458) 15 | | [7888](./7888.md) | Demystifying the context property | positive | yes | [Proposal](https://w3id.org/fep/7888) 16 | | 8b32 | Object Integrity Proofs | positive | no | [Proposal](https://w3id.org/fep/8b32) 17 | | 9967 | Polls | positive | no | [Proposal](https://w3id.org/fep/9967) 18 | | [c0e0](./c0e0.md) | Emoji reactions | positive | no | [Proposal](https://w3id.org/fep/c0e0) 19 | | d36d | Sharing Content Across Federated Forums | neutral | no | [Proposal](https://w3id.org/fep/d36d) 20 | | fb2a | Actor metadata | positive | yes | [Proposal](https://w3id.org/fep/fb2a) 21 | | f1d5 | NodeInfo in Fediverse Software | positive | yes | [Proposal](https://w3id.org/fep/f1d5) 22 | | | All other FEPs | defer | | | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # NodeBB Documentation Portal 2 | 3 | This repository houses the content and source code for the [documentation portal](//docs.nodebb.org). 4 | 5 | ## Contributing 6 | 7 | The primary method of contributing is by [making a pull request](https://github.com/NodeBB/docs/pulls). You can either edit the source code directly in GitHub (which would automatically fork the repository into your own account), or by cloning a local copy and forking the repository manually. 8 | 9 | Documentation is written in Markdown. While Markdown supports HTML, we encourage the _minimal use of HTML_ so as to ensure that all documentation is of similar style. 10 | 11 | If there are insufficient articles or incorrect information, please [file a new issue](https://github.com/NodeBB/docs/issues/new) against this repository. It will help us ensure that content is kept up to date. 12 | 13 | When changes are committed or pull requests merged, the documentation portal will be updated automatically. If this is not the case, please open an issue for us to investigate. 14 | 15 | ## How to test your changes 16 | 17 | If you want to take a look at how your changes look, you can run a local install of the documentation portal. 18 | 19 | 1. Install pip: `sudo apt-get update && sudo apt-get install python3-pip` 20 | 1. Install mkdocs: `pip3 install mkdocs` (you may need sudo for this, Windows users may need to run `python -m pip install mkdocs` instead) 21 | 1. Install the `material` theme: `pip3 install mkdocs-material "mkdocs-material[imaging]"` 22 | 1. From repo root, create a symbolic link pointing to `src/docs`: `ln -s ./src/docs` 23 | 1. Install dependencies: `yarn` or `npm` 24 | 1. Build templates: `node src/compile.js` 25 | 1. Start development mode: `mkdocs serve` (run this from the root of the checked out repository, `python -m mkdocs serve` for Windows) 26 | 1. Browse to `http://localhost:8000` 27 | 28 | The page will automatically refresh every time any files are changed. 29 | 30 | ## Localisation 31 | 32 | At this time we do not have plans to localise the NodeBB documentation. -------------------------------------------------------------------------------- /src/docs/installing/os/centos.md: -------------------------------------------------------------------------------- 1 | CentOS 6/7 2 | ========== 3 | 4 | First we should make sure that CentOS is up to date, we can do so using 5 | this command: 6 | 7 | ``` 8 | yum -y update 9 | ``` 10 | 11 | \*\*If you're on CentOS 7, you will need to install the epel release, you 12 | can do so using the following command: 13 | 14 | ``` 15 | yum -y install epel-release 16 | ``` 17 | 18 | Now, we install our base software stack: 19 | 20 | ``` 21 | yum -y groupinstall "Development Tools" 22 | yum -y install git redis ImageMagick npm 23 | ``` 24 | 25 | Now we need install nodejs via npm as the repo package is too old. 26 | 27 | ``` 28 | curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash 29 | source ~/.bash_profile 30 | nvm list-remote 31 | nvm install v14.18.1 # as of this writing check the result of the list-remote to see all choices 32 | ``` 33 | 34 | Now start redis and set it to start on reboot 35 | 36 | ``` 37 | systemctl start redis 38 | systemctl enable redis 39 | ``` 40 | 41 | If you want to use MongoDB, LevelDB, or another database instead of 42 | Redis please look at the 43 | [Configuring Databases](../../configuring/databases/index.md) section. 44 | 45 | Next, clone the NodeBB repository: 46 | 47 | ``` 48 | cd /path/to/nodebb/install/location 49 | git clone -b v2.x https://github.com/NodeBB/NodeBB nodebb 50 | cd nodebb 51 | ``` 52 | 53 | \*\*Note: To clone the master branch you can use the same command with 54 | out the "-b" option. 55 | 56 | Initiate the setup script by running the app with the `setup` flag: 57 | 58 | ``` 59 | ./nodebb setup 60 | ``` 61 | 62 | The default settings are for a local server running on the default port, 63 | with a redis store on the same machine/port. 64 | 65 | Assuming you kept the default port setting, you need to allow it through 66 | the firewall. 67 | 68 | ``` 69 | firewall-cmd --zone=public --add-port=4567/tcp --permanent 70 | firewall-cmd --reload 71 | ``` 72 | 73 | Lastly, we run the forum. 74 | 75 | ``` 76 | ./nodebb start 77 | ``` 78 | 79 | NodeBB can also be started with helper programs, such as `forever`. 80 | Take a look at the options [here](../../configuring/running.md). 81 | 82 | -------------------------------------------------------------------------------- /src/docs/activitypub/settings.md: -------------------------------------------------------------------------------- 1 | The settings page for ActivityPub integration can be reached in the administration panel: 2 | 3 | **ACP > Settings > Federation (ActivityPub)** 4 | 5 | ## General 6 | 7 | * "Enable Federation" 8 | * This is the global toggle that controls whether NodeBB federates at all. Use this toggle as a convenience switch to enable or disable federation completely. 9 | * "Allow loopback processing" 10 | * This setting allows the NodeBB installation to make ActivityPub calls to itself. It is purely used for development and debugging and should be left disabled in production. 11 | 12 | ## Content Pruning 13 | 14 | The fediverse is large — that's probably an understatement! As more and more content streams into NodeBB from the fediverse, the database will grow in size. Content streams in at all hours of the day, and it is very likely that of the content received by NodeBB, only a miniscule fraction would be read by your users. 15 | 16 | It is important to understand that it is not your responsibility to catalog the entire fediverse, and there is absolutely no expectation that you keep everything you receive in perpetuity. The remote content received is best thought of as transient, and can be expunged from the data store as soon as is reasonable. 17 | 18 | NodeBB prunes remote content and user profiles on a daily basis, and that caching interval can be adjusted. 19 | 20 | * "Days to keep remote content" 21 | * Topics containing content that has received no "engagement" are automatically pruned after 30 days (default, adjustable) 22 | * A topic is considered to have engagement if at least one of the posts within has been voted upon, or if a local user has replied to it. 23 | * "Days to keep remote user accounts" 24 | * A remote user account is automatically pruned after 7 days (default, adjustable). 25 | * Remote user accounts are pruned if they have not made any posts, and have no follow relationships with local users. 26 | 27 | ## Filtering 28 | 29 | Heavy-handed global filtering options are available here, allowing the administrator to make unilateral decisions about whether to federate with (or allow remote content from) certain domains. 30 | 31 | The list can be either a deny-list (default), or an allow-list. -------------------------------------------------------------------------------- /src/docs/activitypub/fep/7888.md: -------------------------------------------------------------------------------- 1 | # 7888: Demystifying the context property 2 | 3 | FEP 7888 deals with adding some specificity to the `context` property as originally specified in [the ActivityStreams vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-context): 4 | 5 | > ActivityStreams Vocabulary defines the context property, but it is "intentionally vague". Unfortunately, this makes the definition so vague as to be practically useless. This FEP aims to provide more guidance on possible uses of the context property, as well as formalizing some best practices. 6 | 7 | — FEP Summary 8 | 9 | ## Our implementation 10 | 11 | Every post in NodeBB has the capability to be federated outward (whether it is done so is [governed by the containing category's privilege settings](../privileges.md)). When done so, the object will contain the `context` property as indicated by the FEP. 12 | 13 | This `context` property is the URL of the NodeBB topic. 14 | 15 | ## The resolvable context 16 | 17 | The `context` value in each post (aka ActivityPub `Note`) is also resolvable via ActivityPub. 18 | 19 | While FEP 7888 does not explicitly detail the specifics of the resolvable context, NodeBB sends back an `OrderedCollection` that contains the posts in that topic, with the appropriate sub-properties to allow it to be paginated if necessary. 20 | 21 | This resolvable context enables the ability for other implementors to backfill an entire topic (or their nomenclatural equivalent) in its entirety without relying on other less-performant alternatives such as `inReplyTo` traversal. 22 | 23 | ## The `Add` activity (or Inbox Forwarding) 24 | 25 | The FEP specifies the sending of `Add` activities when new content is discovered. At this time, NodeBB will not send the `Add` activity or forward the accepted activity to its followers. 26 | 27 | ## The future 28 | 29 | FEP 7888 has done a great service in presenting a framework for use of the `context` property. It takes into account that the property is already used by other implementors in a different fashion, and should work seamlessly in conjunction with them. 30 | 31 | Much of the future of `context` is currently undecided, but it is the primary focus of the SWICG Forums and Threaded Discussions Task Force (ForumWG). -------------------------------------------------------------------------------- /src/docs/installing/cloud/docker.md: -------------------------------------------------------------------------------- 1 | NodeBB includes a [bundled Dockerfile](https://github.com/NodeBB/NodeBB/blob/master/Dockerfile) and configuration for use with Docker-compatible container systems. 2 | 3 | The configuration (and this documentation) is community-maintained, and those looking for support should create a new topic 4 | [on the community forum](https://community.nodebb.org/category/16/technical-support). 5 | 6 | ### Docker Compose usage 7 | 8 | An example instance of NodeBB can also be rapidly started using Docker Compose provided in this repo. 9 | At least Docker Compose version 3.8 is required. 10 | 11 | ### Choosing your database 12 | 13 | You will need to choose the type of database first. In this repo you can choose the following three profiles 14 | 15 | - mongo 16 | - postgres 17 | - redis 18 | 19 | For MongoDB, PostgreSQL (legacy), Redis support respectively. 20 | This will be supplied along with the main Docker Compose launch command as extra file source. 21 | Let's call this `{DATABASE}` shall we? 22 | 23 | ### Starting NodeBB 24 | 25 | To start the example, you just need to run the command in the following style 26 | ```bash 27 | $ docker-compose --profile {DATABASE} up 28 | ``` 29 | After few minutes or so you should be able to see (console output may be clobbered): 30 | ```bash 31 | nodebb_1 | Config file not found at /opt/config/config.json 32 | nodebb_1 | Starting installer 33 | nodebb_1 | 2022-07-10T15:05:35.085Z [23] - info: Launching web installer on port 4567 34 | nodebb_1 | 2022-07-10T15:05:47.697Z [23] - info: Web installer listening on http://0.0.0.0:4567 35 | ``` 36 | Now open your browser and access to http://localhost:4567. 37 | 38 | **The default database host is the name of your database, so type in `redis` if you used Redis, `mongo` using MongoDB, etc.** 39 | 40 | Your stateful files (build artifacts, node_modules, database data) will be stored at `.docker` at the current working directory, 41 | but you are adviced to not rely on the default Docker Compose setup and instead make up your own. 42 | 43 | #### Additional information for MongoDB 44 | 45 | For MongoDB, please notice that you need to use **admin** as database at the moment, since for some reason the latest version of the official 46 | MongoDB docker did not take in account for `MONGO_INITDB_DATABASE`, so the default `admin` database is still used. -------------------------------------------------------------------------------- /src/docs/development/plugins/parsing.md: -------------------------------------------------------------------------------- 1 | # Post Parsing 2 | 3 | NodeBB is editor-agnostic, meaning that the default composer and markup plugin combination (composer-default and markdown, respectively) can be swapped out if desired. 4 | 5 | To achieve this, NodeBB fires a number of hooks that deal with parsing of content. 6 | This article deals with the `filter:parse:post` hook, which is called by `posts.parsePost`. 7 | 8 | ## Function signature 9 | 10 | `parsePosts(post, type)` 11 | 12 | * `post` is an object containing post data, typically from a call to `posts.getPostData(pid);`. 13 | * *N.B. You don't need to send in the entire post object, the minimum set of properties is `pid` and `content`.* 14 | * `type` is a nullable string that hints to plugins what the desired output is. The values are one of the following: 15 | * `null`/`falsy`, which is automatically passed to plugins as `default`. 16 | * `default`, html for display in the front-end. 17 | * `plaintext`, self-explanatory, no html markup intended. 18 | * `activitypub.note`, html for federation to remote instances (see [Federation](../../activitypub/index.md)); typically a subset of valid html tags are used, such as those related to text formatting. 19 | * `activitypub.article`, html for federation to remote instances (see [Federation](../../activitypub/index.md)); this type is reserved for future use. 20 | * `markdown`, markdown for federation to remote instances (see [Federation](../../activitypub/index.md)); in most cases this is the same as the raw content 21 | 22 | ## Guidance 23 | 24 | When your plugin listens to `filter:parse.post`, you should look at the `types` available and consider whether your plugin should respond to each type. While most of thet types are html-related, `plaintext` and `markdown` are the two that need specific handling (or opting out of). 25 | 26 | ## Examples 27 | 28 | 1. A plugin expands anchors in the post body into dynamic link previews. It would not make sense to send the complicated HTML (with classes, tables, etc.) to other servers, and there is no markdown equivalent. 29 | 30 | The plugin should listen and act only for the `default`, and do nothing otherwise. 31 | 32 | 1. A plugin looks for bbcode and converts it to html. Sending simple html to other servers is fine. 33 | 34 | The plugin should execute alternative logic specifically to `plaintext` (excise the bbcode tags) and `markdown` (optionally convert to markdown equivalent), and act normally otherwise. -------------------------------------------------------------------------------- /src/docs/activitypub/fep/1b12.md: -------------------------------------------------------------------------------- 1 | # 1b12: Group Federation 2 | 3 | NodeBB has elected to follow FEP 1b12 for Group Federation. Nomenclature-wise, the term "group" here refers to the content submitted by a collection of users, represented by the [`Group` Actor Type](https://www.w3.org/TR/activitystreams-vocabulary/#actor-types). 4 | 5 | The proposal explicitly mentions "internet forums", and this concept is most analogous to both user groups and categories in NodeBB. In NodeBB, FEP 1b12 is implemented for **categories only**. 6 | 7 | ## Our implementation 8 | 9 | Each category in NodeBB is potentially able to federate content outward to the fediverse. They identify themselves as `Group` actors, and can maintain follow relationships with other actors/remote-users. 10 | 11 | Additionally, NodeBB categories can follow other `Group` actors. This special handling was created in order for categories across disparate forums (e.g. separate NodeBB instances, or even other AP-enabled forum software) to synchronize their content with each other. 12 | 13 | ### The `audience` 14 | 15 | NodeBB sets the `audience` property to the NodeBB category that houses a particular post. While the FEP was written with the expectation that the `audience` is one order higher than the post, in forums, the `audience` is actually the second-order parent, with the first-order parent being the topic, which is expressed in `context` (see [FEP 7888](./7888.md).) 16 | 17 | ### The handle 18 | 19 | Each category is given a handle that can be used to reference it locally or remotely. Like users and user groups, they must be unique, and the default is a "slugified" variant of the category name (e.g. "Category About Cats" would have the default handle `category-about-cats`.) 20 | 21 | ### The announce 22 | 23 | Whenever a user (local to the forum or remotely) posts content (new topic or reply), that category will federate an `Announce` activity to its followers, for that new post. This is analogous to an internet "share", and allows posted content to be more widely consumed by relevant parties. 24 | 25 | There is no `Announce` federation for the [Uncategorized category](../../development/plugins/uncategorized.md). 26 | 27 | ## Direct address 28 | 29 | Remote users may post new topics to a category by directly addressing their handle. In the contrived example above, a user may elect to post a new `Note` to `@category-about-cats@example.org`, and the category will capture that post and automatically slot it in the category. -------------------------------------------------------------------------------- /src/docs/configuring/databases/redis.md: -------------------------------------------------------------------------------- 1 | # Using Redis as a data store 2 | 3 | NodeBB defaults to using MongoDB as its primary data store, although we also support Redis. Both Redis and MongoDB are considered data stores with first-class support in NodeBB, so if you experience bugs using the Redis as your data store instead of MongoDB, we still encourage you to [file an issue](https://github.com/NodeBB/NodeBB/issues/new). 4 | 5 | Redis may be useful in some high-scalability scenarios due to its design which keeps the entirety of the database in active memory. This strategy allows lookups to be very very fast, and compared to MongoDB, you may see some non-insignificant increase in speed. 6 | 7 | However, this advantage is a double-edged sword. As Redis keeps the entire database in active memory, it means that your system memory needs to be twice as large (if not more) than your dataset (i.e. 2gb of data will require a system with at least 4gb). Redis requires twice the memory (compared to its data set) as its backup strategy consists of cloning the in-memory data before persisting it to disk. 8 | 9 | Consider your hardware options carefully and see whether the trade-off is worth it for your installation. Keep in mind that the NodeBB team maintains a Redis-to-MongoDB migration service for those that need it. For more information, reach out to sales@nodebb.org. 10 | 11 | ## Step 1: Install Redis 12 | 13 | Install Redis according to the instructions of whatever package manager you use. In Ubuntu/Debian, you can use `apt`: 14 | 15 | ``` 16 | // as root user 17 | add-apt-repository ppa:chris-lea/redis-server 18 | apt-get update 19 | apt-get install -y redis-server 20 | ``` 21 | 22 | ## Step 2: NodeBB Installation 23 | 24 | During the setup phase of NodeBB, you will be asked a series of questions related to your database. When asked which data store to use, enter `redis`. 25 | 26 | * Host IP or address of your Redis instance 27 | * `127.0.0.1` or `localhost` will work for local installations 28 | * Host port of your Redis instance 29 | * By default, Redis listens on port `6379`. If you changed it in `/etc/redis.conf`, adjust it here as well 30 | * Password of your Redis database 31 | * Enter the password you set up in `/etc/redis.conf`. If you didn't change that file, chances are there is no password, and you can leave it blank. We do suggest you set up a password. 32 | * Which database to use (0..n) 33 | * Redis defaults to 16 databases, numbered from 0 to 15. You can choose any of those numbers. -------------------------------------------------------------------------------- /src/docs/activitypub/context.md: -------------------------------------------------------------------------------- 1 | # Conversational Contexts 2 | 3 | ActivityPub supports a number of different activity types, such as [`Question`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-question), [`Listen`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-listen), etc. The most common type of activity encountered is the [`Create`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-create), which is typically paired with the [`Note`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-note) object. 4 | 5 | All of these activities and objects theoretically could relate to one another, and through these relationships we can build a _conversational context_ (herein referred to as "context"). 6 | 7 | In NodeBB, these conversational contexts are easily represented as **topics**, which house **posts**. 8 | 9 | There are several ways that NodeBB can build a context, listed here in order of preference. 10 | 11 | ## Resolvable context resolution 12 | 13 | [FEP 7888](./fep/7888.md) outlines a set of normative guidances for use of the context property. Specifically, it details the use of the `context` property and how it is a resolvable URL that returns a `Collection`. 14 | 15 | When NodeBB encounters an object that refers to a `context`, it will attempt first to resolve the context. If the resolved context contains objects, then all of those objects are parsed and organized into a topic. 16 | 17 | [This issue](https://github.com/NodeBB/NodeBB/issues/12695) ([related discussion](https://community.nodebb.org/topic/18184/the-current-state-of-context-resolution)) further outlines the capability of NodeBB to provide and parse a synchronization header so that ActivityPub implementors can easily determine whether their context is up-to-date without needing to traverse all pages of the context collection. 18 | 19 | ## Reply chain traversal 20 | 21 | Most of the other software that NodeBB can communicate with attaches the [`inReplyTo`](https://www.w3.org/TR/activitystreams-vocabulary/#dfn-inreplyto) property, which allows for one or more references to be considered a "parent". 22 | 23 | If a resolvable context (see above) cannot be found, then NodeBB will fall back to traversing up this reply chain to the root node, in order to build a context. This chain of objects would then be parsed and organized into a topic. 24 | 25 | ### Deficiencies 26 | 27 | 1. If one of the objects in the chain no longer resolves (either temporarily or permanently), then the chain is broken, and the root node is unreachable. 28 | 1. Reply chain traversal allows you to build a direct line of replies to the root node, but by design omits every other branch of a reply tree. It will almost never represent the entire context. -------------------------------------------------------------------------------- /src/compile.js: -------------------------------------------------------------------------------- 1 | 'use strict'; 2 | 3 | const fs = require('fs'); 4 | const path = require('path'); 5 | const klaw = require('klaw-sync'); 6 | const mkdirp = require('mkdirp').sync; 7 | 8 | const cache = {}; 9 | 10 | function get(obj, path) { 11 | path = path.split('.'); 12 | 13 | for (let i = 0; (i < path.length) && obj; i += 1) { 14 | const key = path[i]; 15 | obj = obj[key]; 16 | } 17 | 18 | return obj || 'NOT FOUND'; 19 | } 20 | 21 | function set(obj, path, value) { 22 | path = path.split(/[\/\\]/); 23 | 24 | const lastKey = path.pop(); 25 | 26 | for (let i = 0; i < path.length; i += 1) { 27 | const key = path[i]; 28 | obj = obj[key] = obj[key] || {}; 29 | } 30 | 31 | obj[lastKey] = value; 32 | } 33 | 34 | const pattern = /{{([^}]*)}}/g; 35 | function parse(template, data) { 36 | const output = template.replace(pattern, (whole, identifier) => get(data, identifier)); 37 | return pattern.test(output) ? parse(output, data) : output; 38 | } 39 | 40 | // basePath is something like 'installing/os/ubuntu' 41 | function prepareData(basePath) { 42 | const base = path.join(__dirname, 'templates', basePath); 43 | 44 | const files = klaw(base, { 45 | nodir: true, 46 | }); 47 | 48 | const data = {}; 49 | files.forEach(file => { 50 | const p = path.relative(base, file.path.replace(/\..*$/, '')); 51 | const val = fs.readFileSync(file.path, 'utf8'); 52 | 53 | set(data, p, val); 54 | }); 55 | 56 | const directories = path.resolve(base).split(path.sep); 57 | 58 | const indexData = directories.reduce((prev, dir, i) => { 59 | try { 60 | const p = path.join('/', ...directories.slice(0, i + 1)); 61 | const d = require(p); 62 | 63 | return Object.assign({}, prev, d); 64 | } catch (e) { 65 | return prev; 66 | } 67 | }, {}); 68 | 69 | const all = Object.assign({}, indexData, data); 70 | 71 | return all; 72 | } 73 | 74 | const categories = [ 75 | 'installing/os', 76 | ]; 77 | 78 | function compileAll() { 79 | categories.forEach((categoryPath) => { 80 | const baseTemplate = fs.readFileSync(path.join(__dirname, 'templates', categoryPath, 'template.md'), 'utf8'); 81 | 82 | const entries = fs.readdirSync(path.join(__dirname, 'templates', categoryPath)); 83 | entries.filter(p => fs.statSync(path.join(__dirname, 'templates', categoryPath, p)).isDirectory()).forEach(entry => { 84 | const data = prepareData(path.join(categoryPath, entry)); 85 | const output = parse(baseTemplate, data); 86 | 87 | const filePath = path.join(__dirname, '../docs', categoryPath, entry + '.md'); 88 | mkdirp(path.dirname(filePath)); 89 | fs.writeFileSync(filePath, output); 90 | }); 91 | }); 92 | } 93 | 94 | compileAll(); 95 | -------------------------------------------------------------------------------- /src/docs/index.md: -------------------------------------------------------------------------------- 1 | ![NodeBB](images/nodebb.svg) 2 | 3 | # Welcome! 4 | 5 | Welcome to the documentation portal for **NodeBB**. 6 | 7 | **NodeBB** is a next-generation discussion platform that utilizes web sockets for instant interactions and real-time notifications. NodeBB forums have many modern features out of the box such as social network integration and streaming discussions, as well as a full REST API and plugin framework for full third-party extensibility. 8 | 9 | NodeBB is an open source project which can be forked on [GitHub](https://github.com/NodeBB/NodeBB/). If there are any discrepancies in the documentation please feel free to submit a [pull request](https://github.com/NodeBB/docs) or raise an issue on our [issue tracker](https://github.com/NodeBB/docs/issues). 10 | 11 | ## Contributing to the documentation 12 | 13 | The source code for the documentation portal is found in the [GitHub repository](https://github.com/NodeBB/docs). If you wish to add pages or make changes, please feel free to submit a pull request! All changes are welcome :) 14 | 15 | ## Helping out the NodeBB Project 16 | 17 | NodeBB is an open source project, and will forever remain free. Here's a 18 | number of ways you can help us, even if you aren't a programmer. 19 | 20 | - Join our [community](https://community.nodebb.org) and give us a hard time about bugs and missing features 21 | - [Like and share our content on Facebook](http://www.facebook.com/NodeBB) 22 | - [Follow us on X (Twitter)](https://x.com/NodeBB) and perhaps POST (tweet) **\#NodeBB is the most awesome forum software @NodeBB** 23 | - Tell everybody about NodeBB, including your grandma and her cats. 24 | - [Submit a pull request, or two, or three..](https://www.github.com/NodeBB/NodeBB) 25 | - Build a new theme 26 | - Write a plugin 27 | - Keep the link back to us on the footer of your own NodeBB :) 28 | - Blog about us! Give the gift of SEO juice this Christmas 29 | - [Help Translate NodeBB](https://explore.transifex.com/nodebb/nodebb/) - It's a really simple translation tool and you don't need to know how to code. 30 | 31 | ## Translating NodeBB to another language 32 | 33 | NodeBB uses Transifex, which is a user friendly visual tool which allows any individual to translate text into a language of their choice. You don't need to be a programmer to do this, so what are you waiting for? [Join the translation team](https://explore.transifex.com/nodebb/nodebb/) now :) 34 | 35 | ## Enterprise/Corporate customizations 36 | 37 | NodeBB Inc., the custodian of the NodeBB open-source project, is available for consultation and/or contract work for all NodeBB-related projects. Inquire with us [by sending us a message](//nodebb.org/contact), or by emailing us at sales [at] nodebb [dot] org. 38 | -------------------------------------------------------------------------------- /src/docs/installing/cloud/heroku.md: -------------------------------------------------------------------------------- 1 | Heroku 2 | ====== 3 | 4 | **Note**: Installations to Heroku require a local machine with some 5 | flavour of unix, as NodeBB does not run on Windows. 6 | 7 | 1. Download and install [Heroku Toolbelt](https://toolbelt.heroku.com/) 8 | for your operating system 9 | 1. Log into your Heroku account: `heroku login` 10 | 1. Verify your Heroku account by adding a credit card (at 11 | ). *Required for enabling mLab MongoDB Add-on.* 12 | 1. Clone the repository: 13 | `git clone -b v2.x https://github.com/NodeBB/NodeBB.git /path/to/repo/clone` 14 | 1. `cd /path/to/repo/clone` 15 | 1. Create the heroku app: `heroku create` 16 | 1. Enable [mLab MongoDB](https://elements.heroku.com/addons/mongolab) 17 | for your heroku account ([Sandbox](https://elements.heroku.com/addons/mongolab#sandbox) 18 | is a free plan): `heroku addons:create mongolab:sandbox` 19 | 1. Run the NodeBB setup script: `./nodebb setup` (information for 20 | your Heroku server and mLab MongoDB instance can be found in your 21 | account page) 22 | 23 | > - Your server name is found in your Heroku app's "settings" 24 | > page, and looks something like 25 | > `https://adjective-noun-wxyz.herokuapp.com` 26 | > - Use any port number. It will be ignored. 27 | > - Your MongoDB server can be found as part of the mongoDB url. For 28 | > example, for the url: 29 | > `mongodb://heroku_b5mwv5hk:8i0hd53a35qhd7bd2p8lm0m4do@ds151291.mlab.com:61391/heroku_b5mwv5hk` 30 | > - The host is `ds151291.mlab.com` 31 | > - The port is `61391` 32 | > - The username is `heroku_b5mwv5hk` 33 | > - The password is `8i0hd53a35qhd7bd2p8lm0m4do` 34 | 35 | 1. Create a Procfile for Heroku: 36 | `echo "web: node loader.js --no-daemon" > Procfile` 37 | 1. Commit the Procfile: 38 | 39 | ``` 40 | git add -f Procfile config.json package.json build && git commit -am "adding Procfile and configs for Heroku" 41 | ``` 42 | 43 | 1. Push to heroku: `git push -u heroku v2.x:master` 44 | * Ensure that a proper SSH key was added to your account, otherwise the push will not succeed! 45 | 1. Initialise a single dyno: `heroku ps:scale web=1` 46 | 1. Visit your app! 47 | 48 | If these instructions are unclear or if you run into trouble, please let 49 | us know by creating a topic on the [Community Support 50 | Forum](https://community.nodebb.org). 51 | 52 | Keeping it up to date 53 | --------------------- 54 | 55 | If you wish to pull the latest changes from the git repository to your 56 | Heroku app: 57 | 58 | 1. Navigate to your repository at `/path/to/nodebb` 59 | 1. `git pull` 60 | 1. `npm install` 61 | 1. `node app --upgrade` 62 | 1. `git commit -am "upgrading to latest nodebb"` 63 | 1. `git push` 64 | 65 | Upload Support 66 | -------------- 67 | Given the Heroku doesn't uses a persistant storage, to avoid losing uploaded assets, remember to follow the solution in [Uploads](https://docs.nodebb.org/admin/uploads/) to setup a persistant storage. 68 | -------------------------------------------------------------------------------- /src/docs/activitypub/discovery.md: -------------------------------------------------------------------------------- 1 | # Content Discovery 2 | 3 | A forum that can communicate over ActivityPub can theoretically communicate with a wider universe of content (also known as the _fediverse_). 4 | 5 | However, new entrants to the fediverse often remark that it is "quiet", or that they are not receiving content. This is by design, and is one of the trademarks that sets the fediverse apart from centralized social media platforms like Facebook, X, etc. 6 | 7 | Considering that — as of writing — there are over 8 billion people in the world, if we were to see every piece of content shared by everybody, you would be very much overwhelmed! Finding out how to tame that firehose is a problem that many social networks attempt to tackle. 8 | 9 | Many incumbent social networks take that incoming stream of content (or "firehose") and parse it for sentiment and association. It uses that information against their own collective knowledge of you as a person to serve you content you want to view. It is a very effective strategy, but one that is very resource intensive and privacy invading. 10 | 11 | ActivityPub by-design encourages a relationship-based spread of content. You need to follow other people in order to receive their content, and other people need to follow you in order to receive your content. 12 | 13 | The best analogy is a chain of islands, each island representing a separate website. Each website can build bridges (ActvityPub) with other islands, and they become connected. New installations do not have any known associations, and so its reach is limited. You are an island with no bridges yet! 14 | 15 | There are a couple of tried-and-true methods to build these connections. 16 | 17 | ## Follow often and follow lots 18 | 19 | As indicated prior, ActivityPub is built upon the follow relationships of its users. Therefore if you want to see lots of content, follow people that interest you in order to see more content from them. 20 | 21 | In addition to seeing their content, following a user also exposes you to content **shared** by that followed user, meaning that a *linear* increase in follow relationships may expose you to *exponentially* more content. 22 | 23 | ## Manual content discovery 24 | 25 | If you discover content on another site that you would like to interact with, you can instruct NodeBB to *pull* that content in. 26 | 27 | Take the URL of the piece of content and paste it into the NodeBB search bar. NodeBB will then attempt to pull it in using ActivityPub and generate a topic and automatically slot in into [Uncategorized](../development/plugins/uncategorized.md). 28 | 29 | From there, you can reply, upvote, etc. — you can also move that topic to one of your local categories. 30 | 31 | ## Relays 32 | 33 | **NodeBB does not support relays at this time**. 34 | 35 | Some fediverse software can be set up so that there is a two-way exchange of all known content, even if there is no specific user-follow relation between them. This setup allows for a forum to be quickly connected to a larger network, but does not guarantee the quality of the incoming content. -------------------------------------------------------------------------------- /src/docs/development/plugins/statics.md: -------------------------------------------------------------------------------- 1 | # Static Directories 2 | 3 | NodeBB allows plugins to configure static directories, which will allow the direct access of files from the browser. This can be useful for serving up assets as part of your plugin; e.g. 4 | 5 | > A NodeBB plugin allows users to earn trophies based on forum participation. These trophies are represented as PNG images that can be seen in their profile page. 6 | > 7 | > A static directory needs to be set up so that they can be linked to directly in a browser `` tag. 8 | 9 | ## Security Considerations 10 | 11 | A static directory when configured per below is not secured from public access. That lack of authentication means that any user (guest, bot, or otherwise) will be able to access files within the mounted directory, thus potentially exposing them to search engines, etc. 12 | 13 | Be sure not to place private items in static directories unless they are protected behind another authentication mechanism (e.g. [Basic/Digest authentication via nginx](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/)). 14 | 15 | Alternatively, instead of using a static directory, you can mount a controller to a route via the `static:api.routes` hook, do any checks and validation as necessary, and [use `res.sendFile`](http://expressjs.com/en/api.html#res.sendFile). 16 | 17 | ## Mounting a static directory 18 | 19 | ### In core 20 | 21 | In core itself, NodeBB exposes two directories: 22 | 23 | 1. **`/build/public`** which is cleared and generated whenever `./nodebb build` is executed (do not use this) 24 | 1. **`/public`** which contains various assets used by NodeBB (default images, language files, etc.) 25 | * **`/public/uploads`** is the only directory here that is **not** version tracked, so it is recommended to add items here. 26 | 27 | Both of these directories are served under the common prefix `/assets` (the former takes precedence over the latter.) For example, to load the default favicon located at `/public/favicon.ico`, you can browse to `/assets/favicon.ico` via the browser. 28 | 29 | ### via plugins 30 | 31 | Plugins can define a static directory using the `staticDirs` property of [the `plugin.json` file](./plugin.json.md). 32 | 33 | You can define an object literal containing a key-value map of directory names and their paths (relative to the plugin directory). 34 | 35 | When plugins define static directories, they are all mounted behind the prefix `plugins/{YOUR-PLUGIN-ID}`. 36 | 37 | Given the following: 38 | 39 | * If NodeBB is installed at `/var/www/nodebb`, and 40 | * It is reachable at `https://example.org`, and 41 | * A plugin when installed would be found at `/var/www/nodebb/node_modules/nodebb-plugin-example` 42 | 43 | You can define a static directory thusly: 44 | 45 | ``` json 46 | { 47 | ... 48 | "staticDirs": { 49 | "images": "images" 50 | } 51 | ... 52 | } 53 | ``` 54 | 55 | This configuration will instruct NodeBB to mount the path `/var/www/nodebb/node_modules/nodebb-plugin-example/images` onto `https://example.org/plugins/nodebb-plugin-example/images`, and all files inside can be directly accessed. -------------------------------------------------------------------------------- /src/docs/installing/cloud/cloud9.md: -------------------------------------------------------------------------------- 1 | Cloud 9 IDE 2 | =========== 3 | 4 | The following are installation instructions for the [Cloud 5 | 9](https://c9.io/) web based IDE. 6 | 7 | **Step 1:** Clone NodeBB into a new workspace from GitHub. You can use 8 | the following command from the terminal: 9 | 10 | ``` 11 | git clone -b v2.x https://github.com/NodeBB/NodeBB.git nodebb 12 | ``` 13 | 14 | The nodebb command after the git url will create a folder called nodebb 15 | so you have to `cd` into that directory after you have cloned NodeBB. 16 | 17 | **Step 2:** Install redis with Cloud9's package manager 18 | 19 | ``` 20 | nada-nix install redis 21 | ``` 22 | 23 | **Step 3:** Run your redis server on port 16379 - port 6379 tends to be 24 | already used on Cloud 9. The "&" makes the command run in the 25 | background. You can always terminate the process later. \$IP is a Cloud 26 | 9 system variable containing the global ip of your server instance. 27 | 28 | ``` 29 | redis-server --port 16379 --bind $IP & 30 | ``` 31 | 32 | **Step 4:** Find out your instance's ip address so NodeBB can bind to it 33 | correctly. This is one of Cloud 9's demands and seems to be the only way 34 | it will work. You can't use \$IP in your config.json either (which means 35 | you can't enter \$IP in the node app --setup). 36 | 37 | ``` 38 | echo $IP 39 | ``` 40 | 41 | **Step 5:** Run the nodebb setup utility: 42 | 43 | ``` 44 | node app --setup 45 | ``` 46 | 47 | URL of this installation should be set to 48 | '', replacing workspace\_name 49 | with your workspace name and username with your username. Note that as 50 | NodeBB is currently using unsecure http for loading jQuery you will find 51 | it much easier using instead of for your base url. 52 | Otherwise jQuery won't load and NodeBB will break. 53 | 54 | Port number isn't so important - Cloud9 may force you to use port 80 55 | anyway. Just set it to 80. If this is another port, like 4567, that is 56 | also fine. 57 | 58 | Use a port number to access NodeBB? Again, this doesn't seem to make a 59 | big difference. Set this to no. Either will work. 60 | 61 | Host IP or address of your Redis instance: localhost (the output of the 62 | \$IP Command is also acceptable) 63 | 64 | IP or Hostname to bind to: Enter what your \$IP value holds here found 65 | in step 4. It should look something like: 123.4.567.8 66 | 67 | Host port of your Redis instance: 16379 68 | 69 | Redis Password: Unless you have set one manually, Redis will be 70 | configured without a password. Leave this blank and press enter 71 | 72 | First-time set-up will also require an Admin name, email address and 73 | password to be set. 74 | 75 | And you're good to go! Don't use the Run button at the top if the IDE, 76 | it has been a little buggy for me. Besides, you're better off using the 77 | command line anyway. Run: 78 | 79 | ``` 80 | node app 81 | ``` 82 | 83 | And then open in your browser. 84 | 85 | Troubleshooting 86 | --------------- 87 | 88 | A common problem is that the database hasn't been started. Make sure you 89 | have set Redis up correctly and ran 90 | 91 | ``` 92 | redis-server --port 16379 --bind $IP 93 | ``` 94 | -------------------------------------------------------------------------------- /src/docs/installing/os/fedora.md: -------------------------------------------------------------------------------- 1 | Fedora 33+ 2 | ========== 3 | 4 | *This was tested on Fedora 33. It will likely work on slightly older or newer verisons, with zero changes.* 5 | 6 | Fedora does not natively support MongoDB because of the license. Therefore, this guide will use PostgreSQL. 7 | 8 | 9 | First you need to make sure that Fedora is up to date, you can do so using 10 | this command: 11 | 12 | ``` 13 | dnf upgrade -y --refresh 14 | ``` 15 | 16 | Now, you install the base software stack: 17 | 18 | ``` 19 | dnf install -y git nodejs postgresql-server policycoreutils-python-utils 20 | ``` 21 | 22 | Initialize the PostgreSQL database 23 | 24 | ``` 25 | /usr/bin/postgresql-setup initdb 26 | ``` 27 | 28 | Enable and start the database 29 | 30 | ``` 31 | systemctl enable --now postgresql 32 | ``` 33 | 34 | Update the firewall to allow the needed connections 35 | 36 | ``` 37 | firewall-cmd --add-port=4567/tcp --permanent 38 | firewall-cmd --reload 39 | ``` 40 | 41 | Tell SELinux to allow the webserver to connect to the local network 42 | 43 | ``` 44 | setsebool -P httpd_can_network_connect on 45 | ``` 46 | 47 | Create user and database to be used by NodeBB 48 | * This spews an error about changing directories, but still creates. 49 | 50 | ``` 51 | sudo -u postgres psql -c "create user nbbuser with encrypted password 'SomeLongPasswordForTheUser'" 52 | sudo -u postgres psql -c "create database nodebbdb" 53 | sudo -u postgres psql -c "grant all privileges on database nodebbdb to nbbuser" 54 | ``` 55 | 56 | Set a password for the admin user (postgres) 57 | 58 | ``` 59 | sudo -u postgres psql -c "alter user postgres with password 'SomeLongPasswordForTheRootUser'" 60 | ``` 61 | 62 | Update PostgreSQL to use database user login information. 63 | 64 | ``` 65 | sed -i 's/ident$/md5/g' /var/lib/pgsql/data/pg_hba.conf 66 | ``` 67 | 68 | Restart PostgreSQL 69 | 70 | ``` 71 | systemctl restart postgresql 72 | ``` 73 | 74 | Create application directory. 75 | 76 | ``` 77 | mkdir -p /opt/nodebb 78 | ``` 79 | 80 | Next, clone the NodeBB repository: 81 | * As of the creation of this guide, the current branch is v2.x 82 | * Update accordingly 83 | 84 | ``` 85 | git clone -b v2.x https://github.com/NodeBB/NodeBB /opt/nodebb 86 | ``` 87 | 88 | \*\*Note: To clone the master branch you can use the same command with 89 | out the "-b v2.x" option. 90 | 91 | 92 | It is bad practice to run NodeBB as a privileged user, so create a user 93 | 94 | ``` 95 | adduser nodebb --system --create-home 96 | ``` 97 | 98 | Set ownership of the NodeBB folder to the user that will be running the application 99 | 100 | ``` 101 | chown -R nodebb:nodebb /opt/nodebb 102 | ``` 103 | 104 | Change directory and then initiate the setup script by running the app as the nodebb user with the `setup` flag: 105 | 106 | ``` 107 | cd /opt/nodebb 108 | sudo -u nodebb ./nodebb setup 109 | ``` 110 | 111 | The wizards will ask what database to use, make sure you specify `postgres` and then use the same information as used above when the database was created. 112 | 113 | Lastly, we run the forum, again as the nodebb user. 114 | 115 | ``` 116 | sudo -u nodebb ./nodebb start 117 | ``` 118 | 119 | NodeBB can also be started with helper programs, such as `forever`. 120 | Take a look at the options [here](../../configuring/running.md). 121 | 122 | -------------------------------------------------------------------------------- /src/docs/activitypub/visibility.md: -------------------------------------------------------------------------------- 1 | # Public and Private Visibility 2 | 3 | ActivityPub has a concept of _addressing_ that is similar to email. There are recipients that activities are sent `to`, and additional recipients can be added in `cc`. 4 | 5 | There is also the concept of a "public address" that, when included, signifies that the activity and its object therein is to be considered public. **By and large**, almost all content sent via ActivityPub is considered public. 6 | 7 | ## Public content 8 | 9 | When public content is received by NodeBB, **it is parsed into a post object**, and slotted into an existing topic if available, creating a new topic if not. 10 | 11 | NodeBB will attempt to backfill a topic with additional replies if available, and will attempt to traverse up the reply chain otherwise. 12 | 13 | If a specific category is mentioned, then the topic will be slotted in that category. Otherwise, it will be [uncategorized](../development/plugins/uncategorized.md) but can be moved at-will by administrators. 14 | 15 | ## Private content 16 | 17 | If the public address is not present in the recipients list, then **NodeBB will parse it into a chat message**, and add it to a room if available, creating a new chat room if not. 18 | 19 | When a new chat room is created, its recipients are the individuals addressed in the received activity. Those users are added to the chat room as though they were in the chat. 20 | 21 | When messages are sent in that chat room, they are automatically federated out to the members of the chat room. The visibility scope is limited to that of the chat room membership. 22 | 23 | For example; 24 | 25 | > Alice (@alice@example.org) sends Bob (@bob on NodeBB) a message. As it is not in reply to another message, a new chat room is created that contains both Alice and Bob. 26 | 27 | > Bob sends Alice a reply to her message. It is federated out to Alice only. 28 | 29 | ### Broader scope 30 | 31 | When additional members are found in the recipents of a message, they are automatically added to the chat room. New users when added to a chat room are not able to view the existing history of the room, so their view of the conversation begins when they are added. 32 | 33 | > Alice (@alice@example.org) replies to Bob (@bob on NodeBB) and also includes Charles (@charles@example.com) in the recipients list. Charles is added to the existing chat room containing Alice and Bob. 34 | 35 | ### Narrower scope 36 | 37 | If a message is received that is addressed to *fewer* recipients, then a new chat is created for security, as the recipients list has changed. 38 | 39 | > Charles (@charles@example.com) replies to the earlier message, but addresses the reply only to Bob (@bob on NodeBB). A new chat room is created that contains only Charles and Bob. Future messages in that chat room will not include Alice in the recipients list. 40 | 41 | ## Additional visibility patterns 42 | 43 | Other ActivityPub implementors further divide their visibility levels based on recipient ordering and/or inclusion of the public address in `to` vs `cc`; e.g. 44 | 45 | * A message addressed to the public address in `cc` is "unlisted" or "quiet public" 46 | * A message addressed to a follower collection is only sent to the followers of a specific user. 47 | 48 | NodeBB does not differentiate between these separate states. Follower collections are ignored, and unlisted/quiet objects are considered fully public posts in NodeBB. -------------------------------------------------------------------------------- /src/docs/development/plugins/plugin.json.md: -------------------------------------------------------------------------------- 1 | # `plugin.json` 2 | 3 | Each plugin package contains a configuration file called `plugin.json`. 4 | Here is a sample, keeping in mind that *not all options are required*: 5 | 6 | ``` json 7 | { 8 | "id": "nodebb-plugin-myplugin", 9 | "url": "Absolute URL to your plugin or a Github repository", 10 | "library": "./my-plugin.js", 11 | "staticDirs": { 12 | "images": "public/images" 13 | }, 14 | "scss": [ 15 | "assets/style.scss" 16 | ], 17 | "hooks": [ 18 | { "hook": "filter:post.save", "method": "filter" }, 19 | { "hook": "action:post.save", "method": "emailme" } 20 | ], 21 | "scripts": [ 22 | "public/src/client.js" 23 | ], 24 | "acpScripts": [ 25 | "public/src/admin.js" 26 | ], 27 | "modules": { 28 | "../client/myplugin.js": "./public/src/myplugin.js", 29 | "../admin/plugins/myplugin.js": "./public/src/admin.js" 30 | }, 31 | "upgrades": [ 32 | "upgrades/your_upgrade_script.js" 33 | ], 34 | "languages": "path/to/languages", 35 | "templates": "path/to/templates" 36 | } 37 | ``` 38 | 39 | `id` is a unique identifier for your plugin. NodeBB will refer to your plugin by this id, and if published to npm, NodeBB will try to download the package with the same name as this id. 40 | 41 | The `library` property is a relative path to the library in your 42 | package. It is automatically loaded by NodeBB (if the plugin is 43 | activated). 44 | 45 | The `staticDirs` property is an object hash that maps out paths 46 | (relative to your plugin's root) to a directory that NodeBB will expose 47 | to the public at the route `/plugins/{YOUR-PLUGIN-ID}`. 48 | 49 | * e.g. The `staticDirs` hash in the sample configuration maps `/path/to/your/plugin/public/images` to `/plugins/my-plugin/images` 50 | 51 | [More information about static directories can be found here](./statics.md). 52 | 53 | The `scss` property contains an array of paths (relative to your 54 | plugin's directory), that will be precompiled into the CSS served by 55 | NodeBB. 56 | 57 | The `hooks` property is an array containing objects that tell NodeBB 58 | which hooks are used by your plugin, and what method in your library to 59 | invoke when that hook is called. Each object contains the following 60 | properties (those with a \* are required): 61 | 62 | * `hook`, the name of the NodeBB hook 63 | * `method`, the method called in your plugin 64 | * `priority`, the relative priority of the method when it is 65 | eventually called (default: 10) 66 | 67 | The `scripts` property is an array containing files that will be 68 | compiled into the minified javascript payload served to users. 69 | 70 | The `acpScripts` property is similar to `scripts`, except these files 71 | are compiled into the minified payload served in the Admin Control Panel 72 | (ACP) 73 | 74 | The `modules` property allows you to embed third-party AMD-style scripts into your plugin. For more information, see 75 | [Using Third-Party Libraries](https://docs.nodebb.org/development/plugins/libraries/). 76 | 77 | The `upgrades` array is optional, useful for seamlessly updating your plugin's database 78 | schema via NodeBB's upgrade system. Have a look at this example in NodeBB's [dbsearch plugin](https://github.com/barisusakli/nodebb-plugin-dbsearch/blob/master/upgrades/dbsearch_change_mongodb_schema.js) for further details. 79 | 80 | The `languages` property is optional, which allows you to set up your 81 | own internationalization for your plugin (or theme). Set up a similar 82 | directory structure as core, for example: 83 | `language/en-GB/myplugin.json`. 84 | 85 | The `templates` property is optional, and allows you to define a folder 86 | that contains template files to be loaded into NodeBB. Set up a similar 87 | directory structure as core, for example: `partials/topic/post.tpl`. 88 | -------------------------------------------------------------------------------- /src/docs/development/index.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | We try to make working with NodeBB as seamless and open-ended as possible. 4 | 5 | NodeBB uses [benchpress](https://github.com/benchpressjs/benchpressjs) as its templating engine, [express](https://expressjs.org) on the backend to serve pages, and [webpack](https://webpack.js.org/) to bundle client side javascript. Of course, there are other dependencies, but these are the main ones that concern plugin developers. 6 | 7 | The easiest way to get started is by looking at the [Quickstart plugin](https://github.com/nodebb/nodebb-plugin-quickstart). This is a template repository, meaning you are not meant to install it on a NodeBB installation, but rather should fork it to serve as a base for your own plugin. 8 | 9 | Take a look at our [Quickstart plugin breakdown](./quickstart.md) for more details. 10 | 11 | ## Accessing page data 12 | 13 | Each page in NodeBB is rendered using json data. You can view this data by prepending `/api` to the url. For example if you are on the `/recent` page you can navigate to `/api/recent` to see the corresponding json data. When NodeBB is started in production mode the json output will not have any formatting so it will be hard to read, to prettify it you can add ?pretty=1 to the url. 14 | 15 | ## Asset building 16 | 17 | NodeBB requires a build step before it can run and serve pages to end users. This build process can be 18 | manually invoked by running `./nodebb build`. However, as the build process itself can take a long time 19 | depending on your particular computer specifications, there are other strategies to optimize the 20 | development process. The same strategies can be used if you are developing plugins and themes. 21 | 22 | ## Selective building of assets 23 | 24 | If you only need to build a specific part of NodeBB, `./nodebb build` can take space-separated arguments 25 | to limit its scope. 26 | 27 | For example, if you are making changes to your plugin's administrative pages, you can elect to build: 28 | 29 | ./nodebb build adminjs admincss tpl 30 | 31 | ... which would build only the ACP javascript, ACP stylesheets, and templates. 32 | 33 | The full list is can be found by running the following command: 34 | 35 | ```shell 36 | ./nodebb build -h 37 | ``` 38 | 39 | > If you're curious about the source, please refer to [this link](https://github.com/NodeBB/NodeBB/blob/c44ddb10e7ef5b822781e7e6b6e4859d5edc223d/src/meta/aliases.js#L6-L21) 40 | 41 | ## grunt 42 | 43 | For optimized development, the NodeBB team (and many of the plugin authors) use [Grunt](https://gruntjs.com/) 44 | as part of their workflow. The pre-requisite dependencies are installed with NodeBB during the `npm install` 45 | step, although you may need to install `grunt-cli` (or your distribution's appropriate package for grunt) 46 | to allow `grunt` to be called via the command line. 47 | 48 | Once installed, you can simply run `grunt` to build all assets and run NodeBB. Grunt will also watch for 49 | file changes and selectively build a subset of NodeBB's assets so there is no need to hop back to the 50 | console to stop NodeBB, build, and restart NodeBB. 51 | 52 | Alternatively, you can run `grunt --skip`, which skips the build step and simply runs NodeBB with file 53 | watching enabled. 54 | 55 | ## Testing 56 | 57 | In order to run tests on NodeBB, add the following block to your `config.json` file: 58 | 59 | ``` 60 | "test_database": { 61 | "host": "127.0.0.1", 62 | "port": "27017", 63 | "username": "", 64 | "password": "", 65 | "database": "test" 66 | } 67 | ``` 68 | 69 | Run the whole suite of tests via `npm test` or an individual file via `npx mocha test/your_test_file.js`. 70 | 71 | If you need to activate a certain plugin for testing as well, add the following block to your `config.json` file: 72 | 73 | ``` 74 | "test_plugins": [ 75 | "nodebb-plugin-xyz" 76 | ] 77 | ``` 78 | 79 | -------------------------------------------------------------------------------- /src/docs/development/quickstart.md: -------------------------------------------------------------------------------- 1 | # Quickstart plugin 2 | 3 | The [Quickstart plugin](https://github.com/nodebb/nodebb-plugin-quickstart) is a plugin skeleton that was created by the NodeBB team to serve as a fully-featured base to launch off from when creating custom plugins. 4 | 5 | It contains a minimal set of functionality, along with all of the necessary boiletplate to allow NodeBB to recognize it as a plugin. 6 | 7 | # Breakdown 8 | 9 | Cloning the repository and inspecing the files themselves can be overwhelming, so this guide has been created to guide you through the various aspects of the plugin. 10 | 11 | ## `plugin.json` 12 | 13 | → [View this file in GitHub](https://github.com/NodeBB/nodebb-plugin-quickstart/blob/master/plugin.json) 14 | 15 | Our first stop is is the `plugin.json` file, this plugin's main configuration area. NodeBB looks at this file to determine the plugin's name, hook listeners, and files. 16 | 17 | [Click here for a more detailed look at the file format and options](./plugins/plugin.json.md) 18 | 19 | `plugin.json` has an option called `library`, which is defined as `library.js`, let's look at that next. 20 | 21 | ## `library.js` 22 | 23 | → [View this file in GitHub](https://github.com/NodeBB/nodebb-plugin-quickstart/blob/master/library.js) 24 | 25 | The main bulk of the code is contained here, although additional logic is separated out into additional files in `lib/` (e.g. `lib/controllers.js`.) 26 | 27 | Each hook that is defined in `plugin.json` is mapped to an exported method in this file. 28 | 29 | For example, the `static:app.load` hook defined in `plugin.json` points to the `init` method. Whenever NodeBB starts, that hook is called, and by extension, this listener is called as well. 30 | 31 | In this particular hook, we set up some routes and mount them to the express router. 32 | 33 | You can discover additional hooks by inspecting the NodeBB database, or by [viewing the continually updated list of hooks](https://github.com/NodeBB/NodeBB/wiki/Hooks). 34 | 35 | For more information on [plugin hooks, click here](./plugins/hooks.md). 36 | 37 | ## Client-side logic 38 | 39 | The previous section detailed how a new route is created and mounted to the express router, but how would we define custom client-side logic? 40 | 41 | NodeBB uses [require.js](https://requirejs.org) to dynamically load modules on a page-by-page basis. 42 | 43 | The quickstart plugin mounted a route for the admin settings page, at `/admin/plugins/quickstart`. Inspecting the controller (found in `lib/controllers.js`) tells us that it attempts to load the template "`admin/plugins/quickstart`". This designation is important, as it tells us how NodeBB will look for the associated client-side module. 44 | 45 | No matter the mount point, NodeBB will attempt to `require` a client-side library based on the template name. In this case, navigating to the admin settings page will cause NodeBB to call `require('admin/plugins/quickstart')` and execute the `.init()` method, if one is available. Otherwise, it will do nothing. 46 | 47 | **Note**: Mounted pages that are **not** in the admin namespace are prefixed `forum/`. For example, if you have a mounted page `/foobar` that loads template `views/foobar`, NodeBB will attempt to call `require('forum/views/foobar')`. 48 | 49 | We can define a require.js module to NodeBB and specify its name, so that it is loaded when called directly. 50 | 51 | → [View this file in GitHub](https://github.com/NodeBB/nodebb-plugin-quickstart/blob/master/static/lib/admin.js) (`static/lib/admin.js`) 52 | 53 | This file starts off with a call to `define` with the module name (as discussed earlier) passed-in as the first argument. 54 | 55 | NodeBB looks for an exported `.init()` method, and executes it if found. 56 | 57 | There are two ways this file can be exposed to NodeBB: 58 | 59 | 1. It can be added to the `scripts` or `acpScripts` array in `plugin.json`, or 60 | 1. It can be defined as a custom module in the `modules` section of `plugin.json` 61 | 62 | ## Styling 63 | 64 | Styling is defined as a set of SASS files exposed to NodeBB via the `scss` array property in `plugin.json`. You can define and organize your SASS files as you wish. 65 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: NodeBB Documentation 2 | site_description: Documentation portal for NodeBB Forum Software 3 | theme: 4 | name: material 5 | logo: images/nodebb-light.svg 6 | features: 7 | - content.code.copy 8 | extra_css: 9 | - stylesheets/overrides.css 10 | repo_url: https://github.com/NodeBB/NodeBB 11 | edit_uri: https://github.com/NodeBB/docs/edit/master/src/docs/ 12 | markdown_extensions: 13 | - fenced_code 14 | - tables 15 | plugins: 16 | - search 17 | - social 18 | nav: 19 | - 'index.md' 20 | - Installation: 21 | - via OS: 22 | - 'installing/os/index.md' 23 | - 'Ubuntu (Recommended)': 'installing/os/ubuntu.md' 24 | - 'Arch Linux': 'installing/os/arch.md' 25 | - 'CentOS': 'installing/os/centos.md' 26 | - 'installing/os/debian.md' 27 | - 'installing/os/fedora.md' 28 | - 'FreeBSD/OpenBSD': 'installing/os/freebsd.md' 29 | - 'MacOS': 'installing/os/macOS.md' 30 | - 'installing/os/macos-bigsur.md' 31 | - 'SmartOS': 'installing/os/smartos.md' 32 | - 'Windows': 'installing/os/windows.md' 33 | - via the Cloud: 34 | - 'installing/cloud/index.md' 35 | - 'installing/cloud/cloud9.md' 36 | - 'installing/cloud/cloudron.md' 37 | - 'installing/cloud/docker.md' 38 | - 'installing/cloud/heroku.md' 39 | - 'installing/cloud/nitrous.md' 40 | - 'installing/cloud/openshift.md' 41 | - 'installing/cloud/elestio.md' 42 | - Configuration: 43 | - Running NodeBB: 'configuring/running.md' 44 | - config.json: 'configuring/config.md' 45 | - Databases: 46 | - 'configuring/databases/index.md' 47 | - MongoDB: 'configuring/databases/mongo.md' 48 | - Redis: 'configuring/databases/redis.md' 49 | - Proxies: 50 | - 'configuring/proxies/index.md' 51 | - Apache (v2.4+): 'configuring/proxies/apache.md' 52 | - Apache (v2.2): 'configuring/proxies/apache2.2.md' 53 | - Caddy: 'configuring/proxies/caddy.md' 54 | - NginX: 'configuring/proxies/nginx.md' 55 | - Node.js: 'configuring/proxies/node.md' 56 | - 'configuring/proxies/varnish.md' 57 | - Plugins: 58 | - 'configuring/plugins/index.md' 59 | - 'configuring/plugins/emailers.md' 60 | - 'configuring/plugins/search.md' 61 | - Upgrading: 'configuring/upgrade.md' 62 | - 'configuring/scaling.md' 63 | - Federation (v4): 64 | - FAQ: 'activitypub/index.md' 65 | - Pre-release Info: 'activitypub/prerelease.md' 66 | - 'activitypub/world.md' 67 | - 'activitypub/settings.md' 68 | - 'activitypub/privileges.md' 69 | - 'activitypub/discovery.md' 70 | - 'activitypub/context.md' 71 | - 'activitypub/visibility.md' 72 | - FEPs: 73 | - Overview: 'activitypub/fep/index.md' 74 | - 'activitypub/fep/1b12.md' 75 | - 'activitypub/fep/7888.md' 76 | - 'activitypub/fep/7458.md' 77 | - 'activitypub/fep/c0e0.md' 78 | - Development: 79 | - 'development/index.md' 80 | - 'development/quickstart.md' 81 | - Read API Reference 🔗: '/api/read' 82 | - Write API Reference 🔗: '/api/write' 83 | - Plugins: 84 | - 'development/plugins/index.md' 85 | - 'development/plugins/hooks.md' 86 | - 'development/plugins/libraries.md' 87 | - 'development/plugins/plugin.json.md' 88 | - 'development/plugins/statics.md' 89 | - 'development/plugins/parsing.md' 90 | - 'development/plugins/uncategorized.md' 91 | - Themes: 92 | - 'development/themes/index.md' 93 | - Templating System: 'development/themes/templates.md' 94 | - 'development/widgets.md' 95 | - 'development/database-structure.md' 96 | - Internationalisation (i18n): 'development/i18n.md' 97 | - Style Guide: 'development/style-guide.md' 98 | - Admin Panel: 99 | - 'admin/index.md' 100 | - 'admin/dashboard.md' 101 | - 'admin/uploads.md' 102 | - FAQ: 'faq.md' 103 | -------------------------------------------------------------------------------- /src/docs/development/widgets.md: -------------------------------------------------------------------------------- 1 | Writing Widgets for NodeBB 2 | ========================== 3 | 4 | See the original [blog post](http://blog.nodebb.org/widgets-system/) for 5 | a high level overview and screenshots of the widget system. 6 | 7 | Embedding HTML and JavaScript 8 | ----------------------------- 9 | 10 | You don't need to be a developer to figure this out. Head over to the 11 | Themes control panel and click on the Widgets tab. Create a new HTML 12 | widget by dragging and dropping the widget onto whatever template you 13 | want. 14 | 15 | Copy and paste HTML or JavaScript into the widget and hit save - you're 16 | done! 17 | 18 | You can optionally give your widget a container by dragging and dropping 19 | from the containers section onto your selected widget. 20 | 21 | If you're looking for some sample scripts, head over to our [plugins 22 | section](http://community.nodebb.org/category/7/nodebb-plugins) and look 23 | for any topic labelled `nodebb-script-xyz`. Don't forget to submit your 24 | scripts and ideas as well! 25 | 26 | Creating Widgets 27 | ---------------- 28 | 29 | You can define widgets in both plugins and themes. If you're building a 30 | plugin which simply delivers a widget (or collection of widgets), we 31 | strongly suggest you follow the `nodebb-widget-xyz` nomenclature instead 32 | when publishing. 33 | 34 | ### Registering your widget 35 | 36 | Listen to this hook to register your widget: 37 | 38 | ``` json 39 | "hook": "filter:widgets.getWidgets", "method": "defineWidgets" 40 | ``` 41 | 42 | Pass this back in the array: 43 | 44 | ``` json 45 | { 46 | widget: "widget_namespace", 47 | name: "My Widget", 48 | description: "Short description of what it does.", 49 | content: "" 50 | } 51 | ``` 52 | 53 | `Content` defines the form that is displayed to customize your widget in 54 | the admin panel. 55 | 56 | ### Listening to your widget 57 | 58 | NodeBB core will call your widget on the appropriate page load by way of 59 | the hooks system. The hook will be named after your widget's namespace 60 | (see previous example) - like so: 61 | `filter:widget.render:widget_namespace` 62 | 63 | This will pass in a `widget` object with the following useful properties: 64 | 65 | - `widget.area` - that defined by hook `filter:widgets.getAreas` (see 66 | section below) - will have `location`, `template`, `url` 67 | - `widget.data` - will have your admin-defined data; in the example from 68 | the previous section you will be exposed an `obj.data.myKey` 69 | - `widget.req` - [req object](https://expressjs.com/en/4x/api.html#req) 70 | represent current HTTP request. 71 | 72 | You render widget by assigning HTML to `widget.html`. For example: 73 | 74 | ```javascript 75 | Plugin.renderWidget = function (widget, callback) { 76 | widget.html = '

Hello world !

'; 77 | callback(null, widget); 78 | }; 79 | ``` 80 | 81 | Or you can render template file by `widget.req.app.render` ( 82 | see also [templating system](./themes/templates.md)). For example: 83 | 84 | ```javascript 85 | Plugin.renderWidget = async function (widget) { 86 | widget.html = await widget.req.app.renderAsync('widgets/my-widget'); 87 | return widget 88 | }; 89 | ``` 90 | 91 | Defining Widget Areas in Themes 92 | ------------------------------- 93 | 94 | A Widget Area is characterized by a template and a location. Themes can 95 | share widgets if they define the same Widget Areas. If an admin switches 96 | themes, widgets that were previously defined in a Widget Area 97 | incompatible with the new theme are saved. 98 | 99 | Listen to this hook to register your Widget Area: 100 | 101 | ``` json 102 | "hook": "filter:widgets.getAreas", "method": "defineWidgetAreas" 103 | ``` 104 | 105 | Pass this back in the array: 106 | 107 | ``` json 108 | { 109 | widget: "categorysidebar", 110 | name: "Category Sidebar", 111 | template: "category.tpl", 112 | location: "sidebar" 113 | } 114 | ``` 115 | 116 | And that's all. You can define as many Widget Areas in your theme as you 117 | wish. If you're still stuck, have a look at [this 118 | commit](https://github.com/NodeBB/nodebb-theme-cerulean/commit/50e49a9da5a89484fa8001bbda2e613b69f18e86) 119 | which upgraded the Cerulean theme to use the widget system. 120 | -------------------------------------------------------------------------------- /src/docs/images/nodebb-light.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | -------------------------------------------------------------------------------- /src/docs/development/themes/index.md: -------------------------------------------------------------------------------- 1 | Creating a new NodeBB Theme 2 | =========================== 3 | 4 | NodeBB is built on [Twitter Bootstrap](http://getbootstrap.com/), which 5 | makes theming incredibly simple. 6 | 7 | Quick start 8 | ----------- 9 | 10 | The easiest way to get started theming NodeBB is to fork the [Quickstart 11 | Theme](https://github.com/nodebb/nodebb-theme-quickstart) and adjust it 12 | for your customisations. 13 | 14 | The quickstart theme is a **child theme** (see below) of NodeBB's default 15 | theme (Harmony), and thus inherits all of its styling and templates from 16 | its parent theme. 17 | 18 | If you want to overwrite an existing template, copy it from [the Harmony 19 | repository](https://github.com/nodebb/nodebb-theme-harmony) into your 20 | theme's `/templates` directory, taking care to follow the same directory 21 | structure. You may have to create this directory. 22 | 23 | Then rebuild NodeBB's assets and your template should override Harmony's 24 | template of the same path. 25 | 26 | e.g. If you want to modify topic.tpl, you would: 27 | 28 | 1. Copy the contents of `nodebb-theme-harmony/templates/topic.tpl` 29 | 1. Create `nodebb-theme-mytheme/templates` 30 | 1. Create a new file `nodebb-theme-mytheme/templates/topic.tpl` with the contents of the original topic.tpl file 31 | 1. Make your changes as necessary. 32 | 1. `./nodebb build tpl && ./nodebb dev` to rebuild and start NodeBB 33 | 34 | Packaging for NodeBB 35 | -------------------- 36 | 37 | NodeBB expects any installed themes to be installed via `npm`. Each 38 | individual theme is an npm package, and users can install themes through 39 | the command line, ex.: 40 | 41 | ``` bash 42 | npm install nodebb-theme-modern-ui 43 | ``` 44 | 45 | The theme's folder must contain at least two files for it to be a valid 46 | theme: 47 | 48 | 1. `theme.json` 49 | 2. `theme.scss` 50 | 51 | `theme.scss` is where your theme's styles will reside. NodeBB expects 52 | SCSS to be present in this file, and will precompile it down to CSS 53 | on-demand. For more information regarding SCSS, take a look at [the 54 | project homepage](https://sass-lang.com/). 55 | 56 | **Note**: A *suggested* organization for `theme.scss` is to `@import` 57 | multiple smaller files instead of placing all of the styles in the main 58 | `theme.scss` file. 59 | 60 | Configuration 61 | ------------- 62 | 63 | The theme configuration file is a simple JSON string containing all 64 | appropriate meta data regarding the theme. Please take note of the 65 | following properties: 66 | 67 | - `id`: A unique id for a theme (e.g. "my-theme") 68 | - `name`: A user-friendly name for the theme (e.g. "My Theme") 69 | - `description`: A one/two line description about the theme (e.g. 70 | "This is the theme I made for my personal NodeBB") 71 | - `screenshot`: A filename (in the same folder) that is a preview 72 | image (ideally, 370x250, or an aspect ratio of 1.48:1) 73 | - `url`: A fully qualified URL linking back to the theme's 74 | homepage/project 75 | - `templates`: (Optional) A system path (relative to your plugin's 76 | root directory) to the folder containing template files. If not 77 | specified, NodeBB will search for the "templates" directory, and 78 | then simply fall back to using vanilla's template files. 79 | - `baseTheme`: (Optional) If undefined, will use nodebb-theme-persona 80 | (our current base theme) as a default for missing template files. 81 | See the Child Themes section for more details. 82 | 83 | Child Themes 84 | ------------ 85 | 86 | ### CSS / LESS 87 | 88 | If your theme is based off of another theme, simply modify your LESS 89 | files to point to the other theme as a base, ex for topics.less: 90 | 91 | As `topic.less` from the theme `nodebb-theme-vanilla` was imported, 92 | those styles are automatically incorporated into your theme. 93 | 94 | ### Templates 95 | 96 | You do not need to redefine all templates for your theme. If the 97 | template file does not exist in your current theme, NodeBB will inherit 98 | templates from the baseTheme that you have defined in your `theme.json` 99 | (or if undefined, it will inherit from `nodebb-theme-persona`'s 100 | templates). 101 | 102 | If your theme is dependent on a theme that is not nodebb-theme-vanilla, 103 | you should set the `baseTheme` configuration in your `theme.json` to the 104 | appropriate theme. 105 | 106 | For more information, please see the detailed article on [the templating system](./templates.md) 107 | -------------------------------------------------------------------------------- /src/docs/configuring/proxies/node.md: -------------------------------------------------------------------------------- 1 | Configuring a node.js reverse proxy 2 | ============================ 3 | 4 | In this tutorial we will create a reverse proxy https server complete 5 | with proxy rules, websockets, and TLS. This will allow multiple node 6 | applications to share the same domain, so that you can run NodeBB on a 7 | specific path (IE /forum) and another node application on another path. 8 | 9 | ## Requirements 10 | 11 | - NodeBB installation 12 | - Node.js v5.0 13 | - The following npm packages installed using the command: npm install PACKAGE\_NAME\_HERE --save 14 | - http-proxy-rules 15 | - express 16 | - http-proxy 17 | 18 | ### Include packages 19 | 20 | Create a node.js app with the following code 21 | 22 | ``` js 23 | var https = require('https'); 24 | var httpProxy = require('http-proxy'); 25 | var express = require('express'); 26 | var HttpProxyRules = require('http-proxy-rules'); 27 | ``` 28 | 29 | #### Define proxy rules and create proxy 30 | 31 | Change these proxy rules to suit your needs. These rules will determine 32 | where traffic is proxied to based on the url path. In this example we 33 | assume you have an instance of NodeBB running on the default port 34 | 35 | ``` js 36 | var proxyRules = new HttpProxyRules({ 37 | rules: { 38 | '.*/docs': 'http://localhost:8081', // Rule (1) docs, about, etc 39 | '.*/docs/*': 'http://localhost:8081', 40 | '.*/about': 'http://localhost:8081', 41 | '.*/press': 'http://localhost:8081', 42 | '.*/jobs': 'http://localhost:8081', 43 | '.*/developers': 'http://localhost:8081', 44 | 45 | '.*/forum': 'http://localhost:4567/forum', // Rule (2) forums 46 | '.*/forum/*': 'http://localhost:4567/forum', 47 | '/forum/*': 'http://localhost:4567/forum', 48 | './forum/*': 'http://localhost:4567/forum', 49 | '/forum': 'http://localhost:4567/forum' 50 | }, 51 | default: 'http://localhost:8081' // default target, will be landing page 52 | }); 53 | var proxy = httpProxy.createProxy(); 54 | ``` 55 | 56 | #### Change url in NodeBB config.json 57 | 58 | Suffix the path you set in the proxy rules onto the default NodeBB url 59 | in the config.json file in your NodeBB directory. In this example, the 60 | path was /forum, so the URL becomes: .. code:: javascript 61 | 62 | 63 | #### Create the web server and call the proxy 64 | 65 | First create the express.js app 66 | 67 | ``` js 68 | var express = require('express'); 69 | var bodyParser = require('body-parser') 70 | var mainapp = express(); 71 | mainapp.use(function(req,res,next){ 72 | try{ 73 | if (req.url.substr(0, 18).indexOf("socket.io")>-1){ 74 | //console.log("SOCKET.IO", req.url) 75 | return proxy.web(req, res, { target: 'wss://localhost:4567', ws: true }, function(e) { 76 | //console.log('PROXY ERR',e) 77 | }); 78 | } else { 79 | var target = proxyRules.match(req); 80 | if (target) { 81 | //console.log("TARGET", target, req.url) 82 | return proxy.web(req, res, { 83 | target: target 84 | }, function(e) { 85 | //console.log('PROXY ERR',e) 86 | }); 87 | } else { 88 | res.sendStatus(404); 89 | } 90 | } 91 | } catch(e){ 92 | res.sendStatus(500); 93 | } 94 | }); 95 | mainapp.use(bodyParser.json()); 96 | mainapp.use(bodyParser.urlencoded({ extended: false })); 97 | ``` 98 | 99 | Then put the code to start the web server, and put your HTTPS options in 100 | the options variable. (see node docs for more info about HTTPS) 101 | 102 | Change the port (4433) to your port. 103 | 104 | ``` js 105 | var options = {/*Put your TLS options here.*/}; 106 | 107 | var mainserver = https.createServer(options, mainapp); 108 | mainserver.listen(4433); 109 | mainserver.on('listening', onListening); 110 | mainserver.on('error', function (error, req, res) { 111 | var json; 112 | console.log('proxy error', error); 113 | if (!res.headersSent) { 114 | res.writeHead(500, { 'content-type': 'application/json' }); 115 | } 116 | 117 | json = { error: 'proxy_error', reason: error.message }; 118 | res.end(JSON.stringify(json)); 119 | }); 120 | ``` 121 | 122 | Thats it. Start up the proxy server, start up NodeBB, and start up your 123 | second server on port 8081 (or whichever port you chose) 124 | -------------------------------------------------------------------------------- /src/docs/activitypub/index.md: -------------------------------------------------------------------------------- 1 | ***Important Note**: Federation is currently only available in pre-release versions of NodeBB v4.* 2 | 3 | Technical details on enabling federation [can be found here](./prerelease.md). 4 | 5 | ---- 6 | 7 | `Availability: >4.0.0` 8 | 9 | "Federation", used in a technical sense, is the ability for a software to interact with others outside of its own domain. NodeBB is working towards federation in version 4 by adopting the ActivityPub protocol. 10 | 11 | ## What is ActivityPub? 12 | 13 | ActivityPub is a standardized protocol that allows software — like NodeBB — to communicate with other ActivityPub enabled software. This exchange could take place between two separate NodeBB instances, or even with non-forum software, such as microblogging networks, bookmarking apps, or image-based feed scrollers. 14 | 15 | If enabled, your NodeBB installation would become part of a larger decentralized social network; a federated universe, or _fediverse_. 16 | 17 | [More information about ActivityPub](https://activitypub.rocks/). 18 | 19 | ## Upgrading to v4 20 | 21 | When coming from a version of NodeBB lesser than v4.0.0, your installation will automatically run several upgrade scripts; one of those scripts will **intentionally disable** ActivityPub integration so as to not surprise administrators of existing installations. (See "Enabling Federation", below.) 22 | 23 | Once enabled, pre-existing categories will not federate out-of-the-box. You will need to modify their privileges so that the "fediverse" pseudo-user is granted viewing and posting privileges on a per-category basis. 24 | 25 | *N.B. New installations of NodeBB v4+ will have ActivityPub enabled, and all categories will federate by default.* 26 | 27 | ## Enabling Federation 28 | 29 | ActivityPub integration is controlled via a global toggle switch in the admin panel (`ACP > Settings > Federation`). 30 | 31 | ### Additional Settings 32 | 33 | A list of additional settings available for tweaking the ActivityPub integration can be found [here](./settings.md). 34 | 35 | ## How is NodeBB different from other apps on the fediverse? 36 | 37 | By some margin, the largest ActivityPub implementor is [Mastodon](https://joinmastodon.org/), a micro-blogging platform (similar to Twitter/X.) Other notable apps include, but are not limited to, [WordPress](https://wordpress.org/plugins/activitypub/) and [Ghost](https://activitypub.ghost.org/) (both blogs), [Pixelfed](//pixelfed.org) (media-focused feed, like Instagram), and [Threads](//threads.net) (micro-blogging platform by Meta.) 38 | 39 | All of those examples present and organize their content in a different manner, but via ActivityPub, content can be exchanged seamlessly between them. 40 | 41 | NodeBB belongs to a subset of ActivityPub implementors who structure their content in topics (or threads). A forum-style presentation of content allows for topics to be organized logically, which is a departure from the somewhat ephemeral nature of social networks found today. 42 | 43 | Typically, content is also presented in chronological order (or reverse so when listing topics). This presents a recency bias for content, but also allows for more algorithmic-free discovery of new content. As topics receive replies, they are bumped up to the top of the list, allowing others to re-discover the content. 44 | 45 | Additionally, NodeBB contains strong tooling for local community building. Not all categories need be federated, and some can be kept within the local community for more focused discussion. 46 | 47 | ## Discovering Content 48 | 49 | When first enabled, it may seem as though there is not much remote content to view, or even none at all. This lack of content is due to ActivityPub being a "follow-based" protocol. Content is streamed to you in real-time from your followers, and vice versa. Unlike traditional social media, there is no centralized authority to artificially boost your content for viewership purposes, or to expose you to new content. 50 | 51 | Remote users can be discovered by using the search bar. Enter the handle of a remote user (e.g. `julian@community.nodebb.org`) to see their profile and follow them! 52 | 53 | For more information, see the [Discovery](./discovery.md) page. 54 | 55 | ## The "Uncategorized" category 56 | 57 | NodeBB v4 introduces a new (albeit oddly named) pseudo-category called "Uncategorized". This category is a catch-all bucket for remote content, and content pruning logic works only on topics contained in this pseudo-category. 58 | 59 | [More information on the "Uncategorized" pseudo-category](../development/plugins/uncategorized.md). 60 | 61 | ## Privileges 62 | 63 | Fine-grained control over how content from the fediverse ("remote content") is handled can be adjusted using the existing privilege tooling at ACP > Manage > Privileges. 64 | 65 | For more information, see the [privileges](./privileges.md) page. -------------------------------------------------------------------------------- /src/docs/images/nodebb.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /src/docs/development/i18n.md: -------------------------------------------------------------------------------- 1 | # Internationalising your Plugin/Theme 2 | 3 | You are free to write your plugin and/or theme in whatever language you'd like, although if you wish to support multiple languages, NodeBB has a language engine that you can utilise. 4 | 5 | In this article, we'll be referring to *plugins*. Keep in mind that themes are also plugins, so the implementation is the same for both. 6 | 7 | ## Step 1: Directory layout of translations 8 | 9 | To begin, let's define some language keys and translations! In your plugin, create a new directory to house your translations. Keep in mind that the structure of the files _inside_ this folder must match that of NodeBB itself: Each sub-directory is named after a language **key** (e.g. `en-GB`), and contains `.json` files housing the translations themselves. 10 | 11 | ``` bash 12 | $ cd /path/to/my/plugin 13 | $ mkdir -p languages/en-GB 14 | $ mkdir -p languages/es 15 | ``` 16 | 17 | In the commands above, I've created my languages folder, with two languages, English (`en-GB`), and Spanish (`es`). 18 | 19 | ## Step 2: Add your translations 20 | 21 | In the sub-directories created in Step 1, I'll create text files with a `.json` extension. These file will house the plugin's translations. 22 | 23 | In `languages/en-GB/myplugin.json`: 24 | 25 | ``` json 26 | { 27 | "greeting": "Hello there! How are you?" 28 | } 29 | ``` 30 | 31 | In `languages/es/myplugin.json`: 32 | 33 | ``` json 34 | { 35 | "greeting": "Hola! Como estás?" 36 | } 37 | ``` 38 | 39 | You can name the file whatever you'd like, but keeping it something recognizable (e.g. related to your plugin) is ideal. You can also name a file the same name as an existing language file in NodeBB. NodeBB will automatically merge the two localisation sets together into a single set. For example, NodeBB contains a `user.json` file. You can also name your file `user.json` and you can call language strings from both files in your plugin/theme. 40 | 41 | **Note**: Remember to change the name `myplugin` to something related to your plugin! 42 | 43 | ## Step 3: Tell NodeBB that you have language files to load 44 | 45 | NodeBB won't automatically know you have translations to load, so we'll need to add a line to our `plugin.json` file to tell NodeBB to load our language files, and where those files reside. 46 | 47 | Open up `plugin.json` and add a new property called `languages`: 48 | 49 | ``` json 50 | { 51 | ... 52 | "languages": "languages", 53 | ... 54 | } 55 | ``` 56 | 57 | The value for this property is the path to wherever your language files reside, _relative to the plugin's root folder_. In this case, I've placed my languages in a folder called `languages` directly in my plugin's root folder, so I just need to put in `languages`. If my languages were in a sub-folder called `public`, then the correct value here would be `public/languages`. 58 | 59 | ## Step 4: Use your translations in your plugin 60 | 61 | There are a number of ways you can use your translations in your plugin: 62 | 63 | ### Server-side 64 | 65 | In your server-side code, you can invoke the translation engine as follows: 66 | 67 | ``` js 68 | var translator = require.main.require('./src/translator'); 69 | 70 | translator.translate('[[myplugin:greeting]]', function(translated) { 71 | console.log('Translated string:', translated); 72 | }); 73 | ``` 74 | 75 | **Note**: Server-side invocation will translate to server's default language in ACP settings: `http:///admin/general/languages` 76 | 77 | ### Client-side 78 | 79 | In the browser, you can invoke the translation engine as follows: 80 | 81 | ``` js 82 | require(['translator'], function(translator) { 83 | translator.translate('[[myplugin:greeting]]', function(translated) { 84 | console.log('Translated string:', translated); 85 | }); 86 | }); 87 | ``` 88 | 89 | **Note**: Client-side invocation will translate to the language in user settings: `http:///user//settings` 90 | 91 | ### Templates 92 | 93 | In your templates, you don't need to do anything special to invoke the translation engine, it is run through automatically, and parses any language strings matching the following syntax: `[[resource:key]]`. So for our plugin: 94 | 95 | ``` html 96 |

[[myplugin:greeting]]

97 | ``` 98 | 99 | ## (Optional) Step 5: Tell NodeBB that a particular language is the default 100 | 101 | NodeBB itself supports around 40 languages, so you couldn't possibly be expected to translate them into every language! To define a specific language as default, add the `defaultLang` property to your `plugin.json` file: 102 | 103 | ``` json 104 | { 105 | ... 106 | "languages": "languages", 107 | "defaultLang": "es", 108 | ... 109 | } 110 | ``` 111 | 112 | Now, if a user utilising a language not supported by your plugin loads a language resource for your plugin, they will see the Spanish translation, as it is the designated fallback language. 113 | -------------------------------------------------------------------------------- /src/docs/installing/os/smartos.md: -------------------------------------------------------------------------------- 1 | SmartOS 2 | ======= 3 | 4 | Requirements 5 | ------------ 6 | 7 | NodeBB requires the following software to be installed: 8 | 9 | - Node.js (version 12 or greater, instructions below). 10 | - Redis (version 2.6.12 or greater, instructions below) or MongoDB 11 | (version 3.2 or greater). 12 | - nginx (version 1.3.13 or greater, **only if** intending to use nginx 13 | to proxy requests to a NodeBB server). 14 | 15 | Server Access 16 | ------------- 17 | 18 | 1. Sign in your Joyent account: [Joyent.com](http://joyent.com) 19 | 1. Select: `Create Instance` 20 | 1. Create the newest `smartos nodejs` image. 21 | 22 | > **Note:** The following steps have been tested with images: 23 | > `smartos nodejs 13.1.0` `smartos nodejs 13.2.3` 24 | 25 | 1. Wait for your instance to show `Running` then click on its name. 26 | 1. Find your `Login` and admin password. If the `Credentials` section 27 | is missing, refresh the webpage. 28 | 29 | > **Example:** `ssh root@0.0.0.0` `A#Ca{c1@3` 30 | 31 | 1. SSH into your server as the admin not root: `ssh admin@0.0.0.0` 32 | 33 | > **Note:** For Windows users that do not have ssh installed, here 34 | > is an option: [Cygwin.com](http://cygwin.com) 35 | 36 | Installation 37 | ------------ 38 | 39 | 1. Install NodeBB's software dependencies: 40 | 41 | > ``` 42 | > $ sudo pkgin update 43 | > $ sudo pkgin install scmgit nodejs build-essential ImageMagick redis 44 | > ``` 45 | > 46 | > If any of those failed to install then: 47 | > 48 | > ``` 49 | > $ pkgin search *failed-name* 50 | > $ sudo pkgin install *available-name* 51 | > ``` 52 | 53 | 1. **If needed** setup a redis-server with default settings as a 54 | service (automatically starts and restarts): 55 | 56 | > If you want to use MongoDB, LevelDB, or another database instead 57 | > of Redis please look at the 58 | > [Configuring Databases](../../configuring/databases/index.md) section. 59 | > 60 | > **Note:** These steps quickly setup a redis server but do not 61 | > fine-tuned it for production. 62 | > 63 | > **Note:** If you manually ran `redis-server` then exit out of 64 | > it now. 65 | > 66 | > ``` 67 | > $ svcadm enable redis 68 | > $ svcs svc:/pkgsrc/redis:default 69 | > ``` 70 | > 71 | > **Note:** If the STATE is maintenance then: 72 | > 73 | > ``` 74 | > $ scvadm clear redis 75 | > ``` 76 | > 77 | > *-* To shut down your redis-server and keep it from restarting: 78 | > 79 | > ``` 80 | > $ scvadm disable redis 81 | > ``` 82 | > 83 | > *-* To start up your redis-server and have it always running: 84 | > 85 | > ``` 86 | > $ scvadm enable redis 87 | > ``` 88 | 89 | 1. Move to where you want to create the nodebb folder: 90 | 91 | > ``` 92 | > $ cd /parent/directory/of/nodebb/ 93 | > ``` 94 | 95 | 1. Clone NodeBB's repository (you may replace the ending nodebb with a 96 | different folder name): 97 | 98 | > ``` 99 | > $ git clone -b v2.x https://github.com/NodeBB/NodeBB.git nodebb 100 | > $ cd nodebb 101 | > ``` 102 | 103 | 1. Run NodeBB's setup script: 104 | 105 | > ``` 106 | > $ ./nodebb setup 107 | > ``` 108 | > 109 | > a. `URL used to access this NodeBB` is either your public ip 110 | > address from your ssh `Login` or your domain name pointing to 111 | > that ip address. 112 | > 113 | > > **Example:** `http://0.0.0.0` or `http://example.org` 114 | > 115 | > b. `Port number of your NodeBB` is the port needed to access your 116 | > site: 117 | > 118 | > > **Note:** If you do not proxy your port with something like 119 | > > nginx then port 80 is recommended for production. 120 | > 121 | > c. `Please enter a NodeBB secret` - Do not email this or 122 | > post publicly. 123 | > d. `IP or Hostname to bind to` - Use default unless your server 124 | > requires otherwise. 125 | > e. If you used the above steps to setup your redis-server then 126 | > use the default redis settings. 127 | 128 | 1. Start NodeBB process manually: 129 | 130 | > **Note:** This should not be used for production but instead create a deamon manually, use Forever, or use Supervisor. Take a look at the options [here])../../running/index). 131 | 132 | > ``` 133 | > $ node app 134 | > ``` 135 | 136 | 1. Visit your app! 137 | 138 | > **Example:** With a port of 4567: `http://0.0.0.0:4567` or `http://example.org:4567` 139 | > 140 | > **Note:** With port 80 the `:80` does not need to be entered. 141 | 142 | ---- 143 | 144 | **Note:** If these instructions are unclear or if you run into trouble, 145 | please let us know by [filing an 146 | issue](https://github.com/NodeBB/NodeBB/issues). 147 | 148 | Upgrading NodeBB 149 | ---------------- 150 | 151 | **Note:** Detailed upgrade instructions are listed in [Upgrading NodeBB](../../configuring/upgrade.md). 152 | -------------------------------------------------------------------------------- /src/docs/configuring/upgrade.md: -------------------------------------------------------------------------------- 1 | Upgrading NodeBB 2 | ================ 3 | 4 | NodeBB's periodic releases are located in the 5 | [Releases](https://github.com/NodeBB/NodeBB/releases). These releases 6 | contain what is usually considered the most bug-free code, and is 7 | designed to be used on production-level instances of NodeBB. 8 | 9 | You can utilise git to install a specific version of NodeBB, and upgrade 10 | periodically as new releases are made. 11 | 12 | To obtain the latest fixes and features, you can also `git clone` the 13 | latest version directly from the repository (`master` branch), although 14 | its stability cannot be guaranteed. Core developers will attempt to 15 | ensure that every commit results in a working client, even if individual 16 | features may not be 100% complete. 17 | 18 | ***As always***, the NodeBB team is not responsible for any 19 | misadventures, loss of data, data corruption, or any other bad things 20 | that may arise due to a botched upgrade - so please **don't forget to 21 | back up** before beginning! 22 | 23 | ## Upgrade Path 24 | 25 | NodeBB's upgrade path is designed so that upgrading between versions is straightforward. 26 | 27 | ## Upgrade Steps 28 | 29 | ### 1. Shut down your forum 30 | 31 | While it is possible to upgrade NodeBB while it is running, it is 32 | definitely not recommended, particularly if it is an active forum: 33 | 34 | ``` bash 35 | cd /path/to/nodebb 36 | ./nodebb stop 37 | ``` 38 | 39 | ### 2. Back up your data 40 | 41 | #### Backing up Redis 42 | 43 | As with all upgrades, the first step is to **back up your data**! Nobody 44 | likes database corruption/misplacement. 45 | 46 | All of the textual data stored in NodeBB is found in a `.rdb` file. On 47 | typical installs of Redis, the main database is found at 48 | `/var/lib/redis/dump.rdb`. 49 | 50 | **Store this file somewhere safe.** 51 | 52 | #### Backing up MongoDB 53 | 54 | To run a backup of your complete MongoDB you can simply run 55 | 56 | > mongodump 57 | 58 | which will create a directory structure that can be restored with the 59 | mongorestore command. 60 | 61 | It is recommended that you first shut down your database. On Debian / 62 | Ubuntu it's likely to be: sudo service mongodb stop 63 | 64 | **Store this file somewhere safe.** 65 | 66 | #### Uploads 67 | 68 | Uploaded images and files are stored in /public/uploads. Feel free to 69 | back up this folder too: 70 | 71 | ``` bash 72 | cd /path/to/nodebb/public 73 | tar -czf ~/nodebb_assets.tar.gz ./uploads 74 | ``` 75 | 76 | ### 3. Grab the latest and greatest code 77 | 78 | Before upgrading NodeBB make sure you have the required nodejs version. NodeBB supports the latest stable versions of nodejs. (v18, etc.) To upgrade nodejs run 79 | 80 | ``` bash 81 | curl -sL https://deb.nodesource.com/setup_lts.x | sudo -E bash - 82 | sudo apt-get install -y nodejs 83 | ``` 84 | 85 | Navigate to your NodeBB: `cd /path/to/nodebb`. 86 | 87 | There are multiple ways NodeBB can be installed. You could either be on the main branch (`master`), a release branch (e.g. `v2.x`), or using archived downloads from [releases of NodeBB repo](https://github.com/NodeBB/NodeBB/releases). 88 | 89 | Don't know what branch you are on? Execute 90 | `git rev-parse --abbrev-ref HEAD` to find out. 91 | 92 | #### via main branch 93 | 94 | ``` bash 95 | git fetch # Grab the latest code from the NodeBB repository 96 | git reset --hard v2.2.5 # Replace this with the version you want to upgrade to 97 | ``` 98 | 99 | This should retrieve the latest (and greatest) version of NodeBB from 100 | the repository. 101 | 102 | #### via release branches 103 | 104 | If you are upgrading from a lower branch to a higher branch, switch 105 | branches as necessary. ***Make sure you are completely up-to-date on 106 | your current branch!***. 107 | 108 | For example, if upgrading from `v1.19.8` to `v2.2.5`: 109 | 110 | ``` bash 111 | git fetch # Grab the latest code from the NodeBB repository 112 | git checkout v2.x # Switch to the v2.x branch since we are now upgrading to NodeBB version 2 113 | git reset --hard origin/v2.x 114 | ``` 115 | 116 | If not upgrading between branches (e.g. `v2.2.4` to `v2.2.5`), just run 117 | the following commands: 118 | 119 | ``` bash 120 | git fetch 121 | git reset --hard origin/v2.x 122 | ``` 123 | 124 | This should retrieve the latest (and greatest) version of NodeBB from the repository. 125 | 126 | #### via archived release 127 | 128 | Alternatively, download and extract the latest versioned copy of the code from [the Releases Page](https://github.com/NodeBB/NodeBB/releases). 129 | Overwrite any files as necessary. This method is not supported. 130 | 131 | ### 4. Run the NodeBB upgrade script 132 | 133 | This script will install any missing dependencies, upgrade any plugins or themes (if an upgrade is available), and migrate the database if necessary. 134 | 135 | ``` bash 136 | ./nodebb upgrade 137 | ``` 138 | 139 | ### 5. Start up NodeBB & Test! 140 | 141 | ``` bash 142 | ./nodebb start -l 143 | ``` 144 | 145 | You should now be running the latest version of NodeBB. 146 | -------------------------------------------------------------------------------- /src/docs/configuring/databases/mongo.md: -------------------------------------------------------------------------------- 1 | MongoDB 2 | ======= 3 | 4 | If you're afraid of running out of memory by using Redis, or want your 5 | forum to be more easily scalable, you can install NodeBB with MongoDB. 6 | This tutorial assumes you know how to SSH into your server and have root 7 | access. 8 | 9 | **These instructions are for Ubuntu. Adjust them accordingly for your 10 | distro.** 11 | 12 | **Note:** If you have to add `sudo` to any command, do so. No one is 13 | going to hold it against you ;) 14 | 15 | Step 1: Install MongoDB 16 | ----------------------- 17 | 18 | The latest and greatest MongoDB is required (or at least greater than 19 | the package manager). The instructions to install it can be found on the 20 | [MongoDB 21 | manual](http://docs.mongodb.org/manual/administration/install-on-linux/)). 22 | 23 | Step 2: Install node.js 24 | ----------------------- 25 | 26 | Like MongoDB, the latest and greatest node.js is required (or at least 27 | greater than the package manager), so I'm leaving this to the official 28 | wiki. The instructions to install can be found on 29 | [Joyent](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager). 30 | 31 | **Note: NPM is installed along with node.js, so there is no need to 32 | install it separately** 33 | 34 | Step 3: Install the Base Software Stack 35 | ------------------------- 36 | 37 | Enter the following into the terminal to install the base software 38 | required to run NodeBB: 39 | 40 | ``` bash 41 | # apt-get install git build-essential imagemagick 42 | ``` 43 | 44 | Step 4: Clone the Repository 45 | ------------------------- 46 | 47 | Enter the following into the terminal, replacing 48 | /path/to/nodebb/install/location to where you would like NodeBB to be 49 | installed. 50 | 51 | ``` bash 52 | $ cd /path/to/nodebb/install/location 53 | $ git clone git://github.com/NodeBB/NodeBB.git nodebb 54 | ``` 55 | 56 | Step 5: Install The Required NodeBB Dependencies 57 | ------------------------- 58 | 59 | Go into the newly created nodebb directory and install the required 60 | dependencies by entering the following. 61 | 62 | ``` bash 63 | $ cd nodebb 64 | $ npm install 65 | ``` 66 | 67 | Step 6: Adding a New Database With Users 68 | ------------------------- 69 | 70 | To go into the MongoDB command line, type: 71 | 72 | ``` bash 73 | $ mongo 74 | ``` 75 | 76 | To add a new database called nodebb, type: 77 | 78 | ``` 79 | > use nodebb 80 | ``` 81 | 82 | To add a user to access the nodebb database, type: 83 | 84 | ``` 85 | > db.createUser( { user: "nodebb", pwd: "", roles: [ "readWrite" ] } ) 86 | ``` 87 | 88 | If you want to be able to view database statistics in NodeBB's admin 89 | control panel (Advanced → Database) type also this command: 90 | 91 | ``` 92 | > db.grantRolesToUser("nodebb",[{ role: "clusterMonitor", db: "admin" }]); 93 | ``` 94 | 95 | If you don't type the last command you will get this error message when 96 | trying to see database statistics: 97 | 98 | ``` 99 | Internal Error. 100 | 101 | Oops! Looks like something went wrong! 102 | 103 | /api/admin/advanced/database 104 | 105 | not authorized on nodebb to execute command { serverStatus: 1 } 106 | ``` 107 | 108 | 109 | **Note**: NodeBB requires MongoDB 3.0 or higher. The role `readWrite` 110 | provides read or write any collection within a specific database to 111 | user. 112 | 113 | Step 7: Configure MongoDB 114 | ------------------------- 115 | 116 | Modify `/etc/mongodb.conf`. 117 | 118 | ``` 119 | # nano /etc/mongodb.conf 120 | ``` 121 | 122 | To enable authentication, type: 123 | 124 | Uncomment `security:` and add `authorization: enabled` below it (and 125 | don't forget to put two spaces before the second line). It should look 126 | like this: 127 | 128 | ``` 129 | security: 130 | authorization: enabled 131 | ``` 132 | 133 | Restart MongoDB. 134 | 135 | ``` 136 | # service mongodb restart 137 | ``` 138 | 139 | Step 8: Configuring NodeBB 140 | ------------------------- 141 | 142 | Make sure you are in your NodeBB root folder. If not, just type: 143 | 144 | ``` 145 | $ cd /path/to/nodebb 146 | ``` 147 | 148 | To setup the app, type: 149 | 150 | ``` 151 | $ node app --setup 152 | ``` 153 | 154 | - Change the hostname to your domain name. 155 | - Accept the defaults by pressing enter until it asks you what 156 | database you want to use. Type `mongo` in that field. 157 | - Accept the default port, unless you changed it in the 158 | previous steps. 159 | - Change your username to `nodebb`, unless you set it to 160 | another username. 161 | - Enter in the password you made in step 5. 162 | - Change the database to `nodebb`, unless you named it something else. 163 | 164 | Continue with the installation, following the instructions the installer 165 | provides you. 166 | 167 | Step 9: Starting the App 168 | ------------------------ 169 | 170 | To start the app, run: 171 | 172 | ``` 173 | $ ./nodebb start 174 | ``` 175 | 176 | Now visit `yourdomainorip.com:4567` and your NodeBB installation should 177 | be running. 178 | 179 | NodeBB can also be started with helper programs, such as [supervisor or forever](../running.md). You can also [use `nginx` as a reverse proxy](../proxies/index.md). 180 | 181 | Advanced Settings 182 | =========== 183 | 184 | The mongodb nodejs driver has a default connection pool size of 5, if 185 | you need to increase this just add a poolSize setting into your 186 | config.json file under the mongo block. 187 | -------------------------------------------------------------------------------- /src/docs/configuring/running.md: -------------------------------------------------------------------------------- 1 | Running NodeBB 2 | ============== 3 | 4 | The preferred way to start and stop NodeBB is by invoking its 5 | executable: 6 | 7 | * `./nodebb start` Starts the NodeBB server 8 | * `./nodebb stop` Stops the NodeBB server 9 | * Alternatively, you may use `npm start` and `npm stop` to do the same 10 | 11 | However, NodeBB when started via `./nodebb start` will not automatically start up again when the system reboots. The methods listed below are alternatives to starting NodeBB via the 12 | executable. 13 | 14 | ## systemd 15 | 16 | The new standard for Ubuntu/CentOS/Debian/OpenSuse is to use `systemd` to manage their services. The following is a systemd service example you can use, but **assumes the following**: 17 | 18 | * MongoDB is installed via package manager and is managed by `systemd` 19 | * Node.js is installed via package manager and can be invoked via the `env` executable 20 | * NodeBB is run under the unprivileged user `nodebb` 21 | * You will [use the systemd journal](https://www.digitalocean.com/community/tutorials/how-to-use-journalctl-to-view-and-manipulate-systemd-logs) to manage NodeBB's logs 22 | 23 | ``` 24 | [Unit] 25 | Description=NodeBB 26 | Documentation=https://docs.nodebb.org 27 | After=system.slice multi-user.target mongod.service 28 | 29 | [Service] 30 | Type=forking 31 | User=nodebb 32 | 33 | WorkingDirectory=/path/to/nodebb 34 | PIDFile=/path/to/nodebb/pidfile 35 | ExecStart=/usr/bin/env node loader.js --no-silent 36 | Restart=always 37 | 38 | [Install] 39 | WantedBy=multi-user.target 40 | ``` 41 | 42 | Replace the value of `User` (currently set to `nodebb`, above) with the system user you wish to run NodeBB, and the path to NodeBB (`/path/to/nodebb`) as appropriate. 43 | You'll most likely want to set the `User` to a system user with as few privileges as possible. 44 | 45 | Save the file to `/etc/systemd/system/nodebb.service`. 46 | 47 | From here, you can proceed to start and stop NodeBB by doing the following: 48 | 49 | ``` 50 | $ systemctl start nodebb 51 | $ systemctl stop nodebb 52 | ``` 53 | 54 | If you would like NodeBB to automatically start up on system boot: 55 | 56 | ``` 57 | $ systemctl enable mongod 58 | $ systemctl enable nodebb 59 | ``` 60 | 61 | If you do not wish to use `journalctl` to view the NodeBB logs, you can switch back to having logs appended to `logs/output.log` by removing `--no-silent` from the `ExecStart` directive. 62 | 63 | For more information on configuring systemd, please consult [the manpage for the systemd service](https://www.freedesktop.org/software/systemd/man/systemd.service.html). 64 | 65 | ## Upstart 66 | 67 | Older versions of Ubuntu may utilise [Upstart](http://upstart.ubuntu.com/) to manage processes at boot. Upstart also handles restarts of scripts if/when they crash. 68 | 69 | You can use Upstart to start/stop/restart your NodeBB. 70 | 71 | Note: Prior to NodeBB v0.7.0, Upstart processes would not track the proper pid, meaning there was no way to stop the NodeBB process. NodeBB v0.7.0 includes some changes that allow Upstart to control NodeBB more effectively. 72 | 73 | You can utilise this Upstart configuration as a template to manage your NodeBB: 74 | 75 | ``` 76 | start on startup 77 | stop on runlevel [016] 78 | respawn 79 | setuid someuser 80 | setgid someuser 81 | script 82 | cd /path/to/nodebb 83 | node loader.js --no-silent --no-daemon 84 | end script 85 | ``` 86 | 87 | From there, you can start stop and restart NodeBB as the root user: 88 | `start nodebb`, `stop nodebb`, `restart nodebb`, assuming `nodebb.conf` 89 | is the name of the Upstart config file. 90 | 91 | **Notes**: 92 | 93 | * If a service is reported as started (eg mongod.service), does not mean it has completed its starting process. For more information, one will need to monitor journalctl and see if it has started. When starting a service, wait a minute or 2 (depending on your server's technical specifications) 94 | * By adding `mongod.service`, or `AnyOther.service` in the `After=` field, means it will try to start when the service is reported as started. It will however NOT check if the service is working (e.g. `network.service`, it can be started, but it will not check if you are connected to a network). If the service has been enabled (`systemctl enable SERVICENAME`), then it will keep retrying, until it has started or until dependent services has started, or otherwise stated in the service file. 95 | 96 | ## Supervisor Process 97 | 98 | Using the [supervisor package](https://github.com/isaacs/node-supervisor), you can have NodeBB 99 | restart itself if it crashes: 100 | 101 | ``` bash 102 | $ npm install -g supervisor 103 | $ supervisor app 104 | ``` 105 | 106 | As `supervisor` by default continues to pipe output to `stdout`, it is 107 | best suited to development builds. 108 | 109 | ## Forever Daemon 110 | 111 | Another way to keep NodeBB up is to use the [forever 112 | package](https://github.com/nodejitsu/forever) via the command line 113 | interface, which can monitor NodeBB and re-launch it if necessary: 114 | 115 | ``` bash 116 | $ npm install -g forever 117 | $ forever start app.js 118 | ``` 119 | 120 | You can `forever start` and `forever stop` app.js, although the built-in Reload/Restart tools in the ACP will not work. 121 | 122 | ## Grunt Development 123 | 124 | We can utilize grunt to launch NodeBB and re-compile assets when files 125 | are changed. Start up speed is increased because we don't compile assets 126 | that weren't modified. 127 | 128 | Installing Grunt 129 | 130 | ``` bash 131 | $ npm install -g grunt-cli 132 | ``` 133 | 134 | Run grunt to start up NodeBB and watch for code changes. 135 | 136 | ``` bash 137 | $ grunt 138 | ``` 139 | -------------------------------------------------------------------------------- /src/docs/installing/os/macOS.md: -------------------------------------------------------------------------------- 1 | # macOS 2 | 3 | ## Required Software 4 | 5 | First, install the following programs: 6 | 7 | - 8 | - 9 | 10 | ## Installing NodeBB 11 | 12 | ### With mongoDB 13 | 14 | The following is an abbreviation of [the official MongoDB installation guide for macOS](https://www.mongodb.com/docs/manual/tutorial/install-mongodb-on-os-x/#using-the-mongodb-database-tools). If you're having issues, fall back to using that guide instead. 15 | 16 | Homebrew requires the Xcode command-line tools from Apple's Xcode. 17 | 18 | Install the Xcode command-line tools by running the following command in your macOS Terminal: 19 | ``` 20 | xcode-select --install 21 | ``` 22 | 23 | Install mongoDB with homebrew by entering the following commands into terminal: 24 | 25 | ``` 26 | brew tap mongodb/brew 27 | ``` 28 | 29 | ``` 30 | brew update 31 | ``` 32 | 33 | ``` 34 | brew install mongodb-community@7.0 35 | ``` 36 | 37 | Verify installation of MongoDB. You should have version 7.0: 38 | ``` 39 | mongod --version 40 | ``` 41 | Start mongodb server, in your terminal enter: 42 | 43 | ``` 44 | brew services start mongodb-community@7.0 45 | ``` 46 | 47 | ### Configure MongoDB 48 | 49 | 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: 50 | 51 | ``` 52 | mongosh 53 | ``` 54 | 55 | Switch to the built-in `admin` database: 56 | 57 | ``` 58 | use admin 59 | ``` 60 | 61 | Create an administrative user (the is different from the `nodebb` user we'll create later). Replace the placeholder `` with your own selected password. Be sure that the `<` and `>` are also not left behind. 62 | 63 | ``` 64 | db.createUser( { user: "admin", pwd: "", roles: [ { role: "root", db: "admin" } ] } ) 65 | ``` 66 | 67 | This user is scoped to the `admin` database to manage MongoDB once authorization has been enabled. 68 | 69 | To initially create a database that doesn't exist simply `use` it. Add a new database called `nodebb`: 70 | 71 | ``` 72 | use nodebb 73 | ``` 74 | 75 | The database will be created and context switched to `nodebb`. Next create the `nodebb` user with the appropriate privileges: 76 | 77 | ``` 78 | db.createUser( { user: "nodebb", pwd: "", roles: [ { role: "readWrite", db: "nodebb" }, { role: "clusterMonitor", db: "admin" } ] } ) 79 | ``` 80 | 81 | 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). 82 | 83 | Exit the Mongo Shell: 84 | 85 | ``` 86 | quit() 87 | ``` 88 | 89 | Enable database authorization in the MongoDB configuration file ` /usr/local/etc/mongod.conf` by appending the following lines: 90 | 91 | ``` 92 | security: 93 | authorization: enabled 94 | ``` 95 | (Hint: To find that file, navigate to root folder in Finder and enter `shift` + `cmd` + `.`. This reveals, hidden system folders and `/usr` should appear.) 96 | 97 | Restart MongoDB and verify the administrative user created earlier can connect: 98 | 99 | ``` 100 | brew services restart mongodb/brew/mongodb-community@7.0 101 | mongosh "mongodb://localhost:27017" --username admin --authenticationDatabase admin 102 | 103 | ``` 104 | 105 | If everything is configured correctly the Mongo Shell will connect. Exit the shell. 106 | 107 | 108 | ### Or with redis server 109 | 110 | Install redis with homebrew: 111 | 112 | ``` 113 | brew install redis 114 | ``` 115 | 116 | Start redis server, in your terminal enter: 117 | 118 | ``` 119 | redis-server 120 | ``` 121 | 122 | ### Installing NodeBB 123 | After you've installed MongoDB, we can continue with NodeBB. Clone NodeBB into an appropriate location. 124 | Here the local nodebb directory is used, though any destination is fine: 125 | 126 | ```sh 127 | git clone -b v3.x https://github.com/NodeBB/NodeBB.git nodebb 128 | cd nodebb 129 | ``` 130 | 131 | This clones the NodeBB repository from the v3.x branch to the nodebb directory. A list of alternative branches are 132 | available in the [NodeBB Branches](https://github.com/NodeBB/NodeBB/branches) GitHub page, but only the versioned branches are stable. 133 | 134 | NodeBB ships with a command line utility which allows for several functions. We'll first use it to setup NodeBB. 135 | This will install modules from npm and then enter the setup utilty. 136 | 137 | ```sh 138 | ./nodebb setup 139 | ``` 140 | **If you setup with mongodb:** 141 | 142 | A series of questions will be prompted with defaults in parentheses. The default settings are for a local server listening 143 | on the default port `4567` with a MongoDB instance listening on port `27017`. When prompted for the mongodb username and password, 144 | enter `nodebb`, and the password that you configured earlier. Once connectivity to the database is confirmed the setup will prompt 145 | that initial user setup is running. Since this is a fresh NodeBB install a forum administrator must be configured. 146 | Enter the desired administrator information. This will culminate in a _NodeBB Setup Completed_ message. 147 | 148 | **If you setup with redis server:** 149 | 150 | You may leave all of the options as default, except "Which database to 151 | use (mongo)", which you should answer with "redis". Once connectivity to the database is confirmed the setup will prompt 152 | that initial user setup is running. Since this is a fresh NodeBB install a forum administrator must be configured. 153 | Enter the desired administrator information. This will culminate in a _NodeBB Setup Completed_ message. 154 | 155 | Finally, you can use the cli utility to start NodeBB: 156 | 157 | ```sh 158 | ./nodebb start 159 | ``` 160 | 161 | You can visit your forum at `http://localhost:4567/` 162 | -------------------------------------------------------------------------------- /src/docs/configuring/proxies/apache.md: -------------------------------------------------------------------------------- 1 | Configuring Apache as a proxy 2 | ============================= 3 | 4 | NodeBB by default runs on port 4567, meaning that builds are usually accessed using a port number in addition to their hostname (e.g. http://example.com:4567) 5 | 6 | In order to allow NodeBB to be served without a port, Apache can be set up to proxy all requests to a particular hostname (or subdomain) to an upstream NodeBB build running on any port. 7 | 8 | Requirements 9 | ---------------------------- 10 | 11 | **Note**: This requires Apache v2.4.x or greater. If your version of Apache is older, please see [Apache v2.2.x Instructions](./apache2.2.md) 12 | 13 | You have to enable the following Apache mods: 14 | 15 | 1. `sudo a2enmod proxy` 16 | 2. `sudo a2enmod proxy_http` 17 | 3. `sudo a2enmod proxy_wstunnel` 18 | 4. `sudo a2enmod rewrite` 19 | 5. `sudo a2enmod headers` 20 | 21 | Configuration 22 | ------------------------ 23 | 24 | The next step is creating a configuration file, typically named after your site (e.g. `www.example.com.conf`), in the Apache vhost 25 | config directory, usually found at `/etc/apache2/sites-available/`. Make sure to match servername to the URL field defined in the `config.json`. 26 | 27 | Below is a minimal Apache virtualhost configuration for NodeBB running on port `4567`. 28 | 29 | ``` apache 30 | 31 | ServerName www.example.com 32 | RequestHeader set X-Forwarded-Proto "http" 33 | 34 | ProxyRequests off 35 | 36 | Order deny,allow 37 | Allow from all 38 | 39 | 40 | RewriteEngine On 41 | RewriteCond %{REQUEST_URI} ^/socket.io [NC] 42 | RewriteCond %{QUERY_STRING} transport=websocket [NC] 43 | RewriteRule /(.*) ws://127.0.0.1:4567/$1 [P,L] 44 | 45 | ProxyPass / http://127.0.0.1:4567/ 46 | ProxyPassReverse / http://127.0.0.1:4567/ 47 | 48 | ``` 49 | 50 | This is a more advanced Apache virtualhost configuration which uses TLS, HTTP/2, static file cache headers 51 | and redirects http traffic **permanently** to HTTPS! 52 | 53 | ```apache 54 | 55 | ServerName www.example.com 56 | ServerAlias example.com 57 | 58 | # Rewrite any http traffic to the main url https site 59 | 60 | RewriteEngine On 61 | RewriteRule ^[^\/]*\/(.*) https://www.example.com/$1 [R=301,L] 62 | 63 | 64 | 65 | 66 | Protocols h2 http/1.1 67 | ServerName www.example.com 68 | 69 | SSLEngine on 70 | SSLCertificateFile /path/to/cert.pem 71 | SSLCertificateKeyFile /path/to/privkey.pem 72 | SSLCertificateChainFile /path/to/chain.pem 73 | 74 | # Basic security headers 75 | Header always set X-Content-Type-Options "nosniff" 76 | Header always set X-Xss-Protection "1; mode=block" 77 | 78 | # NodeBB header 79 | RequestHeader set X-Forwarded-Proto "https" 80 | 81 | # Static file cache 82 | 83 | 84 | ExpiresActive on 85 | ExpiresDefault "access plus 14 days" 86 | Header set Cache-Control "public" 87 | 88 | 89 | 90 | ProxyRequests off 91 | 92 | Order deny,allow 93 | Allow from all 94 | 95 | 96 | # Custom Error Document when NodeBB is offline 97 | ProxyPass /error-documents ! 98 | ErrorDocument 503 /error-documents/503.html 99 | Alias /error-documents /path/to/nodebb/public 100 | 101 | # Websocket passthrough 102 | RewriteEngine On 103 | RewriteCond %{REQUEST_URI} ^/socket.io [NC] 104 | RewriteCond %{QUERY_STRING} transport=websocket [NC] 105 | RewriteRule /(.*) ws://localhost:4567/$1 [P,L] 106 | 107 | ProxyPass / http://localhost:4567/ 108 | ProxyPassReverse / http://localhost:4567/ 109 | 110 | # Log stuff 111 | ErrorLog ${APACHE_LOG_DIR}/www-example-error.log 112 | CustomLog ${APACHE_LOG_DIR}/www-example-access.log combined 113 | 114 | 115 | ``` 116 | 117 | Configuring Apache to use a custom error page 118 | ============================ 119 | 120 | This example will demonstrate how to configure Apache to use a custom 503 121 | error page when your forum isn't running. 122 | 123 | ## Create your custom error page 124 | 125 | You can create your own `503.html` or you use the one included with your NodeBB installation. To make your own create a 126 | new file `503.html` and place it in a subfolder of your NodeBB public folder `/path/to/nodebb/public/error-documents`. 127 | If you want to use the one included with NodeBB, copy the `503.html` from the `public` folder to the subfolder mentioned above. 128 | 129 | Be sure to add content to your `503_custom.html` file. Here's an example which you 130 | can copy and paste: 131 | 132 | ``` 133 | 134 | 135 | 136 | 137 | Insert your page title here 138 | 139 | 140 |

Insert your content here.

141 | 142 | 143 | ``` 144 | 145 | ## Configure Apache to use your custom error page 146 | 147 | We now need to tell Apache to use our page when the relevant error 148 | occurs. Open your vhost file `/etc/apache2/sites-available/www.example.com.conf`. 149 | 150 | Add this to your active virtual host section and change the paths accordingly. 151 | 152 | ``` 153 | ProxyPass /error-documents ! 154 | ErrorDocument 503 /error-documents/503.html 155 | Alias /error-documents /var/www/nodebb/nodebb/public/error-documents 156 | ``` 157 | 158 | The `Alias` directive is used so that it can be easier excluded from the ProxyPasss directive. 159 | 160 | Reload Apache `sudo service apache2 reload` and the next time a user 161 | visits your forum when it isn't running, they'll see your custom page. 162 | -------------------------------------------------------------------------------- /src/docs/faq.md: -------------------------------------------------------------------------------- 1 | Need Help? 2 | ========== 3 | 4 | Frequently Asked Questions 5 | -------------------------- 6 | 7 | If you experience difficulties setting up a NodeBB instance, perhaps one 8 | of the following may help. 9 | 10 | ### How do I start/stop/restart NodeBB? 11 | 12 | You can call the `./nodebb` executable to start and stop NodeBB: 13 | 14 | ``` bash 15 | $ ./nodebb 16 | Usage: ./nodebb [options] [command] 17 | 18 | Welcome to NodeBB 19 | 20 | Options: 21 | -V, --version output the version number 22 | --json-logging Output to logs in JSON format (default: false) 23 | --log-level Default logging level to use (default: "info") 24 | --config Specify a config file (default: "config.json") 25 | -d, --dev Development mode, including verbose logging (default: false) 26 | -l, --log Log subprocess output to console (default: false) 27 | -h, --help display help for command 28 | 29 | Commands: 30 | start Start the NodeBB server 31 | stop Stop the NodeBB server 32 | restart Restart the NodeBB server 33 | status Check the running status of the NodeBB server 34 | log Open the output log (useful for debugging) 35 | setup [options] [config] Run the NodeBB setup script, or setup with an initial config 36 | install Launch the NodeBB web installer for configuration setup 37 | build [options] [targets...] Compile static assets (JS, CSS, templates, languages) 38 | activate [plugin] Activate a plugin for the next startup of NodeBB (nodebb-plugin- prefix is optional) 39 | plugins List all installed plugins 40 | events [count] Outputs the most recent administrative events recorded by NodeBB 41 | info Outputs various system info 42 | reset [options] Reset plugins, themes, settings, etc 43 | user [command] Manage users 44 | upgrade [options] [scripts...] Run NodeBB upgrade scripts and ensure packages are up-to-date, or run a particular upgrade script 45 | help [command] Display help for [command] 46 | ``` 47 | 48 | ### How do I reset the admin password? 49 | 50 | The `./nodebb` can be used to reset any users password. All you need to know is the user id. To set a new password, you can use the following command: 51 | 52 | ``` 53 | ./nodebb user reset --password 54 | ``` 55 | 56 | Hint: The admin user id in a default installation is `1`. 57 | 58 | ### How do I upgrade my NodeBB to a newer version? 59 | 60 | Please consult [Upgrading NodeBB](./configuring/upgrade.md) 61 | 62 | ### I upgraded NodeBB and now X isn't working properly! 63 | 64 | Please consult [Upgrading NodeBB](./configuring/upgrade.md) 65 | 66 | ### I installed an incompatible plugin, and now my forum won't start! 67 | 68 | If you know which plugin caused problems, disable it by running: 69 | `./nodebb reset -p nodebb-plugin-pluginName` 70 | 71 | Otherwise, disable all plugins by running: `./nodebb reset -p` 72 | 73 | ### I'm getting an "npm ERR!" error 74 | 75 | For the most part, errors involving `npm` are due to Node.js being 76 | outdated. If you see an error similar to this one while running 77 | `npm install`: 78 | 79 | ``` bash 80 | npm ERR! Unsupported 81 | npm ERR! Not compatible with your version of node/npm: connect@2.7.11 82 | ``` 83 | 84 | You'll need to update your Node.js version to 4 or higher. 85 | 86 | To do this on Ubuntu: 87 | 88 | ``` bash 89 | # Using Ubuntu 90 | curl -sL https://deb.nodesource.com/setup_4.x | sudo -E bash - 91 | sudo apt-get install -y nodejs 92 | 93 | # Using Debian, as root 94 | curl -sL https://deb.nodesource.com/setup_4.x | bash - 95 | apt-get install -y nodejs 96 | ``` 97 | 98 | If successful, running the following command should show a version 99 | higher than 0.8 100 | 101 | ``` bash 102 | # apt-cache policy nodejs 103 | ``` 104 | 105 | ### URLs on my NodeBB (or emails) still have the port number in them! 106 | 107 | If you are using [nginx](./configuring/proxies/nginx.md) or 108 | [Apache](./configuring/proxies/apache.md) as a reverse proxy, you 109 | don't need the port to be shown. Simply run ./nodebb setup and specify 110 | the base URL without a port number. 111 | 112 | Alternatively, edit the `config.json` file using your favourite text 113 | editor and change `use_port` to `false`. 114 | 115 | ### The "Recently Logged In IPs" section only shows 127.0.0.1 116 | 117 | NodeBBs running behind a proxy may have difficulties determining the 118 | original IP address that requests come from. It is important that the 119 | proxy server provides the referral IP header. 120 | 121 | In nginx, ensure that the following line is present in your `server` 122 | block: 123 | 124 | ``` nginx 125 | proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 126 | ``` 127 | 128 | In addition, ensure that the `use_port` option is set to `false` in your 129 | NodeBB's `config.json` 130 | 131 | Submit Bugs on our Issue Tracker 132 | -------------------------------- 133 | 134 | Before reporting bugs, please ensure that the issue has not already been 135 | filed on our 136 | [tracker](https://github.com/NodeBB/NodeBB/issues?state=closed), or has 137 | already been resolved on our [support 138 | forum](http://community.nodebb.org/category/6/bug-reports). If it has 139 | not been filed, feel free to create an account on GitHub and [create a 140 | new issue](https://github.com/NodeBB/NodeBB/issues). 141 | 142 | Ask the NodeBB Community 143 | ------------------------ 144 | 145 | Having trouble installing NodeBB? Or did something break? Don't hesitate 146 | to [join our forum](https://community.nodebb.org/register) and ask for help. 147 | Hopefully one day you'll be able to help others too :) 148 | -------------------------------------------------------------------------------- /src/docs/configuring/config.md: -------------------------------------------------------------------------------- 1 | The NodeBB Config (`config.json`) 2 | ================================= 3 | 4 | The majority of NodeBB's configuration is handled by the Administrator 5 | Control Panel (ACP), although a handful of server-related options are 6 | defined in the configuration file (`config.json`) located at NodeBB's 7 | root folder. Any changes made to config.json file require a restart of NodeBB. 8 | 9 | Some of these values are saved via the setup script: 10 | 11 | * `url` is the full web-accessible address that points to your NodeBB. 12 | If you don't have a domain, an IP address will work fine (e.g. 13 | `http://127.0.0.1:4567`). Subfolder installations also define their 14 | folder here as well (e.g. `http://127.0.0.1:4567/forum`). If the url is 15 | changed to a sub-folder you need to rebuild nodebb with `./nodebb build` 16 | * `secret` is a text string used to hash cookie sessions. If the 17 | secret is changed, all existing sessons will no longer validate and 18 | users will need to log in again. 19 | * `database` defines the primary database used by NodeBB. (e.g. 20 | `redis`, `mongo` or `postgres`) -- for more information, see 21 | Configuring Databases <databases> 22 | * `redis`, `mongo` and `postgres` are objects that contain database-related 23 | connection information, they contain some or all of the following: 24 | * `host` 25 | * `port` 26 | * `uri` (MongoDB only connection string) 27 | * `username` (MongoDB only) 28 | * `password` 29 | * `database` 30 | 31 | The following values are optional, and override the defaults set by 32 | NodeBB: 33 | 34 | * `bcrypt_rounds` (Default: 12) Specifies the number of rounds to hash 35 | a password. Slower machines may elect to reduce the number of rounds 36 | to speed up the login process, but you'd more likely want to 37 | *increase* the number of rounds at some point if computer processing 38 | power gets so fast that the default \# of rounds isn't high enough 39 | of a barrier to password cracking. 40 | * `bind_address` (Default: `0.0.0.0`, or all interfaces) Specifies the local address that NodeBB should bind to. 41 | - By default, NodeBB will listen to requests on all interfaces, but when set, NodeBB will only accept connections from that interface. 42 | * `isCluster` Set this to `true` if you have multiple machines each running a single NodeBB process. This setting is not required if you have multiple NodeBB processes running either on a single or multiple machines. 43 | * `jobsDisabled` This can be added to disable jobs that are run on a certain interval. 44 | - For example "jobsDisabled":true will disable daily digest emails and notification pruning. This option is useful for installations that run multiple NodeBB backends in order to scale. In such a setup, only one backend should handle jobs, and the other backends would set `jobsDisabled` to `true`. 45 | * `acpPluginInstallDisabled` Set this to `true` to prevent plugin installation through the ACP (Administrator Control Panel). When enabled, plugins can only be installed using `./nodebb install` or through npm directly. 46 | * `logFile` (Default: `logs/output.log`) Specifies the path, relative to the NodeBB root install, that the log file will be stored. If this doesn't exist it will be created. Log files will be rotated to the same directory when the current log file gets above 1 Megabyte, to a maximum of 3 archived. 47 | * `port` (Default: `4567`) Specifies the port number that NodeBB will 48 | bind to. You can specify an array of ports and NodeBB will spawn 49 | port.length processes. If you use multiple ports you need to 50 | configure a load balancer to proxy requests to the different ports. 51 | * `max-memory` Specifies the maximum memory a nodebb process can use in megabytes. 52 | * `package_manager` Specifies the package manager that NodeBB will invoke. If not set, will fall back to lockfile detection (and if no lockfiles are present, will use npm.) 53 | * `sessionKey` (Default: `express.sid`) Specifies the session key to use. 54 | * `session_store` This is an object similar to the `redis`, `mongo` or `postgres` block. It defines a database to use for sessions. For example by setting this to a different redis instance you can separate your data and sessions into two different redis instances. 55 | * `name` (Name of database to use `redis`, `mongo` or `postgres`) 56 | * other settings are identical to the database block for the datastore. 57 | * `socket.io` A hash with socket.io settings : 58 | * `transports` (Default: `["polling", "websocket"]`) Can be used to configure socket.io transports. 59 | * `address` (Default: `""`) Address of socket.io server can be empty 60 | * `origins` (Defaults to `url` in `config.json` on all ports) Defined a different url for socket.io connections, in the format `domain.tld:port` (e.g. `example.org:*`) 61 | * If you need to enter multiple origins, separate them using commas (e.g. `https://example.org:*,https://example.net:*`) 62 | * `upload_path` (Default: `/public/uploads`) Specifies the path, 63 | relative to the NodeBB root install, that uploaded files will be 64 | saved in. 65 | * `fontawesome` This is an object that defines additional settings for FontAwesome, the icon library used by NodeBB. 66 | * `pro` Set this to `true` if you want to use the paid FontAwesome Pro icons. Note that you'll need to install FontAwesome Pro package yourself before NodeBB can use it. You can do so by following the instructions on https://fontawesome.com/docs/web/setup/packages 67 | * `styles` (Default: `"*"`) Specifies which styles of icons NodeBB will allow to be used. `"*"` means all supported styles will be used, which currently means `["solid", "brands", "regular"]` if `fontawesome:pro` is false and `["solid", "brands", "regular", "light", "thin", "duotone", "sharp"]` otherwise. 68 | * `plugins:active` An array of active plugins `["nodebb-plugin-mentions", "nodebb-plugin-markdown"]`, if set this array is used instead of reading active plugins from the database. 69 | * `ssl` An object with secure sockets layer options. If this property is present, NodeBB will use a secure https server: 70 | * `key` File path of the private key file. 71 | * `cert` File path of the public certificate file. 72 | -------------------------------------------------------------------------------- /src/docs/development/themes/templates.md: -------------------------------------------------------------------------------- 1 | Rendering Engine 2 | ================ 3 | 4 | How it works 5 | ------------ 6 | 7 | Every page has an associated API call, Template file, and Language File. 8 | 9 | For example, if you navigate to 10 | [/topic/351/nodebb-wiki](https://community.nodebb.org/topic/351/nodebb-wiki), 11 | the application will load three resources. The API return 12 | [/api/topic/351/nodebb-wiki](http://community.nodebb.org/api/topic/351/nodebb-wiki) 13 | and the [template](https://community.nodebb.org/templates/topic.tpl), in 14 | this example, "topic.tpl", and the appropriate [language 15 | file](https://community.nodebb.org/language/en-GB/topic.json) "topic.json"\*. 16 | 17 | Just prepend api/ to the URL's path name to discover the JSON return. 18 | Any value in that return can be utilized in your template. 19 | 20 | \*A page's name corresponds to the template and language's filename (ex. 21 | `http://domain.com/topic/xyz` correlates to `topic.tpl`). 22 | 23 | Templating Basics 24 | ----------------- 25 | 26 | Using the API return as your guide, you can utilize any of those values 27 | in your template/logic. Using the above API call as an example, for 28 | anything in the root level of the return you can do something like: 29 | 30 | ``` html 31 | {topic_name} 32 | ``` 33 | 34 | To access values in objects: 35 | 36 | ``` html 37 | {privileges.read} 38 | ``` 39 | 40 | And finally you can loop through arrays and create blocks like so: 41 | 42 | ``` html 43 | {{{ each posts }}} 44 | {posts.content} 45 | {{{ end }}} 46 | ``` 47 | 48 | The above will create X copies of the above block, for each item in the 49 | posts array. 50 | 51 | Templating Logic 52 | ---------------- 53 | 54 | NodeBB's templating system implements some basic logic. Using the same 55 | API call as above for our example. You can write IF conditionals like 56 | so: 57 | 58 | ``` html 59 | {{{ if unreplied }}} 60 | This thread is unreplied! 61 | {{{ end }}} 62 | ``` 63 | 64 | Another example: 65 | 66 | ``` html 67 | {{{ if !disableSocialButtons }}} 68 | 69 | {{{ else }}} 70 | Sharing has been disabled. 71 | {{{ end }}} 72 | ``` 73 | 74 | We can check for the length of an array like so: 75 | 76 | ``` html 77 | {{{ if posts.length }}} 78 | There be some posts 79 | {{{ end }}} 80 | ``` 81 | 82 | While looping through an array, we can check if our current index is the 83 | @first or @last like so: 84 | 85 | ``` html 86 | {{{ each posts }}} 87 | {{{ if @first }}} 88 |

Main Author: {posts.username}

89 | {{{ end }}} 90 | {posts.content} 91 | {{{ if @last }}} 92 | End of posts. Click here to scroll to the top. 93 | {{{ end }}} 94 | {{{ end }}} 95 | ``` 96 | 97 | For more advanced documentation, have a look at the 98 | [bencpressjs](https://github.com/benchpressjs/benchpressjs/tree/master/docs) repository 99 | 100 | Exposing template variables to client-side JavaScript 101 | ----------------------------------------------------- 102 | 103 | There are two ways of letting our JS know about data from the 104 | server-side, apart from WebSockets (TODO: will be covered in a different 105 | article). 106 | 107 | ### Via jQuery.get 108 | 109 | If we require data from a different page we can make a `$.get` call to 110 | any other API call. For example, if we wanted to know more about a 111 | specific user we could make a call like so: 112 | 113 | ``` js 114 | $.get(config.relative_path + '/api/user/psychobunny', {}, function(user) { 115 | console.log(user) 116 | }); 117 | ``` 118 | 119 | See this API call in action: 120 | 121 | 122 | ### Via Template Variables 123 | 124 | On every page the data used to render that page is avaiable in `ajaxify.data` 125 | For example on the topic page you can access the topic title with `ajaxify.data.title` or the category id with `ajaxify.data.cid` 126 | 127 | 128 | Internationalization 129 | -------------------- 130 | 131 | The template engine interfaces with the internationalization system as 132 | well. We can embed variables into language strings. Let's use [this API 133 | call](http://community.nodebb.org/api/register) as well as this 134 | [language 135 | file](http://community.nodebb.org/language/en-GB/register.json) as an 136 | example. We can now do something like the following: 137 | 138 | ``` html 139 | [[register:help.username_restrictions, {minimumUsernameLength}, {maximumUsernameLength}]] 140 | ``` 141 | 142 | Which will translate this string: 143 | 144 | ``` html 145 | A unique username between %1 and %2 characters 146 | ``` 147 | 148 | to 149 | 150 | ``` html 151 | A unique username between 2 and 16 characters 152 | ``` 153 | 154 | Advanced Topics 155 | --------------- 156 | 157 | ### Dynamically requiring and rendering a template file from client-side 158 | JavaScript 159 | 160 | The template engine lazy loads templates on an as-needed basis and 161 | caches them. If your code requires a template or partial on-demand then 162 | you can : 163 | 164 | ``` js 165 | ajaxify.loadTemplate('myTemplate', function(myTemplate) { 166 | var html = templates.parse(myTemplate, myData); 167 | }); 168 | ``` 169 | 170 | You can also access the invidual blocks inside each template, which is 171 | handy for doing things like (for example) rendering a new post's `
  • ` 172 | and dynamically sticking it in an already loaded `
      ` 173 | 174 | ``` html 175 | Some stuff here... 176 | {{{ each posts }}} 177 | We just want to pull this block only. 178 | {{{ end }}} 179 | ... some stuff here 180 | ``` 181 | 182 | ``` js 183 | ajaxify.loadTemplate('myTemplate', function(myTemplate) { 184 | var block = templates.getBlock(myTemplate, 'posts'); 185 | var html = templates.parse(block, myData); 186 | }); 187 | ``` 188 | 189 | ### Rendering templates on server-side Node.js 190 | 191 | The templating system hooks into Express just like most other templating 192 | frameworks. Just use either `app.render` or `res.render` to parse the 193 | appropriate template. 194 | 195 | ``` js 196 | res.render('myTemplate', myData); 197 | ``` 198 | 199 | ``` js 200 | app.render('myTemplate', myData, function(err, parsedTemplate) { 201 | console.log(parsedTemplate); 202 | }); 203 | ``` 204 | -------------------------------------------------------------------------------- /src/docs/configuring/scaling.md: -------------------------------------------------------------------------------- 1 | Scaling NodeBB 2 | ============== 3 | 4 | When it comes to maintaining many concurrent connections or high view 5 | rates, there are certain procedures that can be followed in order to 6 | streamline NodeBB. 7 | 8 | This article attempts to outline the various strategies that can be 9 | employed by those finding that NodeBB is not running as fast as it 10 | should under full load. 11 | 12 | Use a proxy server to serve static assets 13 | ----------------------------------------- 14 | 15 | Nginx is exceedingly good at serving static resources (e.g. javascript, 16 | css, images, etc). By allowing Nginx to take over the task of serving 17 | this to the end user, the NodeBB process(es) will be left to handle only 18 | the API calls, which substantially lowers the amount of work for NodeBB 19 | (and increases your throughput). 20 | 21 | Your Nginx config will need to be modified add the following `location` 22 | blocks: 23 | 24 | location @nodebb { 25 | proxy_pass http://127.0.0.1:4567; 26 | } 27 | 28 | location ~ ^/assets/(.*) { 29 | root /path/to/nodebb/; 30 | try_files /build/public/$1 /public/$1 @nodebb; 31 | } 32 | 33 | location / { 34 | proxy_pass http://127.0.0.1:4567; 35 | } 36 | 37 | Furthermore, you can instruct Nginx to serve these assets compressed: 38 | 39 | gzip on; 40 | gzip_min_length 1000; 41 | gzip_proxied off; 42 | gzip_types text/plain application/xml text/javascript application/javascript application/x-javascript text/css application/json; 43 | 44 | Utilise clustering 45 | ------------------ 46 | 47 | By default, NodeBB will run on one process, and certain calls may take 48 | longer than others, resulting in a lag or queue for the same resources. 49 | To combat this, you can instruct NodeBB to run on multiple processes by 50 | adding the `port` property into your `config.json`: 51 | 52 | { 53 | "port": ["4567", "4568", "4569"] // will start three processes 54 | } 55 | 56 | Keep in mind you need to start nodebb with `node loader.js` or 57 | `./nodebb start` so that 3 workers can be spawned. Using `node app.js` will 58 | only use the first port in the array. 59 | 60 | A proxy server like Nginx is required in order to load balance requests 61 | between all of the servers. Add an `upstream` block to your config: 62 | 63 | upstream io_nodes { 64 | ip_hash; 65 | server 127.0.0.1:4567; 66 | server 127.0.0.1:4568; 67 | server 127.0.0.1:4569; 68 | } 69 | 70 | ... and alter the `proxy_pass` directive in your `location /` block to read: `proxy_pass http://io_nodes;` 71 | 72 | Sample Nginx configuration with all of the above applied 73 | -------------------------------------------------------- 74 | 75 | upstream io_nodes { 76 | ip_hash; 77 | server 127.0.0.1:4567; 78 | server 127.0.0.1:4568; 79 | server 127.0.0.1:4569; 80 | } 81 | 82 | server { 83 | listen 80; 84 | 85 | server_name community.nodebb.org; 86 | 87 | proxy_set_header X-Real-IP $remote_addr; 88 | proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 89 | proxy_set_header Host $http_host; 90 | proxy_set_header X-NginX-Proxy true; 91 | proxy_redirect off; 92 | 93 | # Socket.io Support 94 | proxy_http_version 1.1; 95 | proxy_set_header Upgrade $http_upgrade; 96 | proxy_set_header Connection "upgrade"; 97 | 98 | gzip on; 99 | gzip_min_length 1000; 100 | gzip_proxied off; 101 | gzip_types text/plain application/xml text/javascript application/javascript application/x-javascript text/css application/json; 102 | 103 | location @nodebb { 104 | proxy_pass http://io_nodes; 105 | } 106 | 107 | location ~ ^/assets/(.*) { 108 | root /path/to/nodebb/; 109 | try_files /build/public/$1 /public/$1 @nodebb; 110 | } 111 | 112 | location / { 113 | proxy_pass http://io_nodes; 114 | } 115 | } 116 | 117 | Configure Redis 118 | --------------- 119 | 120 | When you setup NodeBB to use more than one process, Redis needs to be configured alongside your primary data store. Each NodeBB process can communicate with the others through Redis pub-sub. Install Redis on your server and add a `redis` block to your config.json. A sample `config.json` that uses mongodb as datastore and Redis for pubsub looks like this. 121 | 122 | { 123 | "url": "http://example.org", 124 | "secret": "your-secret-goes-here", 125 | "database": "mongo", 126 | "port": [4567, 4568,4569], 127 | "mongo": { 128 | "host": "127.0.0.1", 129 | "port": "27017", 130 | "database": "0" 131 | }, 132 | "redis": { 133 | "host":"127.0.0.1", 134 | "port":"6379", 135 | "database": 0 136 | } 137 | } 138 | 139 | When configured like so, Redis will also be used as the session store. Outside of user session data and message passing between processes, no other data is stored on Redis, and so it is not necessary that it be backed up. If the database is lost, then existing user sessions will no longer be valid, and users will have to log in again. 140 | 141 | ## Handling Duplicate Digests, etc. 142 | 143 | By default, each NodeBB instance assumes it is acting alone and runs scheduled jobs such as pruning notifications and sending out email digests. NodeBB will know if it is part of a local fleet (that is, if NodeBB is running on multiple ports as configured in `config.json`) and act accordingly, but if it is part of a horizontally scaled setup, it won't proactively communicate with its neighbours and elect a primary server. 144 | 145 | In that event, all but one server should have its `config.json` updated to contain an additional config property: `jobsDisabled`. When set to `true`, it will disable these jobs, and so they will only be run on the one server. 146 | 147 | **Note**: If your setup consists of multiple machines each running a single instance of NodeBB (one port), then you will also need to set `isCluster` to `true`. 148 | 149 | For more information, see [our article on `config.json`](./config.md). -------------------------------------------------------------------------------- /src/docs/development/plugins/hooks.md: -------------------------------------------------------------------------------- 1 | // TODO ASYNC hooks 2 | 3 | # Available Hooks 4 | 5 | The following is a list of all hooks present in NodeBB. This list is intended to guide developers who are looking to write plugins for NodeBB. For more information, please consult Writing Plugins for NodeBB <create>. 6 | 7 | Most of the time, when you want to integrate with NodeBB, you'll want to _hook_ into some part of NodeBB's internal processing. This is done by attaching a _listener_ from your plugin, via our plugin hook system. There are four types of hooks, **filters**, **actions**, **static**, and **response** hooks. 8 | 9 | ## Filter hooks 10 | 11 | **Filters** act on content, and can be useful if you want to alter certain pieces of content as it passes through NodeBB. 12 | 13 | For example, a filter may be used to alter posts so that any occurrences of "apple" gets changed to "orange". Likewise, filters may be used to beautify content (i.e. code filters), or remove offensive words (profanity filters). 14 | 15 | Most filter hooks called from NodeBB will pass a single argument in the form of an object, and you **must** send back your return payload in the same schema, as multiple plugins could be listening to the same hook, and expect the same object schema. We don't enforce that you send back the *exact same object*, but that is encouraged as well. 16 | 17 | NodeBB will execute all of the registered listeners _sequentially_, and wait for all of them to return data back (transformed or not) before continuing onwards with execution. 18 | 19 | ## Action hooks 20 | 21 | **Actions**, true to their name, are executed when NodeBB does a certain action. They are useful if you'd like to *do* something asynchronously after a certain trigger. 22 | 23 | For example, an action hook can be used to notify an admin if a certain user has posted. Other uses include analytics recording, or automatic welcome posts on new user registration. 24 | 25 | Action hooks may or may not contain a data payload for processing, but NodeBB will explicitly not care what comes back (and will not use the data that comes back) 26 | 27 | NodeBB will execute all registered listeners for an action hook at once, and **not wait for a response** before continuing onwards. If you need NodeBB to wait, you want a filter/static hook. 28 | 29 | ## Static hooks 30 | 31 | **Static** hooks are executed and wait for you to do something before continuing. They're similar to action hooks, but whereas execution in NodeBB continues immediately after an action is fired, static hooks grant you a bit of time to run your own custom logic, before resuming execution. 32 | 33 | NodeBB will pass in a data payload, and execute all registered listeners at once. It will wait for all of the listeners to return (or execute the return callback) before continuing onwards 34 | 35 | ## Response hooks 36 | 37 | **Response** hooks are executed serially and are similar to action hooks _up until one of the listeners sends a response to the client_. In that event, the plugin hooks that come afterward are skipped completely, including the default response from core. 38 | 39 | Response hooks are used in situatons where one or more plugins may elect to send an error to the client, or redirect them somewhere else. Response hooks are structured in a way so that conflicts are avoided. 40 | 41 | Admittely, there are few response hooks in NodeBB. The only one in core is `response:middleware.authenticate`, which allows a plugin to add their own authentication strategies to protected routes. In this scenario, NodeBB passes in `req` and `res`, much like a middleware would, and a plugin can elect to respond or not. NodeBB checks whether headers were sent, and continues onwards if a response wasn't already sent to the client. 42 | 43 | For example, if a user accesses a protected route, NodeBB fires off `response:middleware.authenticate` for non-logged-in users, and if nothing was done, continues with the default action, which is to show the "Not Allowed" page. 44 | 45 | ## List of hooks 46 | 47 | Please consult the [**autogenerated list of hooks**](https://github.com/NodeBB/NodeBB/wiki/Hooks/). The aforementioned list is automatically generated from the NodeBB codebase and is not guaranteed to be complete at all times. 48 | 49 | ## Special Hooks 50 | 51 | There are a number of special hooks that are included in the NodeBB codebase that are not explicitly called out in the autogenerated hooks page. They are included below as they are either a) useful, or b) difficult to understand given its context. 52 | 53 | ### Page Build Hooks 54 | 55 | In addition to hooks executed on certain actions, a pair of hooks are also fired whenever a page is loaded (either via direct page access, or via a page transition): 56 | 57 | * `filter: