added some documentation. More to come.

README.md

@@ -1,7 +1,7 @@
 # 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. You do not need need to create your own lists. **Thank you.**
+**Dear Developers**, Please use the ToDo list below. 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:
@@ -16,25 +16,18 @@ The following files and directories are linked to areas where they can be access
   * `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.
+~~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.~~
 
-### Pass 0:
-  * `%NAVBAR%` → the code used to build the navbar, should remain in pass 0 as it may contain other variables
-
-### Pass 1:
-Looks quite empty at this point
-
-### Pass 2:
-  * `%CONTENT_DIR%` → The part of the URL between the domain name and the destination (e.g. https://lostcave.ddnss.de**/common/threadr/**about/), should remain in the last pass
-  * `%NO_CHEAP_SESSION_STEALING%` → checks the request origin against the values stored in the session cookie, add this before any actual data is transmitted (as in before any HTML code or echo commands because this affects the HTTP header)
-  * `%PLEAZE_NO_CACHE%` → adds header information, same as above goes here
+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"
 }
+```
 
 ## TODO:
   * cookie policy and eula
@@ -57,4 +50,58 @@ Looks quite empty at this point
   * replacement variable for PDO
   * variable arguments
   * Groups
-  * add %EMPTY_NAVBAR% variable for verify-email.php
+  * add %EMPTY_NAVBAR% variable for verify-email.php
+
+
+# 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.
+It’s 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, that’s 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 is commented to instruct you to leave it there.
+### variable_grabbler.py
+This is the code variable replacer. It take 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. Code variables are preceeded and followed by a % sign in code but this is not the case in the configuration.
+Alternative options to providing a string in the config are to add arrays defining files or commands (Commands are not implemented yet.). Read the source code for further information.
+### variable_grabbler.pass*.json
+the config files for variable_grabbler.py
+### navbar.template, banner_cookies.template
+file templates for variables from the code variable replacement system
+

deployment-script.sh

@@ -3,25 +3,27 @@ echo "Deployment script for repository \"web-deployment\"
 `date`
 =============================================================================="
 
+#run the code variable replacement
 echo -n "`find -name "*.php" -or -name "*.html" | sed 's/^/python variable_grabbler.py /;s/$/ variable_grabbler.pass0.json/'`" | bash -
 echo -n "`find -name "*.php" -or -name "*.html" | sed 's/^/python variable_grabbler.py /;s/$/ variable_grabbler.pass1.json/'`" | bash -
 echo -n "`find -name "*.php" -or -name "*.html" | sed 's/^/python variable_grabbler.py /;s/$/ variable_grabbler.pass2.json/'`" | bash -
 
+#the run-once section
 echo "Checking run-once script..."
 echo "Setting permissions."
 chmod +x run-once-script.sh
+#run the script only if it has changed since the last time it was checked, save a checksum of it to /var/www/git/run-once to compare next time
 echo -ne "import os, sys\nif \"`sha256sum run-once-script.sh`\" == \"`cat ../run-once`\":\n print \"File has not changed. Aborting.\"\n sys.exit()\nelse:\n print \"File has changed. Calculating checksum...\"\n os.system(\"sha256sum run-once-script.sh > ../run-once\")\n print \"\"\"Executing...\n==========\"\"\"\n os.system(\"./run-once-script.sh\")\n print \"\"\"==========\nDone.\"\"\"" | python
 
-
+# The status page is not just symlinked like the other files just to have a backup in case something goes wrong.
+# Not like that ever happened before....
 echo "Replacing status page..."
 cp -v ./strassenkind.php /var/www/strassenkind.ip/index.php
 cp -v ./internal.css /var/www/strassenkind.ip/style.css
-
 cp -v ./commands_git.conf /var/www/strassenkind.ip/
 cp -v ./commands_ondemand.conf /var/www/strassenkind.ip/
 cp -v ./commands_status.conf /var/www/strassenkind.ip/
 echo "Done."
 
-
 echo "==============================================================================
 Done."