diff --git a/README.md b/README.md index aa2a12d6..1a3efe08 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,8 @@ While we currently are [dogfooding](https://en.wikipedia.org/wiki/Eating_your_ow community with around 50 servers, I would not recommend non-developers use the project yet. It's still in fairly major development mode and large sections are still incomplete or function but very rough. -Before we tag a 1.0.0 release, we will write some proper user-facing documentation. +Before we tag a 1.0.0 release, we will write some proper user-facing documentation. You can however look at the +currently incomplete [docs](https://leighmacdonald.github.io/gbans/docs/INTRO). ## Features diff --git a/docs/docs/INTRO.md b/docs/docs/INTRO.md new file mode 100644 index 00000000..a2966205 --- /dev/null +++ b/docs/docs/INTRO.md @@ -0,0 +1,37 @@ +--- +sidebar_position: 1 +--- + +# Intro + +gbans is a system for handling Team Fortress 2 server administration in a centralized manner. It is primarily written +in golang, typescript and sourcepawn and consists of 3 major components: + +- Website / Frontend +- Backend services +- Sourcemod plugin + +## High Level Features + +- Several types of bans (steam, ip/cidr, group membership, friends) with whitelisting for ips/steamids. +- User reports and appeals +- Server browser +- Forums +- Wiki +- Chat logs +- SourceTV downloads +- Player Stats +- Patreon integration (OAuth) +- Discord integration (Bot + OAuth) +- Flagging and automatic action for flagged words +- Sourcemod SQL Admins compatibility + +Most of these features have some level of being toggled on/off. + +## Installation Guide + +To get started with installation, please see the [installation guide](./install) + +## Development Guide + +If you want to hack on gbans, please see the [devel](./devel) section to get started. \ No newline at end of file diff --git a/docs/docs/devel/DOCS.md b/docs/docs/devel/DOCS.md new file mode 100644 index 00000000..bde463e0 --- /dev/null +++ b/docs/docs/devel/DOCS.md @@ -0,0 +1,32 @@ +# Updating Docs + +## Initialize Dependencies + +If its your first time running the docs, you will need to install the dependencies first: + +```shell +make docs_setup +``` + +## Starting a local server + +To get up and running with the local development web server, run the following command: + +```shell +make docs_start +``` + +This should open a browser tab with the current docs. If it does not open for you, the default +address is [http://localhost:3000/gbans/](http://localhost:3000/gbans/) + +## Deployment + +Docs for the project are currently auto deployed on every push to the master branch. + +## Building + +If you wish to build a production version of the docs you may use: + +```shell +make docs_build +``` \ No newline at end of file diff --git a/docs/docs/guide/DATABASE.md b/docs/docs/guide/DATABASE.md new file mode 100644 index 00000000..02acc692 --- /dev/null +++ b/docs/docs/guide/DATABASE.md @@ -0,0 +1,19 @@ +# Database Reference + +## Creating a sourcemod user + +It's recommended to create a secondary non-privileged user, especially when using servers remote of the +gbans instance. Below is an example of creating a read-only user that only has access to the tables, and functions, required +for operation. + +```postgresql +CREATE ROLE sourcemod WITH LOGIN PASSWORD ''; +GRANT CONNECT ON DATABASE gbans TO sourcemod; +GRANT USAGE ON SCHEMA public TO sourcemod ; +GRANT SELECT ON + sm_config, sm_overrides, sm_group_overrides, sm_group_immunity, sm_groups, + sm_admins_groups, sm_adminsTO sourcemod; +GRANT SELECT, INSERT, UPDATE, DELETE ON sm_cookie_cache, sm_cookies TO sourcemod; +GRANT EXECUTE ON FUNCTION check_ban TO sourcemod; + +``` diff --git a/docs/docs/install/CONFIG.md b/docs/docs/install/CONFIG.md new file mode 100644 index 00000000..8c268b8b --- /dev/null +++ b/docs/docs/install/CONFIG.md @@ -0,0 +1,130 @@ +--- +sidebar_position: 2 +--- + +# Config + +## Server + +Copy the example configuration `gbans_example.yml` and name it `gbans.yml`. It should be in +the same directory as the binary. Configure it as desired. + +This is your core configuration file. These values cannot be changed without changing this file and restarting +the service. Most other configuration is handled via the webapp admin interface. +```yaml +owner: 76561197960287930 +external_url: "http://example.com" + +# Listen on this ip address +# 0.0.0.0 = Any +http_host: 0.0.0.0 +# Listen on this port +http_port: 6006 +http_static_path: +http_client_timeout: 20 +# Encryption key for cookies +http_cookie_key: change-me +http_cors_origins: + - "https://example.com" + +# DSN to your database +database_dsn: "postgresql://gbans:gbans@192.168.0.200:5432/gbans" +database_log_queries: false +``` + +## systemd service + +If you are not using docker, it's recommended to create a [systemd .service](https://freedesktop.org/software/systemd/man/systemd.service.html) +file so that it can start automatically. More info on configuring this will be available at a later +date. + +## Sourcemod + +Place the `sourcemod/plugins/gbans.smx` file into `tf/addons/sourcemod/plugins`. Then add the config as +described below. + +This config file should be places in `tf/addons/sourcemod/configs/gbans.cfg`. + +``` +"gbans" +{ + // Remote gban server host + "host" "https://example.com" + + // Remote gban server port + "port" "443" + + // Unique server name for this server, the same as a "server-id" + "server_name" "example-1" + + // The authentication token used to retrieve a auth token + "server_key" "YOUR_SERVER_PASSWORD" +} +``` + +The server gbans server is running you should now be able to see the `[GB]` message logs in the +console. With a message like below on successful authentication with the server. + +``` +[GB] Using config file: addons/sourcemod/configs/gbans.cfg +[GB] Request to https://gbans.example.com/v1/auth finished with status code 200 in 0.01 seconds +[GB] Successfully authenticated with gbans server + +``` + +## Discord + +To use discord you need to [create a discord application](https://discord.com/developers/applications). You will need +the following values from your application: + +- Application ID (General -> Application ID) +- Token (Bot -> Token) +- Client Secret (OAuth2 -> Client Secret) + +You will also need to fetch the following ids from your discord client. You will want to enable discord developer mode +to be able to easily acquire these role and channel ids through your own discord client. + +- Your main server guild id. +- Logging Channels IDs + - Log Channel (default catch-all if no others are configured) + - Match logs + - Vote logs + - Appeal / Report logs + - Ban logs + - Forum logs + - Word filter logs + +Care should be taken to restrict these channels to permissions as appropriate. + +To enable discord connections, You must also set an oauth2 redirect (Oauth2 -> Redirects -> Add) to point to your own server. + + https://example.com/discord/oauth + +## IP2Location + +To install the GeoLite2 databases, create an account on [IP2location Lite](https://lite.ip2location.com). After +confirmation, you'll be given a download token for use in gbans.yaml. + +### Via Web + +You can find a button to initiate a refresh of the database via the geo database admin gui at `https://example.com/admin/settings?section=geo_location`. + +### Via cli + +If instead you want to do it manually, or though cron via CLI you can try the following. + +- If using Docker, start the process via `docker exec -it gbans ./gbans net update`. +- If using a compiled binary, navigate to the folder and run `./gbans net update` to start the process. + +The process will take up to 30 minutes, depending on hardware, and will add around 2GB to the database when all's said +and done. + +## Enabling User Location + +The Servers page lets users sort by range. Gbans does not use the locations API to get data from the browser. +Instead, you're required to use Cloudflare to get the location. Gbans must be proxied through Cloudflare to +accomplish this, and setting that up is out of scope of this doc. + +Once the domain is set up, go to the domain settings, the `Rules` dropdown, `Transform Rules`, and then the +`Managed Transforms` tab. Enable `Add visitor location headers`, and wait around 5 minutes for it to take effect. +You should then be able to see your location (more or less) on the servers page. diff --git a/docs/docs/install/INSTALL.md b/docs/docs/install/INSTALL.md index b0b77837..f552955f 100644 --- a/docs/docs/install/INSTALL.md +++ b/docs/docs/install/INSTALL.md @@ -1,3 +1,7 @@ +--- +sidebar_position: 1 +--- + # Installation Guide Basic installation overview of the gbans server and sourcemod plugin. @@ -8,33 +12,49 @@ Gbans is lightweight and can handle a small to moderately sized community with a Special considerations need to be made when using extended functionality: -- IP2Location is memory intensive when updating the dataset, requiring 10 to 12GB of memory. The process can be - sped up by using NVMe storage for the database. +It's recommended, but not required, to use a dedicated server for installation. The application is fairly lightweight, but some features +will take some computational power which can interrupt other processes. This includes things like downloading demos +over SSH/SCP and processing users stats. If you omit these features, it should be able to run alongside a game server fairly +well on a VPS. Ram usage is pretty negligible, but if you have a lot of servers and a long history, you may want to +increase the ram allocated to postgres. + +If you are hosting game servers and gbans on the same host, you will likely want to specify [GOMAXPROCS](https://pkg.go.dev/runtime#hdr-Environment_Variables) +when starting gbans so that you can set processor affinity/cpuset properly to ensure they are not fighting each other for resources. + +IP2Location updates are a fairly intensive process, so considerations should be taken as far as how and when to update the database +to ensure it doesn't impact other things on the system. + +## Runtime requirements + +Running the binaries is very easy as they are statically compiled. All frontend assets are embedded into the binary +to make deployment as trivial as possible. -Larger communities will inherently require more resources. +- Any modern-ish postgresql install with [PostGIS](https://postgis.net/) & [ip4r](https://github.com/RhodiumToad/ip4r) extensions. All non-EOL versions of postgres should work. +- A platform that go supports. Only linux and windows amd64 are tested, but as far as I know, others should work. ## Sourcemod Plugins -The following extensions must be installed for gbans to work, see their documentation for up to date installation +The following extensions must be installed for gbans to work, see their documentation for up-to-date installation instructions: -- [System2](https://github.com/dordnung/System2) Provides HTTP(S) client functionality +- [sm-ripext](https://github.com/ErikMinekus/sm-ripext) Provides HTTP(S) client functionality - [sm-json](https://github.com/clugg/sm-json) `Required for development only` Provides JSON encoding/decoding. - [Connect](https://github.com/asherkin/connect) Provides `OnClientPreConnectEx` +- [SourceTVManager](https://github.com/peace-maker/sourcetvmanager) Interface to interact with the SourceTV server from SourcePawn. ## gbans Server ### Compile from source -Precompiled binaries will be provided once the project is in a more stable state. Its recommended to use the docker +Precompiled binaries will be provided once the project is in a more stable state. It's recommended to use the docker images as they are currently the only tested usecase. - [make](https://www.gnu.org/software/make/) Not strictly required but provides predefined build commands - [golang 1.22+](https://golang.org/) Version >=1.22 is required. -- [PostgreSQL](https://www.postgresql.org/) Version 15 is the only version currently tested against. However, anything - 10 and up should work, ymmv. - - [PostGIS](https://postgis.net/) extension is also used for some GIS functionality. -- [NodeJS >=18.17.1](https://nodejs.org/en/) To build frontend +- [PostgreSQL](https://www.postgresql.org/) Version 16 is the only version currently tested against. All non-EOL versions should be supported. + - [PostGIS](https://postgis.net/) Provides some basic GIS functionality. + - [ip4r](https://github.com/RhodiumToad/ip4r) Improved ip/cidr indexed and types. +- [Node.js >=18.17.1](https://nodejs.org/en/) To build frontend - [pnpm](https://pnpm.io/) JS package manager - [Sourcemod 1.12](https://www.sourcemod.net/) - Sourcemod installation @@ -43,23 +63,27 @@ Basic steps to build the binary packages: If you do not already have sourcemod, you can download and extract sourcemod to a directory of your choosing with the following: - mkdir -p ~/sourcemod && wget https://sm.alliedmods.net/smdrop/1.12/sourcemod-1.12.0-git7110-linux.tar.gz -O ~/sourcemod/sm.tar.gz && tar xvfz ~/sourcemod/sm.tar.gz -C ~/sourcemod +```shell +mkdir -p ~/sourcemod && wget https://sm.alliedmods.net/smdrop/1.12/sourcemod-1.12.0-git7110-linux.tar.gz -O ~/sourcemod/sm.tar.gz && tar xvfz ~/sourcemod/sm.tar.gz -C ~/sourcemod +``` Clone the gbans repository - git clone git@github.com:leighmacdonald/gbans.git && cd gbans - +```shell +git clone git@github.com:leighmacdonald/gbans.git && cd gbans +```` Build the projects, replace SM_ROOT with the path to your sourcemod installation directory (the folder with addons and cfg folders inside). - SM_ROOT=~/sourcemod make - +```shell +SM_ROOT=~/sourcemod make +```` You should now have a binary located at `./build/$platform/gbans` ### Docker -``` -sudo docker run -d --restart unless-stopped \ +```shell +docker run -d --restart unless-stopped \ -p 6006:6006 \ --dns=1.1.1.1 \ -v /home/ubuntu/gbans/gbans.yml:/app/gbans.yml:ro \ @@ -77,99 +101,6 @@ suddenly start to not return results, you probably need to increase this. You can add `shm_size: 512m` to the docker compose file for postgres, or `--shm-size=512m` if running docker command directly. -## Configuration - -### Server - -Copy the example configuration `gbans_example.yml` and name it `gbans.yml`. It should be in -the same directory as the binary. Configure it as desired. - -#### Starting the server - -To start the server just run `./build/linux64/gbans serve`. - -It's recommended to create a [systemd .service](https://freedesktop.org/software/systemd/man/systemd.service.html) -file so that it can start automatically. More info on configuring this will be available at a later -date. - -### Sourcemod - -Place the `sourcemod/plugins/gbans.smx` file into `tf/addons/sourcemod/plugins`. Then add the config as -described below. - -This config file should be places in `tf/addons/sourcemod/configs/gbans.cfg`. - -``` -"gbans" -{ - // Remote gban server host - "host" "https://gbans.example.com" - - // Remote gban server port - "port" "443" - - // Unique server name for this server, the same as a "server-id" - "server_name" "example-1" - - // The authentication token used to retrieve a auth token - "server_key" "YOUR_TOKEN" -} -``` - -The server gbans server is running you should now be able to see the `[GB]` message logs in the -console. With a message like below on successful authentication with the server. - -``` -[GB] Using config file: addons/sourcemod/configs/gbans.cfg -[GB] Request to https://gbans.example.com/v1/auth finished with status code 200 in 0.01 seconds -[GB] Successfully authenticated with gbans server -``` - -### Discord - -To use discord you need to [create a discord application](https://discord.com/developers/applications). You will need -the following values from your application: - -- Application ID (General -> Application ID) -- Token (Bot -> Token) -- Client Secret (OAuth2 -> Client Secret) - -You Will also need to fetch the following ids from your discord client. You will want to enable discord developer mode -to be able to easily acquire these role and channel ids through your own discord client. - -- Your main server guild id. -- Logging Channels IDS - - Public Log Channel - - (Private) Moderation Channel - - (Private) Bot Logs - - (Private) Report Logs - -You must also set an oauth2 redirect (Oauth2 -> Redirects -> Add) to point to your own server. - - https://example.com/login/discord - -Example configuration for discord - - discord: - # Enable optional discord integration - enabled: true - app_id: 814566730000000000 - app_secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - guild_id: 875964612233801748 - # Your discord bot token - # See: https://discord.com/developers/applications - token: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" - mod_role_ids: [333333333333333333, 4444444444444444444] - # People in these channels automatically have moderator privilege - # To find these, Right click the channel -> copy id - mod_channel_ids: - - "111111111111111111" - mod_log_channel_id: "111111111111111111" - log_channel_id: "111111111111111111" - public_log_channel_enable: true - public_log_channel_id: "222222222222222222" - report_log_channel_id: "111111111111111111" - ## Reverse Proxy ### Caddy w/cloudflare @@ -184,7 +115,7 @@ Example configuration for discord } ``` -## Apache 2.4 +### Apache 2.4 Be sure to run `sudo a2enmod proxy_http ssl` first. @@ -208,29 +139,4 @@ SSLCertificateKeyFile /etc/cloudflare/example.com.key ``` -If using Cloudflare to provide user location, you can use Origin Certificates to generate a long-lasting SSL certicate. - -## IP2Location - -To install the GeoLite2 databases, create an account on [IP2location Lite](https://lite.ip2location.com). After -confirmation, you'll be given a download token for use in gbans.yaml. - -If using Docker, open a terminal with `docker exec -it gbans /bin/sh`, or if using a compiled binary, navigate to the -folder. - -Run `./gbans net update` to start the process. This will require around 12GB of memory (or a suitably large swapfile), -and does *not* need to be run on the host - a more powerful machine can run it, as long as the config is -mirrored and database access works. - -The process will take up to 30 minutes, depending on hardware, and will add around 2GB to the database when all's said -and done. - -## Enabling User Location - -The Servers page lets users sort by range. Gbans does not use the locations API to get data from the browser. -Instead, you're required to use Cloudflare to get the location. Gbans must be proxied through Cloudflare to -accomplish this, and setting that up is out of scope of this doc. - -Once the domain is set up, go to the domain settings, the `Rules` dropdown, `Transform Rules`, and then the -`Managed Transforms` tab. Enable `Add visitor location headers`, and wait around 5 minutes for it to take effect. -You should then be able to see your location (more or less) on the servers page. +If using Cloudflare to provide user location, you can use Origin Certificates to generate a long-lasting SSL certificate. diff --git a/docs/docs/intro.md b/docs/docs/intro.md deleted file mode 100644 index 9350fec5..00000000 --- a/docs/docs/intro.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -sidebar_position: 1 ---- - -# Tutorial Intro - -Let's discover **Docusaurus in less than 5 minutes**. - -## Getting Started - -Get started by **creating a new site**. - -Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. - -### What you'll need - -- [Node.js](https://nodejs.org/en/download/) version 18.0 or above: - - When installing Node.js, you are recommended to check all checkboxes related to dependencies. - -## Generate a new site - -Generate a new Docusaurus site using the **classic template**. - -The classic template will automatically be added to your project after you run the command: - -```bash -npm init docusaurus@latest my-website classic -``` - -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. - -The command also installs all necessary dependencies you need to run Docusaurus. - -## Start your site - -Run the development server: - -```bash -cd my-website -npm run start -``` - -The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. - -The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. - -Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. -