Files
NodeBB/README.md

85 lines
5.6 KiB
Markdown
Raw Permalink Normal View History

# ![NodeBB](public/images/sm-card.png)
2015-07-21 11:23:16 -04:00
2021-11-10 15:33:15 -05:00
[![Workflow](https://github.com/NodeBB/NodeBB/actions/workflows/test.yaml/badge.svg)](https://github.com/NodeBB/NodeBB/actions/workflows/test.yaml)
2016-10-16 22:54:31 +03:00
[![Coverage Status](https://coveralls.io/repos/github/NodeBB/NodeBB/badge.svg?branch=master)](https://coveralls.io/github/NodeBB/NodeBB?branch=master)
2015-07-21 11:23:16 -04:00
[![Code Climate](https://codeclimate.com/github/NodeBB/NodeBB/badges/gpa.svg)](https://codeclimate.com/github/NodeBB/NodeBB)
2022-11-04 19:34:33 -04:00
[![](https://dcbadge.vercel.app/api/server/p6YKPXu7er?style=flat)](https://discord.gg/p6YKPXu7er)
2015-07-21 11:23:16 -04:00
2021-11-12 15:23:41 -05:00
[**NodeBB Forum Software**](https://nodebb.org) is powered by Node.js and supports either Redis, MongoDB, or a PostgreSQL database. It utilizes web sockets for instant interactions and real-time notifications. NodeBB takes the best of the modern web: real-time streaming discussions, mobile responsiveness, and rich RESTful read/write APIs, while staying true to the original bulletin board/forum format → categorical hierarchies, local user accounts, and asynchronous messaging.
2015-07-21 11:23:16 -04:00
2021-11-12 15:23:41 -05:00
NodeBB by itself contains a "common core" of basic functionality, while additional functionality and integrations are enabled through the use of third-party plugins.
2015-07-21 11:23:16 -04:00
2021-11-12 15:26:00 -05:00
### [Try it now](//try.nodebb.org) | [Documentation](//docs.nodebb.org)
2015-07-21 11:23:16 -04:00
## Screenshots
2016-11-24 11:30:45 -05:00
NodeBB's theming engine is highly flexible and does not restrict your design choices. Check out some themed installs in these screenshots below:
2015-07-21 11:23:16 -04:00
[![](http://i.imgur.com/VCoOFyqb.png)](http://i.imgur.com/VCoOFyq.png)
[![](http://i.imgur.com/FLOUuIqb.png)](http://i.imgur.com/FLOUuIq.png)
[![](http://i.imgur.com/Ud1LrfIb.png)](http://i.imgur.com/Ud1LrfI.png)
[![](http://i.imgur.com/h6yZ66sb.png)](http://i.imgur.com/h6yZ66s.png)
[![](http://i.imgur.com/o90kVPib.png)](http://i.imgur.com/o90kVPi.png)
[![](http://i.imgur.com/AaRRrU2b.png)](http://i.imgur.com/AaRRrU2.png)
[![](http://i.imgur.com/LmHtPhob.png)](http://i.imgur.com/LmHtPho.png)
[![](http://i.imgur.com/paiJPJkb.jpg)](http://i.imgur.com/paiJPJk.jpg)
Our minimalist "Harmony" theme gets you going right away, no coding experience required.
2016-08-15 20:21:32 +03:00
![Rendering of a NodeBB install on desktop and mobile devices](https://user-images.githubusercontent.com/923011/228570420-2a4db745-b20d-474a-a571-1b59259508ef.png)
2015-07-21 11:23:16 -04:00
## How can I follow along/contribute?
* If you are a developer, feel free to check out the source and submit pull requests. We also have a wide array of [plugins](http://community.nodebb.org/category/7/nodebb-plugins) which would be a great starting point for learning the codebase.
* If you are a designer, [NodeBB needs themes](http://community.nodebb.org/category/10/nodebb-themes)! NodeBB's theming system allows extension of the base templates as well as styling via SCSS or CSS. NodeBB's base theme utilizes [Bootstrap 5](http://getbootstrap.com/) as a frontend toolkit.
* If you know languages other than English you can help us translate NodeBB. We use [Transifex](https://explore.transifex.com/nodebb/nodebb/) for internationalization.
2015-07-21 11:23:16 -04:00
* Please don't forget to **like**, **follow**, and **star our repo**! Join our growing [community](http://community.nodebb.org) to keep up to date with the latest NodeBB development.
## Requirements
NodeBB requires the following software to be installed:
2025-05-07 11:28:33 -04:00
* A version of Node.js at least 20 or greater ([installation/upgrade instructions](https://github.com/nodesource/distributions))
2025-06-18 13:25:36 -04:00
* MongoDB, version 5 or greater **or** Redis, version 7.2 or greater
* If you are using [clustering](https://docs.nodebb.org/configuring/scaling/) you need Redis installed and configured.
2015-07-21 11:23:16 -04:00
* nginx, version 1.3.13 or greater (**only if** intending to use nginx to proxy requests to a NodeBB)
## Installation
feat: docker improvements (#12031) * use yarn and debian slim build * feat: update Dockerfile to use multistage builds * Create main.yml * remove some useless things from docker context and assume yarn by default * remove all dotfiles in docker context * no need for extra build tools, complain to the module author if there is no alpine build (cherry picked from commit 90516a3c8399e74c38be7115edb39411ba0d86b9) * specify the config file location instead of creating it (cherry picked from commit 38e4295d70682f1049fe671ade96eeccd669d908) * set explicit config path (cherry picked from commit 8dcc6f249d099cb8939a95511ec13702491958bc) * fix docker-compose example to use the exposed volumes * dockerfile: upgrade alpine to 3.16 * dockerignore: add more ignorable entries * docker-compose: change the way the docker startup process works * install: pass config path to child process as well Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * setup: move config file resolution up before setup This fixes issue with different config file location, which will otherwise default on 'config.json', which means the config save won't save to the file we specified Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-entrypoint: don't fix CONFIG_DIR location but fix default location Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-entrypoint: handle missing config file logic Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * README: add simple notice on how to use it Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * add missing semicolons Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-compose: remove multi override, use one big profile instead However, Docker Compose doesn't support profile-based dependency and this would probably means we have less guarantee about the liveness of the database. But since this is just a sample configuration it should be fine Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * workflows: remove main.yml, add platforms to buildx matrix in docker.yml Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * workflows: set docker buildx to build for amd64 and arm64 only Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-entrypoint: don't force build everytime before start Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-entrypoint: implement init verb This would allow you to change between "setup" (automated setup using environmental variables which is the current preferred way to run containerized NodeBB) or "install" (web install that guides user to fill in connection information, which is similar to WordPress) Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * README: mention caveat with MongoDB Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * README: add Docker section placeholder for doc migration Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-entrypoint: add SETUP variable support Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-compose: add force flag to ln on setup Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-compose: fix permission issue; docker-compose: fast exit if still no permission on config dir Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * fix: remove redundant FROM * docs: remove docker stuff (in favour of docs entry, nodebb/docs#78) but add link to cloud install docs * fix: correctly check if directory is writable * fix: ignore .docker directory * fix: multi-arch docker builds and chown performance * chore: bump database image versions * fix: move from alpine to slim image * fix: use omit=dev instead of only=prod * feat: move entrypoint to install directory * feat: initialize mongodb user * feat: use separate rebuild stage * fix: disable eslint for mongodb script * fix: remove node_modules bind mount bind mounts don't save data from container, resulting in a LOONG startup * feat: prepopulate database defaults for installation * feat: enable persistence in redis container * docs: add some comments to the compose file --------- Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> Co-authored-by: Steve Fan <29133953+stevefan1999-personal@users.noreply.github.com> Co-authored-by: Steve Fan <19037626d@connect.polyu.hk> Co-authored-by: Julian Lam <julian@nodebb.org>
2023-11-12 19:38:00 +01:00
[Please refer to platform-specific installation documentation](https://docs.nodebb.org/installing/os).
If installing via the cloud (or using Docker), [please see cloud-based installation documentation](https://docs.nodebb.org/installing/cloud/).
2015-07-21 11:23:16 -04:00
## Securing NodeBB
It is important to ensure that your NodeBB and database servers are secured. Bear these points in mind:
1. While some distributions set up Redis with a more restrictive configuration, Redis by default listens to all interfaces, which is especially dangerous when a server is open to the public. Some suggestions:
* Set `bind_address` to `127.0.0.1` so as to restrict access to the local machine only
* Use `requirepass` to secure Redis behind a password (preferably a long one)
* Familiarise yourself with [Redis Security](http://redis.io/topics/security)
2. Use `iptables` to secure your server from unintended open ports. In Ubuntu, `ufw` provides a friendlier interface to working with `iptables`.
* e.g. If your NodeBB is proxied, no ports should be open except 80 (and possibly 22, for SSH access)
feat: docker improvements (#12031) * use yarn and debian slim build * feat: update Dockerfile to use multistage builds * Create main.yml * remove some useless things from docker context and assume yarn by default * remove all dotfiles in docker context * no need for extra build tools, complain to the module author if there is no alpine build (cherry picked from commit 90516a3c8399e74c38be7115edb39411ba0d86b9) * specify the config file location instead of creating it (cherry picked from commit 38e4295d70682f1049fe671ade96eeccd669d908) * set explicit config path (cherry picked from commit 8dcc6f249d099cb8939a95511ec13702491958bc) * fix docker-compose example to use the exposed volumes * dockerfile: upgrade alpine to 3.16 * dockerignore: add more ignorable entries * docker-compose: change the way the docker startup process works * install: pass config path to child process as well Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * setup: move config file resolution up before setup This fixes issue with different config file location, which will otherwise default on 'config.json', which means the config save won't save to the file we specified Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-entrypoint: don't fix CONFIG_DIR location but fix default location Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-entrypoint: handle missing config file logic Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * README: add simple notice on how to use it Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * add missing semicolons Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-compose: remove multi override, use one big profile instead However, Docker Compose doesn't support profile-based dependency and this would probably means we have less guarantee about the liveness of the database. But since this is just a sample configuration it should be fine Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * workflows: remove main.yml, add platforms to buildx matrix in docker.yml Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * workflows: set docker buildx to build for amd64 and arm64 only Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-entrypoint: don't force build everytime before start Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-entrypoint: implement init verb This would allow you to change between "setup" (automated setup using environmental variables which is the current preferred way to run containerized NodeBB) or "install" (web install that guides user to fill in connection information, which is similar to WordPress) Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * README: mention caveat with MongoDB Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * README: add Docker section placeholder for doc migration Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-entrypoint: add SETUP variable support Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-compose: add force flag to ln on setup Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * docker-compose: fix permission issue; docker-compose: fast exit if still no permission on config dir Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> * fix: remove redundant FROM * docs: remove docker stuff (in favour of docs entry, nodebb/docs#78) but add link to cloud install docs * fix: correctly check if directory is writable * fix: ignore .docker directory * fix: multi-arch docker builds and chown performance * chore: bump database image versions * fix: move from alpine to slim image * fix: use omit=dev instead of only=prod * feat: move entrypoint to install directory * feat: initialize mongodb user * feat: use separate rebuild stage * fix: disable eslint for mongodb script * fix: remove node_modules bind mount bind mounts don't save data from container, resulting in a LOONG startup * feat: prepopulate database defaults for installation * feat: enable persistence in redis container * docs: add some comments to the compose file --------- Signed-off-by: steve <29133953+stevefan1999-personal@users.noreply.github.com> Co-authored-by: Steve Fan <29133953+stevefan1999-personal@users.noreply.github.com> Co-authored-by: Steve Fan <19037626d@connect.polyu.hk> Co-authored-by: Julian Lam <julian@nodebb.org>
2023-11-12 19:38:00 +01:00
2015-07-21 11:23:16 -04:00
## Upgrading NodeBB
Detailed upgrade instructions are listed in [Upgrading NodeBB](https://docs.nodebb.org/configuring/upgrade/)
2015-07-21 11:23:16 -04:00
## License
NodeBB is licensed under the **GNU General Public License v3 (GPL-3)** (http://www.gnu.org/copyleft/gpl.html).
2015-09-04 21:26:26 -04:00
Interested in a sublicense agreement for use of NodeBB in a non-free/restrictive environment? Contact us at sales@nodebb.org.
2021-11-12 15:23:41 -05:00
## More Information/Links
* [Demo](https://try.nodebb.org)
* [Developer Community](http://community.nodebb.org)
* [Documentation & Installation Instructions](https://docs.nodebb.org)
* [Help translate NodeBB](https://explore.transifex.com/nodebb/nodebb/)
* [NodeBB Blog](https://nodebb.org/blog)
* [Premium Hosting for NodeBB](https://www.nodebb.org/ "NodeBB")
2021-11-12 15:23:41 -05:00
* Unofficial IRC community &ndash; channel `#nodebb` on Libera.chat
* [Follow us on Twitter](http://www.twitter.com/NodeBB/ "NodeBB Twitter")
2021-11-17 13:20:07 -05:00
* [Like us on Facebook](http://www.facebook.com/NodeBB/ "NodeBB Facebook")