diff --git a/README.md b/README.md index b4e8945..3c7e8c7 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,27 @@ # 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. +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. +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. +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 @@ -22,14 +33,22 @@ Once these two are given, here are some additional goals both from the original \- 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. +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 will be added in the future. +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: -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 @@ -81,9 +100,12 @@ Database tables: - `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. +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. +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: ``` @@ -97,40 +119,65 @@ cd web-deployment 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. +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: +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 %. +### [[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 -"":"" → direct replacement -"":["file",""] → insert file -"":["exec",""] → 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. +- "":"" → direct replacement +- "":["file",""] → insert file +- "":["exec",""] → run command and insert its output from stdout