threadr.lostcave.ddnss.de/README.md

# Welcome to ThreadR

This is the source code for the ThreadR Forum Engine.

The project originated as a school project with the goal of developing
a mix between a forum engine and a social media platform.
When school was over, we left the project up for some time with the
general intention to continue working on it until I took it down after
an extended period of inactivity to host my own website on my server.

Now, that it is being revived, the original scope of the project
doesn’t really make sense anymore (at least to me) so it needs to shift
slightly.
Below is a list of goals that I would like to see achieved, feel free
to discuss this in the issues or commit comments.

- [x] come back online (see issue #2)
- [x] go FOSS (make the source code publicly available under a FOSS license (see issue #5))
- [x] make the code portable so everyone can set up their own instance
- [ ] get generic forum functionality going (sign-up, creation of boards, creation of threads within boards, messages, profiles)

Once these two are given, here are some additional goals both from
the original scope of the project as well as my own ideas.
Input is welcome.

- [ ] anonymous posts (users can choose to post anonymously, registered users will have a unique name per thread that stays the same so users can tell each other apart)
- [ ] subscribing to threads
- [ ] "split thread here" feature (kinda like on Reddit when multiple ppl answer to one person)
- [ ] automatic loading of new messages in threads (opt-out in settings)
- [ ] notifications for new messages in subscribed threads (opt-out in settings)
- [ ] question threads with an "accept answer" feature, threads can be marked as question threads on creation
- [ ] like/dislike feature but in better (as in more limited in functionality and more nuanced, kinda like on StackExchange but with two types of likes/dislikes and without showing an actual number)

\- BodgeMaster

UPDATE: The ThreadR Forum Engine is now technically host-independent.
By default, it still contains the configuration for our test instance
but all host-dependent setup information is configurable now.
It is still heavily WIP.

# Installation

First of all, keep in mind that the ThreadR Forum Engine is still
in early development and things are subject to change.

For now, the only way to set up an instance is doing it the manual way;
automatic setup might be added in the future.

This setup guide is assuming that you are on a UNIX-like system
and have the following already installed and set up properly:

- Apache with PHP (will most likely also work on other web servers)
- MySQL or MariaDB
- Python 3
- Bash

Installation:

- To install the ThreadR Forum Engine, clone this repository into a directory that the web server has access to but that it outside of any web root.
- Add a database to your MySQL/MariaDB server that contains the tables shown below.
- Create a MySQL/MariaDB user for ThreadR and grant usage privileges for the tables to it.
- Symlink the directory `build/` to your desired location on the web root. ThreadR does not support being linked directly to the webroot.
- adjust the files in `config/` to your setup
- run ./deployment-script.sh to apply configuration
- Optionally symlink `build/redirect_home.html` to all places that you want to redirect to ThreadR.

Database tables:
- boards
  - `id` (int, primary key, auto increment)
  - `name` (varchar)
  - `user_friendly_name` (varchar)
  - `private` (boolean or tinyint(1))
  - `public_visible` (boolean or tinyint(1))
- posts
  - `id` (int, primary key, auto increment)
  - `board_id` (int)
  - `user_id` (int)
  - `post_time` (timestamp, default current_timestamp())
  - `edit_time` (timestamp, may be null, default null, on update current_timestamp())
  - `content` (text, may be null, default null)
  - `attachment_hash` (bigint(20), may be null, default null)
  - `attachment_name` (varchar, may be null, default null)
  - `title` (varchar)
  - `reply_to` (int, default -1)
- profiles (do we even use this?)
  - `id` (smallint (why? this makes no sense whatsoever), primary key, index (why? probably wanted to do unique))
  - `email` (varchar, index (I think that’s supposed to be unique?))
  - `display_name` (varchar)
  - `status` (varchar)
  - `about` (very long varchar)
  - `website` (varchar)
- users
  - `id` (smallint (again, this makes no sense), primary key)
  - `name` (varchar, index (again, that’s probably supposed to be unique))
  - `authentication_string` (varchar(128))
  - `authentication_salt` (varchar)
  - `authentication_algorithm` (varchar)
  - `time_created` (timestamp, default current_timestamp())
  - `time_altered` (timestamp, default current_timestamp(), on update current_timestamp())
  - `verified` (boolean or tinyint(1), default 0)

# Git based automatic web deployment system
This repository will be automagically pulled by the test server
each time something is pushed by a user.

Dear Developers,
Please use pushes sparingly because it takes a while for the server
to replace all code variables.

What this thing does basically equates to:
```
ssh <user>@<threadr.ip|no public access set up currently>
cd /var/www/git
sudo -u www-data -s
rm -rf ./web-deployment
git clone <ssh git repository link>
cd web-deployment
./deployment-script
exit
logout
```
TBD: Remove this section when the ThreadR project moves to its final home
and this repository is only used for our local setup.

## Symlinks
The following files and directories are linked to areas where they can be
accessed by the web server:
  * `build/` → `threadr.lostcave.ddnss.de/` (all files acessible by the web server, READMEs get deleted on deployment)

# Individual documentation for each file

### [[DIR] src](./src)

This folder contains all the files that are parts of ThreadR directly

### [[DIR] build](./build)

Placeholder folder to link against, will be deleted and recreated by
the deployment script, contains the a working instance of ThreadR after
successful execution of the deployment script

### [[DIR] config](./config)

A place to store the configuation for a specific ThreadR instance
(contains official instance config for now, will be removed and replaced
with a generic config eventually)

### [[DIR] macros](./macros)

files for use with variable_grabbler.py

### [deployment_script.sh](./deployment_script.sh)

This script is executed each time (or most of the time) the repository
gets pushed. It contains the commands to execute the code variable
replcement system and some other useful tasks. Its working directory is
the root of the git repository.

### [LICENSE.md](./LICENSE.md)

A copy of the Apache 2.0 license, the license this project is under

### [NOTICE](./NOTICE)

Copyright notice in plain text format

### [README.md](./README.md)

this file

### [variable_grabbler.py](./variable_grabbler.py)

Custom macro processor, takes two arguments:
- macro declaration file
- the file to be processed

Macros in code are strings of capitalized characters prefixed and
suffixed with %.

Macro definition format: JSON
- "<MACRO>":"<text>" → direct replacement
- "<MACRO>":["file","<file path>"] → insert file
- "<MACRO>":["exec","<command>"] → run command and insert its output from stdout