Rewrite README.md
parent
cf66802184
commit
5c67a92b29
159
README.md
159
README.md
|
|
@ -1,78 +1,75 @@
|
|||
# Welcome to ThreadR Rewritten
|
||||
This is the source code for the ThreadR Forum Engine (rewritten in go).
|
||||
|
||||
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.
|
||||
This is the source code for the ThreadR Forum Engine, rewritten in Go. ThreadR is a free and open-source forum engine designed to allow users to host their own forum instances on personal web servers.
|
||||
|
||||
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.
|
||||
## Project Overview
|
||||
|
||||
- [ ] come back online (see issue #2)
|
||||
- [ ] go FOSS (make the source code publicly available under a FOSS license (see issue #5))
|
||||
- [ ] 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)
|
||||
Originally started as a school project in 2019 with the aim of creating a hybrid between a forum and a social media platform, ThreadR was temporarily abandoned after school ended. Revived in 2020, the project shifted focus to become a fully functional, portable, and open-source forum engine under the Apache 2.0 license.
|
||||
|
||||
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.
|
||||
### Current Goals
|
||||
- [ ] Bring ThreadR back online (see issue #2)
|
||||
- [ ] Go FOSS by making the source code publicly available (see issue #5)
|
||||
- [ ] Ensure portability for easy setup of personal instances
|
||||
- [ ] Implement core forum features (sign-up, board creation, threads, messages, profiles)
|
||||
|
||||
- [ ] 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)
|
||||
### Future Features
|
||||
- Anonymous posting with unique per-thread identifiers for registered users
|
||||
- Thread subscription and notifications for new messages (opt-out available)
|
||||
- "Split thread here" functionality for focused discussions
|
||||
- Automatic loading of new messages in threads (opt-out in settings)
|
||||
- Question threads with an "accept answer" feature
|
||||
- Nuanced like/dislike system (limited functionality, inspired by StackExchange)
|
||||
|
||||
\- BodgeMaster
|
||||
**Note:** ThreadR is now technically host-independent with configurable settings, though it remains a work in progress (WIP).
|
||||
|
||||
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
|
||||
|
||||
# Installation
|
||||
First of all, keep in mind that the ThreadR Forum Engine is still in early development and things are subject to change.
|
||||
ThreadR is in early development, and setup is currently manual. Automated setup scripts will be added in the future.
|
||||
|
||||
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)
|
||||
### Prerequisites
|
||||
This guide assumes you are on a UNIX-like system with the following installed:
|
||||
- Apache with PHP (may work with other web servers)
|
||||
- MySQL or MariaDB
|
||||
- Python 3
|
||||
- Bash
|
||||
|
||||
Installation:
|
||||
### Setup Steps
|
||||
1. Clone this repository into a directory accessible by your web server but outside any web root.
|
||||
2. Create a MySQL/MariaDB database with the tables listed below.
|
||||
3. Add a dedicated MySQL/MariaDB user for ThreadR and grant usage privileges for the tables.
|
||||
4. Symlink the `build/` directory to your desired web root location (ThreadR does not support direct web root linking).
|
||||
5. Adjust configuration files in the `config/` directory to match your setup.
|
||||
6. Run `./deployment-script.sh` to apply the configuration.
|
||||
7. Optionally, symlink `build/redirect_home.html` to redirect specific locations to ThreadR.
|
||||
|
||||
- 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
|
||||
### Database Schema
|
||||
- **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
|
||||
- **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)
|
||||
- `edit_time` (timestamp, nullable, default null, on update current_timestamp())
|
||||
- `content` (text, nullable, default null)
|
||||
- `attachment_hash` (bigint(20), nullable, default null)
|
||||
- `attachment_name` (varchar, nullable, 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?))
|
||||
- **profiles** (usage TBD)
|
||||
- `id` (smallint, primary key, index)
|
||||
- `email` (varchar, index, likely unique)
|
||||
- `display_name` (varchar)
|
||||
- `status` (varchar)
|
||||
- `about` (very long varchar)
|
||||
- `about` (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))
|
||||
- **users**
|
||||
- `id` (smallint, primary key)
|
||||
- `name` (varchar, index, likely unique)
|
||||
- `authentication_string` (varchar(128))
|
||||
- `authentication_salt` (varchar)
|
||||
- `authentication_algorithm` (varchar)
|
||||
|
|
@ -80,57 +77,31 @@ Database tables:
|
|||
- `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:
|
||||
## Running the Application
|
||||
To start the ThreadR server, run the following command after configuration:
|
||||
```
|
||||
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
|
||||
go run ./main.go
|
||||
```
|
||||
TBD: Remove this section when the ThreadR project moves to its final home and this repository is only used for our local setup.
|
||||
The server will start on port 8080 by default.
|
||||
|
||||
## 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)
|
||||
## Project Structure
|
||||
- **src/**: Core ThreadR source files
|
||||
- **build/**: Placeholder for deployment, contains a working instance after running the deployment script
|
||||
- **config/**: Configuration files for specific ThreadR instances
|
||||
- **macros/**: Files for use with the variable grabbler script
|
||||
- **static/**: Static assets (CSS, images) for the web interface
|
||||
- **templates/**: HTML templates for rendering pages
|
||||
- **handlers/**: HTTP request handlers for various routes
|
||||
- **models/**: Database models and interaction logic
|
||||
- **deployment_script.sh**: Script for code variable replacement and deployment tasks
|
||||
- **variable_grabbler.py**: Custom macro processor for configuration
|
||||
- **LICENSE.md**: Apache 2.0 license details
|
||||
- **NOTICE**: Copyright notice in plain text
|
||||
|
||||
# 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
|
||||
## Contributing
|
||||
We welcome contributions! Please discuss ideas or issues in the GitHub issues section or join our Discord server for real-time communication: [discord.gg/r3w3zSkEUE](https://discord.gg/r3w3zSkEUE).
|
||||
|
||||
Macros in code are strings of capitalized characters prefixed and suffixed with %.
|
||||
## License
|
||||
ThreadR is licensed under the Apache 2.0 License. See [LICENSE.md](./LICENSE.md) for details.
|
||||
|
||||
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.
|
||||
**Authors:** BodgeMaster, Jocadbz
|
||||
|
|
@ -1,28 +0,0 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||||
<title>Document</title>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Lista de frutas</h1>
|
||||
<div id="array"></div>
|
||||
<div id="pessoa"></div>
|
||||
<script type="text/javascript">
|
||||
let frutas = [];
|
||||
frutas.push("Maçã");
|
||||
frutas.push("Laranja");
|
||||
frutas.push("Limão");
|
||||
document.getElementById("array").innerHTML = `Frutas = ${frutas}`;
|
||||
|
||||
let pessoa = [];
|
||||
pessoa = {
|
||||
nome: "Joaquim",
|
||||
idade: 17,
|
||||
salario: 14400
|
||||
}
|
||||
document.getElementById("pessoa").innerHTML = `${pessoa["nome"]}`;
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
Loading…
Reference in New Issue