From b2c8f2fa9099a2116fbb6e377e36f5d03d59321a Mon Sep 17 00:00:00 2001 From: Jordan Dominion Date: Tue, 3 Sep 2024 07:09:37 -0400 Subject: [PATCH] Unfuck the readme --- README.md | 47 +++++++++++++++++------------------------------ 1 file changed, 17 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 3ecd2a9142..ed43da7fb1 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ If you're just a hobbyist server host, you can probably get away with using SQLi _HOWEVER_ -SQLite is not a battle-ready relational database. It doesn't scale well for any use case. TGS _strongly_ recommends you use one of its supported standalone databases. Setting one of these up is more involved but worth the effort. +SQLite is not a battle-ready relational database. It doesn't scale well for any use case. TGS *strongly* recommends you use one of its supported standalone databases. Setting one of these up is more involved but worth the effort. The supported standalone databases are: @@ -38,9 +38,8 @@ The supported standalone databases are: - MySQL TGS will require either: - - No pre-existing database WITH schema creation permissions. - or +or - Exclusive access to a database schema that TGS has full control over. ### Installation @@ -64,13 +63,11 @@ Note: If you use the `/silent` or `/passive` arguments to the installer, you wil [winget](https://github.com/microsoft/winget-cli) installed is the easiest way to install the latest version of tgstation-server (provided Microsoft has approved the most recent package manifest). Check if you have `winget` by running the following command. - ``` winget --version ``` If it returns an error that means you don't have winget. You can easily install it by running the following commands in an administrative Windows Powershell instance: - ``` Import-Module Appx Invoke-WebRequest -Uri https://www.nuget.org/api/v2/package/Microsoft.UI.Xaml/2.7.3 -OutFile .\microsoft.ui.xaml.2.7.3.zip @@ -161,7 +158,6 @@ Alternatively, to launch the server in the current shell, run `./tgs.sh` in the tgstation-server supports running in a docker container. The official image repository is located at https://hub.docker.com/r/tgstation/server. It can also be built locally by running `docker build . -f build/Dockerfile -t ` in the repository root. To create a container run - ```sh docker run \ -ti \ # Start with interactive terminal the first time to run the setup wizard @@ -178,7 +174,6 @@ docker run \ -v /path/to/your/log/folder:/tgs_logs \ # Recommended, create a volume mapping for server logs tgstation/server[:] ``` - with any additional options you desire (i.e. You'll have to expose more game ports in order to host more than one instance). When launching the container for the first time, you'll be prompted with the setup wizard and then the container will exit. Start the container again to launch the server. @@ -204,15 +199,14 @@ OpenDream currently requires [.NET SDK 8.0](https://dotnet.microsoft.com/en-us/d
How to handle a different SDK version than the ASP.NET runtime of TGS. -On Linux, as long as OpenDream and TGS do not use the same .NET major version, you cannot achieve this with the package manager as they will conflict. For example, the 7.0 SDK can be added to an 8.0 runtime installation via the following steps. + On Linux, as long as OpenDream and TGS do not use the same .NET major version, you cannot achieve this with the package manager as they will conflict. For example, the 7.0 SDK can be added to an 8.0 runtime installation via the following steps. -1. Install `tgstation-server` using any of the above methods. -1. [Download the Linux SDK binaries](https://dotnet.microsoft.com/en-us/download/dotnet/7.0) for your selected architecture. -1. Extract everything EXCEPT the `dotnet` executable, `LICENSE.txt`, and `ThirdPartyNotices.txt` in the `.tar.gz` on top of the existing installation directory `/usr/share/dotnet/` -1. Run `sudo chown -R root /usr/share/dotnet` - -You should now be able to run the `dotnet --list-sdks` command and see an entry for `7.0.XXX [/usr/share/dotnet/sdk]`. + 1. Install `tgstation-server` using any of the above methods. + 1. [Download the Linux SDK binaries](https://dotnet.microsoft.com/en-us/download/dotnet/7.0) for your selected architecture. + 1. Extract everything EXCEPT the `dotnet` executable, `LICENSE.txt`, and `ThirdPartyNotices.txt` in the `.tar.gz` on top of the existing installation directory `/usr/share/dotnet/` + 1. Run `sudo chown -R root /usr/share/dotnet` + You should now be able to run the `dotnet --list-sdks` command and see an entry for `7.0.XXX [/usr/share/dotnet/sdk]`.
### Configuring @@ -267,14 +261,13 @@ Create an `appsettings.Production.yml` file next to `appsettings.yml`. This will - `ControlPanel:Enable`: Enable the javascript based control panel to be served from the server via /index.html -- `ControlPanel:AllowAnyOrigin`: Set the Access-Control-Allow-Origin header to \* for all responses (also enables all headers and methods) +- `ControlPanel:AllowAnyOrigin`: Set the Access-Control-Allow-Origin header to * for all responses (also enables all headers and methods) - `ControlPanel:AllowedOrigins`: Set the Access-Control-Allow-Origin headers to this list of origins for all responses (also enables all headers and methods). This is overridden by `ControlPanel:AllowAnyOrigin` - `ControlPanel:PublicPath`: URL from which the webpanel can be accessed, defaults to "/app/". Must be an absolute path (https://example.org/path/to/webpanel) or a path starting from root (/path/to/webpanel). Note that this option does not relocate the webpanel for you; you will need a reverse proxy to relocate the webpanel - `Elasticsearch`: tgstation-server also supports automatically ingesting its logs to ElasticSearch. You can set this up in the setup wizard, or with the following configuration: - ```yml Elasticsearch: Enable: true @@ -298,7 +291,6 @@ Create an `appsettings.Production.yml` file next to `appsettings.yml`. This will - `Swarm:UpdateRequiredNodeCount`: Should be set to the total number of servers in your swarm minus 1. Prevents updates from occurring unless the non-controller server count in the swarm is greater than or equal to this value. - `Security:OAuth:`: Sets the OAuth client ID and secret for a given ``. The currently supported providers are `Keycloak`, `GitHub`, `Discord`, `InvisionCommunity` and `TGForums`. Setting these fields to `null` disables logins with the provider, but does not stop users from associating their accounts using the API. Sample Entry: - ```yml Security: OAuth: @@ -309,7 +301,6 @@ Security: ServerUrl: "..." UserInformationUrlOverride: "..." # For power users, leave out of configuration for most cases. Not supported by GitHub provider. ``` - The following providers use the `RedirectUrl` setting: - GitHub @@ -375,7 +366,6 @@ The DMAPI is fully backwards compatible and should function with any tgstation-s Here is a bare minimum example project that implements the essential code changes for integrating the DMAPI Before `tgs.dm`: - ```dm //Remember, every codebase is different, you probably have better methods for these defines than the ones given here #define TGS_EXTERNAL_CONFIGURATION @@ -392,7 +382,6 @@ Before `tgs.dm`: ``` Anywhere else: - ```dm var/global/client_count = 0 @@ -447,13 +436,11 @@ _NOTE: Your reverse proxy setup may interfere with SSE (Server-Sent Events) whic 1. Setup a basic website configuration. Instructions on how to do so are out of scope. 2. In your Caddyfile, under a server entry, add the following (replace 5000 with the port TGS is hosted on): - ``` https://your.site.here { reverse_proxy localhost:5000 } ``` - 3. For this setup, your configuration's `ControlPanel:PublicPath` needs to be blank. If you have a path in `PublicPath`, it needs to be in "reverse_proxy PublicPathHere localhost:5000". See https://caddyserver.com/docs/caddyfile/directives/reverse_proxy @@ -463,7 +450,6 @@ See https://caddyserver.com/docs/caddyfile/directives/reverse_proxy 1. Setup a basic website configuration. Instructions on how to do so are out of scope. 2. Acquire an HTTPS certificate, likely via Let's Encrypt, and configure NGINX to use it. 3. Setup a path under a server like the following (replace 8080 with the port TGS is hosted on): - ``` location /tgs { proxy_pass http://127.0.0.1:8080; @@ -479,7 +465,6 @@ See https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/ 2. Setup a basic website configuration. Instructions on how to do so are out of scope. 3. Acquire an HTTPS certificate, likely via Let's Encrypt, and configure Apache to use it. 4. Under a VirtualHost entry, setup the following (replace 8080 with the port TGS is hosted on): - ``` ProxyPass / http://127.0.0.1:8080 ProxyPassReverse / http://127.0.0.1:8080 @@ -488,7 +473,6 @@ ProxyPassReverse / http://127.0.0.1:8080 See https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html Example VirtualHost Entry - ``` @@ -602,7 +586,10 @@ Bots have a set of built-in commands that can be triggered via `!tgs`, mentionin All files in game code deployments are considered transient by default, meaning when new code is deployed, changes will be lost. Static files allow you to specify which files and folders stick around throughout all deployments. -The `StaticFiles` folder contains 3 root folders which cannot be deleted and operate under special rules - `CodeModifications` - `EventScripts` - `GameStaticFiles` +The `StaticFiles` folder contains 3 root folders which cannot be deleted and operate under special rules + - `CodeModifications` + - `EventScripts` + - `GameStaticFiles` These files can be modified either in host mode or system user mode. In host mode, TGS itself is responsible for reading and writing the files. In system user mode read and write actions are performed using the system account of the logged on User, enabling the use of ACLs to control access to files. Database users will not be able to use the static file system if this mode is configured for an instance. @@ -676,12 +663,12 @@ Feel free to ask for help [on the discussions page](https://github.com/tgstation ## Contributing -- See [CONTRIBUTING.md](.github/CONTRIBUTING.md) +* See [CONTRIBUTING.md](.github/CONTRIBUTING.md) ## Licensing -- The DMAPI for the project is licensed under the MIT license. -- The /tg/station 13 icon is licensed under [Creative Commons 3.0 BY-SA](http://creativecommons.org/licenses/by-sa/3.0/). -- The remainder of the project is licensed under [GNU AGPL v3](http://www.gnu.org/licenses/agpl-3.0.html) +* The DMAPI for the project is licensed under the MIT license. +* The /tg/station 13 icon is licensed under [Creative Commons 3.0 BY-SA](http://creativecommons.org/licenses/by-sa/3.0/). +* The remainder of the project is licensed under [GNU AGPL v3](http://www.gnu.org/licenses/agpl-3.0.html) See the files in the `/src/DMAPI` tree for the MIT license