threadr.lostcave.ddnss.de/README.md

122 lines
8.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# Welcome to ThreadR
This is the source code for the ThreadR Forum Engine. It 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 doesnt 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.
- [ ] come back online (see issue #2)
- [ ] go FOSS (make the source code publicly available under a FOSS license (see issue #5) and preferably usable for everyone to host an instance)
- [ ] get generic forum functionality going (creation of boards, creation of threads within boards, messages)
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
# WARNING
~~All information below is only relevant for documentation purposes.~~ This is a backup of the ThreadR project. A backup of the databases has been saved to `ThreadR.sql` and `web.sql`.
Update: This project will (hopefully) be brought back to life in its now home - here. This warning will be removed once the new box is set up with ThreadR in its current state.
# 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 the ToDo list below~~ please put ToDos on Issues with a *ToDo* label. You do not need need to create your own lists. This will allow others to work on things without collecting all the ToDos first. **Thank you.**
## Symlinks
The following files and directories are linked to areas where they can be accessed by the web server:
* `index.html``*/common/index.html` (http redirect)
* `icon.png``*/common/icon.png` (unused)
* `threadr/``*/common/threadr/` (everything else acessible by the web server)
* `default.html``lostcave.ddnss.de/index.html` (http redirect)
* `admin.php``admin.strassenkind.ip/index.php` (future management page, maybe for services, available sites, users, etc?)
* `strassenkind.php``strassenkind.ip/index.php` (status page)
* `commands_status.conf``strassenkind.ip/commands_status.conf`
* `commands_ondemand.conf``strassenkind.ip/commands_ondemand.conf`
* `internal.css``strassenkind.ip/style.css`
## Variables handled by the deployment script
~~Here is the place for variables that will be replaced automatically on the server. Using them is encouraged. Using the paths is DISCOURAGED.
This way, it is possible to change folder names around and fix the URLs in one place for all files simultaneously.~~
This section has moved. Look in the files or their documentation below.
## Some server variables that might turn out to be useful (example):
```
{
"HTTP_USER_AGENT":"Mozilla\/5.0 (X11; Ubuntu; Linux x86_64; rv:73.0) Gecko\/20100101 Firefox\/73.0",
"REMOTE_ADDR":"10.1.1.3"
}
```
# Individual documentation for each file
### policies [DIR]
This folder contains the documents from which our policy pages (privacy policy, TOS, etc) will be built in the future.
### threadr [DIR]
This folder contains all the files that are parts of ThreadR directly
### admin.php
This is the file that is shown on the internal admin page. It will contain a list of users, forums, threads, etc.
At the moment, it is just a convenient way to access the other internal administration tools.
This is not directly a part of ThreadR.
### default.html
The main index.html on the server. It redirects to ThreadR.
### deployment_script.sh
This script is executed each time (well... if Gitea decides to actually run the WebHook) 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.
If you want to know more: It is commented. Just look at it.
### icon.png
Well, thats a story about developers looking at the documentation and realizing what this is for...
I (Jan) intended it as the icon file for the tab icon but some folks put another icon elsewhere. Just ignore it. Maybe, one time, I will find a use for it.
### index.html
This was originally intended to be our index file. Turns out, we even need PHP on our index, so this one became another redirect to the new ThreadR index.php.
### strassenkind.php, internal.css, commands_status.conf, commands_ondemand.conf, commands_git.conf
The internal status page. strassenkind.php is the index, internal.css is the stylesheet strassenkind.php uses
and the .conf files are lists of commands to be executed by the status page. The status page auto-refreshes to display up-to-date information on the commands in commands_status.conf.
It is advised to put commands that have a high disk usage or start/stop/restart/reload system services etc. on the commands_ondemand.conf file as the ondemand status page does not auto-refresh.
The file commands_git.conf contains the commands that would be executed by the deployment WebHook. These are there to provide a fast and simple backup solution.
The alternative to foce-updating ThreadR via the status page would be:
```
ssh <user>@<strassenkind.ip|lostcave.ddnss.de>
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
```
### README.md
this file
### run-once-script.sh
This script will be executed each time it is altered and pushed. Make sure to remove everything the previous user added before using it to not run these commands again.
Leave the bang (#! comment) and the bottom part that has been commented to instruct you to leave it there.
### variable_grabbler.py
This is the code variable replacer. It takes two arguments: The configuration file to be used and the file to be worked on.
The configuration file contains a json which defines replacement string for each code variable in the format `"<VARNAME>":"<String>"`. Code variables are preceeded and followed by a % sign in code but this is not the case in the configuration.
Also, they must be capitalized in code.
An alternative option to providing a string in the config is to add arrays defining files or commands (Commands are not implemented yet.). Format: `"<VARNAME>":["<file|exec>","<filepath|command>"]
Read the source code for further information.
### variable_grabbler.pass*.json
These are the the config files for variable_grabbler.py.
A short description of what the variables do and where they should go:
* `%NAVBAR%` (in HTML part of PHP file) → the Navbar, also includes an automatic logout-function if the user is in a place where they should never be logged in (triggered by absence of the $login variable)
* `%SET_LOGIN_VARIABLE%` (in PHP code) → sets the $login variable in PHP by detecting if the user has a valid logged in session
* `%NO_CHEAP_LOGIN_STEALING%` (in PHP code, before any non-header data is sent to client) → prevents the most primitive cookie stealing attempts, nothing advanced though
* `%BANNER_COOKIES%` (in HTML part of PHP file) → the cookie banner that every web page has
* `%PLEAZE_NO_CACHE%` (in PHP code, before any non-header data is sent to client) → requests the browser to not cache this page
* `%FORCE_LOGOUT%` (in PHP code) → logout immediately (obviously less common than the other variables...)
* `%CONTENT_DIR%` (anywhere in code) → the path to the ThreadR directory (without domain name)
* `%STYLESHEET%` (in HTML) → adds the tag linking the stylesheet
* `%REQUIRE_LOGIN%` (in PHP code, before any non-header data is sent to client) → sends users to the login page if they are not logged in
### navbar.template, banner_cookies.template
file templates for variables from the code variable replacement system