diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..43fb259 --- /dev/null +++ b/README.md @@ -0,0 +1,176 @@ +# nanobbs, a tiny forums software + +`nanobbs` is a simple and lightweight implementation of a forums software, +commonly known as "bulletin board software" or simply "BBS", written in C99 +plus POSIX.1-2008 extensions. + +## Disclaimer + +Intentionally, `nanobbs` does not share some of the philosophical views from the +[suckless project](https://suckless.org). However, it still strives towards +portability, minimalism, simplicity and efficiency. + +## Features + +- No JavaScript. +- Typical forums software features: categories, sections, topics and posts. +- Create/delete users from the web interface. +- Uses [`libweb`](https://gitea.privatedns.org/xavi/libweb), a tiny web framework. +- Uses [`libsodium`](https://www.libsodium.org/) as its cryptography backend. +- Uses [SQLite](https://sqlite.org/) as its database backend. + +### TLS + +In order to maintain simplicity and reduce the risk for security bugs, `nanobbs` +does **not** implement TLS support. Instead, this should be provided by a +reverse proxy, such as [`caddy`](https://caddyserver.com/). + +### Root permissions + +`nanobbs` is expected to listen to connections from any port number so that `root` +access is not required. So, in order to avoid the risk for security bugs, +**please do not run `nanobbs` as `root`**. + +## Requirements + +- A POSIX environment. +- [`libsodium`](https://www.libsodium.org/). +- [SQLite](https://sqlite.org/) >= 3.0.0 (tentative). +- [`dynstr`](https://gitea.privatedns.org/xavi/dynstr) +(provided as a `git` submodule by `libweb`). +- [`libweb`](https://gitea.privatedns.org/xavi/libweb) +(provided as a `git` submodule). +- CMake (optional). + +### Ubuntu / Debian + +#### Mandatory packages + +```sh +sudo apt install build-essential libsqlite3-dev libsodium-dev +``` + +#### Optional packages + +```sh +sudo apt install cmake +``` + +## How to use +### Build + +Two build environments are provided for `nanobbs` - feel free to choose any of +them: + +- A [`configure`](configure) POSIX shell and mostly POSIX-compliant +[`Makefile`](Makefile). +- A [`CMakeLists.txt`](CMakeLists.txt). + +`nanobbs` can be built using the standard build process: + +#### Make + +```sh +$ ./configure +$ make +``` + +#### CMake + +```sh +$ cmake -B build +$ cmake --build build/ +``` + +### Setting up + +`nanobbs` consumes a path to a directory with the following tree structure: + +``` +. +├── nanobbs.db +├── style.css +└── TERMS +``` + +Where: + +- `nanobbs.db` is the SQLite database. + - **Note:** `nanobbs` creates a database with one administrator account, + namely `admin`, if not found, with file mode bits set to `0600`. +- `style.css` is the site stylesheet. It can be freely modified. + - **Note:** `nanobbs` creates a default stylesheet file, if not found. +- `TERMS` is a text file containing the terms of service for the instance. +It can be freely modified. + - **Note:** `nanobbs` creates a default terms file, if not found. + +**Note:** `nanobbs` creates the given directory if it does not exist. + +### Running + +To run `nanobbs`, simply run the executable with the path to a directory including +the files listed above. By default, `nanobbs` will listen to incoming connections +on a random TCP port number. To set a specific port number, use the `-p` +command line option. For example: + +```sh +nanobbs -p 7822 ~/my-db/ +``` + +`nanobbs` requires a temporary directory where files uploaded by users are +temporarily stored until moved to the user directory. By default, `nanobbs` +attempts to retrieve the path to the temporary directory by inspecting the +`TMPDIR` environment variable, and falls back to `/tmp` if undefined. + +If a custom temporary directory is required, it can be defined via command +line option `-t`. For example: + +```sh +nanobbs -t ~/my-tmp -p 7822 ~/my-db +``` + +**Note:** system-level temporary directories such as `/tmp` might reside +on a filesytem different than the one where the database resides. This +would force `nanobbs` to copy the contents from uploaded files from the +temporary directory to the database, which might be an expensive operation. +Therefore, in order to avoid expensive copies, define a custom temporary +directory that resides on the same filesystem. + +## Why this project? + +When looking up a forums software for +[Speed Dreams](https://www.speed-dreams.net/), traditional forums software +solutions had been considered, such as [phpBB](https://www.phpbb.com/), +[myBB](https://mybb.com/) or [Discourse](https://www.discourse.org/), +yet raised concerns related to perceived software bloat and/or excessive +use of client-side JavaScript. + +As of the time of this writing, there was no forums software written in C +other than `nanobbs`, +[according to Wikipedia](https://en.wikipedia.org/wiki/Comparison_of_Internet_forum_software). +Since [`slcl`](https://gitea.privatedns.org/xavi/slcl), another project with +the same philosophy, was motivated by similar goals back then, `nanobbs` was seen +as a good opportunity to show how a solution written in C can be both simple, +efficient and safe. + +## License + +``` +nanobbs, a tiny forums software. +Copyright (C) 2025-2026 Xavier Del Campo Romero + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU Affero General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU Affero General Public License for more details. + +You should have received a copy of the GNU Affero General Public License +along with this program. If not, see <https://www.gnu.org/licenses/>. +``` + +Also, see [`LICENSE`](LICENSE). |