184 lines
7.1 KiB
Markdown
184 lines
7.1 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 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
|