Setup project skeletonHEADmaster

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).