136 lines
7.2 KiB
Markdown
136 lines
7.2 KiB
Markdown
# 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 local instance but all host-dependent stup 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 will 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.
|
||
- Symlink the directory `build/` to your desired location on the 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.
|
||
- adjust the files in `config/` to your setup
|
||
- run ./deployment-script.sh to apply configuration
|
||
|
||
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 web 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 moved elsewhere 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 and 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
|
||
|
||
~~NOTICE: This file (or rather a more up-to-date version of it) will be moved to a new repository containing the deployment system.~~
|
||
I haven’t exactly figured out how to handle this in the future. It is absolutely necessary to deploy a ThreadR instance because it is used to configure ThreadR so we need a copy of it here.
|