bantflags/README.org

* BantFlags
A user script and backend enabling user created flags on [[https://boards.4chan.org/bant][/bant/]],
originally based on [[https://github.com/flaghunters/Extra-Flags-for-4chan][extraflags]].

 [[https://flags.plum.moe/bantflags.user.js][Install bantflags]]

** Userscript
The userscript uses of =GM_xmlhttpRequest= to get and post flags with
the backend . A user's flags are stored between pages using
=GM_setValue= and =GM_getValue=.

Old versions of GreaseMonkey will be able to recieve updates to the
script through use of the =@updateURL= and =@downloadURL= directives,
though these were depricated sometime in GreaseMonkey 3.x and updates
are only checked from the location the script was downloaded from so
be careful where you upload links.

On self hosting, changing =back_end= to your domain /should/ be all
you need to do, but don't take this as fact.

The userscript has been designed specifically to target ECMAScript
2015 (ES6), making liberal use of arrow functions, and const/let
declarations. Update your hecking browser.

** Backend
*** Prerequisites
- .NET Core 3.1
- MariaDB / MySQL

*** .NET dependancies
- Nito.AsyncEX
- Newtonsoft.Json
- MySql.Data
- Microsoft.AspNetCore.Mvc.NewtonsoftJson
- Microsoft.AspNetCore.StaticFiles
- Microsoft.AspNetCore.Razor
- Microsoft.EntityFrameworkCore.SqlServer
- Microsoft.EntityFrameworkCore.Tools
- Magick.NET-Q8-AnyCPU

*** Setup
1. Install .NET Core 
2. Clone and build the BantFlags solution.
3. Create the database using [[https://github.com/C-xC-c/BantFlags/blob/master/Environment/database.sql][database.sql]].
   + *Change the password*.
4. configure =BantFlags/appsettings.example.json= with your connection
   string and webroot (where you'll serve the flags from *without a 
   trailing /*) and rename it to =appsettings.json=
   + The location of the BantFlags application and the served content
     are not necessarly the same. If you leave it empty, or provide a
     nonexistant path the application will look for the =wwwroot=
     folder inside the working directory.
     + For example, you may place =BantFlags.dll= and
 =appsettings.json= in =/etc/bantflags/= and point =webroot= at
 =/var/www/html= and bantflags will server static content from
       that directory, or leave =webroot= empty and bantflags will look
       for static content in =/etc/bantflags/wwwroot=
5. Create a folder called =keys= in the directory you will be hosting
   bantflags from.
   + E.G. =/etc/bantflags/keys/=
   + ASP.NET Core uses some cryptic bullshit anti forgery token when
     processing HTML forms, and it's unable to persistantly store the
     decryption keys in memory on GNU + Linux. This directory will
     store said keys when you or users upload flags to /upload. The
     path is hardcoded to =AppDomain.CurrentDomain.BaseDirectory=,
     I.E. wherever the program is.
6. Add flags to the backend either by querying the database directly 
   and placing images *with the same name* in ={webroot}/flags/= or
   by using /upload.
7. Configure your webserver of choice to forward requests to kestral
   + [[https://github.com/C-xC-c/BantFlags/blob/master/Environment/nginx.conf][Example nginx config.]]
8. Run with =dotnet BantFlags.dll= or create a service to run it as a
   daemon.
   + [[https://github.com/C-xC-c/BantFlags/blob/master/Environment/bantflags.service][Example systemd service.]]
9. ???
10. profit.

*** Database
Tables look like this:

*posts*
| id | post_nr | board |
|  1 |   12345 | bant  |
|  2 |   56789 | bant  |
*flags*
| id | flag      |
|  1 | patchouli |
|  2 | chen      |
*postflags*
| id | post_nr | flag |
|  1 |       1 |    1 |
|  2 |       1 |    2 |
|  2 |       2 |    2 |
where post_nr and flag in *postflags* are the id fields in their
respective tables.
*** API
The backend exposes three endpoints used by the userscript to get and
post flags, and a flags directory storing the images themselves.

| route      | purpse                                     |
|------------+--------------------------------------------|
| /api/get   | Get flags using post numbers in the thread |
| /api/post  | Add flags to the database                  |
| /api/flags | List the flags we support                  |
| /flags/*   | The flag images                            |

** Backwards Compatibility
The API is 1:1 compatable with all previous versions of bantflags, but
also encodes a new =version= variable when getting flags which allows
for breaking changes in the script while the backend only sends data
it knows is parsable. See [[https://github.com/C-xC-c/BantFlags/tree/master/Docs/][Docs/{endpoint}]]
for version compatibility.