diff --git a/_r_e_a_d_m_e_8md_source.html b/_r_e_a_d_m_e_8md_source.html index 85b5bee7cc..a727b37944 100644 --- a/_r_e_a_d_m_e_8md_source.html +++ b/_r_e_a_d_m_e_8md_source.html @@ -90,7 +90,7 @@ var searchBox = new SearchBox("searchBox", "search",false,'Search');
README.md
-Go to the documentation of this file.
1 # tgstation-server v4:
2 
3 [![Build status](https://ci.appveyor.com/api/projects/status/7t1h7bvuha0p9j5f/branch/master?svg=true)](https://ci.appveyor.com/project/Cyberboss/tgstation-server-tools/branch/master) [![Build Status](https://travis-ci.org/tgstation/tgstation-server.svg?branch=master)](https://travis-ci.org/tgstation/tgstation-server) [![codecov](https://codecov.io/gh/tgstation/tgstation-server/branch/master/graph/badge.svg)](https://codecov.io/gh/tgstation/tgstation-server)
4 
5 [![GitHub license](https://img.shields.io/github/license/tgstation/tgstation-server.svg)](LICENSE) [![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/tgstation/tgstation-server.svg)](http://isitmaintained.com/project/tgstation/tgstation-server "Average time to resolve an issue") [![NuGet version](https://img.shields.io/nuget/v/Tgstation.Server.Api.svg)](https://www.nuget.org/packages/Tgstation.Server.Api) [![NuGet version](https://img.shields.io/nuget/v/Tgstation.Server.Client.svg)](https://www.nuget.org/packages/Tgstation.Server.Client)
6 
7 [![forthebadge](http://forthebadge.com/images/badges/made-with-c-sharp.svg)](http://forthebadge.com) [![forinfinityandbyond](https://user-images.githubusercontent.com/5211576/29499758-4efff304-85e6-11e7-8267-62919c3688a9.gif)](https://www.reddit.com/r/SS13/comments/5oplxp/what_is_the_main_problem_with_byond_as_an_engine/dclbu1a)
8 
9 [![forthebadge](http://forthebadge.com/images/badges/built-with-love.svg)](http://forthebadge.com) [![forthebadge](http://forthebadge.com/images/badges/60-percent-of-the-time-works-every-time.svg)](http://forthebadge.com)
10 
11 This is a toolset to manage production BYOND servers. It includes the ability to update the server without having to stop or shutdown the server (the update will take effect on a "reboot" of the server) the ability start the server and restart it if it crashes, as well as systems for managing code and game files, and merging GitHub Pull Requests for test deployments.
12 
13 ### Legacy Servers
14 
15 Older server versions can be found in the V# branches of this repository. Note that V4 is nearly fully incompatible with existing installations. Only some static files may be copied over: https://github.com/tgstation/tgstation-server#static-files
16 
17 ## Setup
18 
19 ### Pre-Requisites
20 
21 - [ASP .NET Core Runtime (>= v3.1)](https://dotnet.microsoft.com/download/dotnet-core/current/runtime) (Choose the option to `Run Server Apps` for your system) If you plan to install tgstation-server as a Windows service, you should also ensure that your .NET Framework runtime version is >= v4.7.2 (Download can be found on same page). Ensure that the `dotnet` executable file is in your system's `PATH` variable (or that of the user's that will be running the server).
22 - A [MariaDB](https://downloads.mariadb.org/), MySQL, or [Microsoft SQL Server](https://www.microsoft.com/en-us/download/details.aspx?id=55994) database engine is required
23 
24 ### Installation
25 
26 1. [Download the latest V4 release .zip](https://github.com/tgstation/tgstation-server/releases/latest). The `ServerService` package will only work on Windows. Choose `ServerConsole` if that is not your target OS or you prefer not to use the Windows service.
27 2. Extract the .zip file to where you want the server to run from. Note the account running the server must have write and delete access to the `lib` subdirectory.
28 
29 #### Windows
30 
31 If you wish to install the TGS as a service, run `Tgstation.Server.Host.Service.exe`. It should prompt you to install it. Click `Yes` and accept a potential UAC elevation prompt and the setup wizard should run.
32 
33 #### Linux (Native)
34 
35 We recommend using Docker for Linux installations, see below. The content of this parent section may be skipped if you choose to do so.
36 
37 The following dependencies are required to run tgstation-server on Linux alongside the .NET Core runtime
38 
39 - libc6-i386
40 - libstdc++6:i386
41 - libssl1.0.0
42 - gcc-multilib (Only on 64-bit systems)
43 
44 Note that tgstation-server has only ever been tested on Linux via it's [docker environment](build/Dockerfile#L22). If you are having trouble with something in a native installation, or figure out a required workaround, please contact project maintainers so this documentation may be better updated.
45 
46 #### Docker (Linux)
47 
48 tgstation-server supports running in a docker container and is the recommended deployment method for Linux systems. 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 <your tag name>` in the repository root.
49 
50 To create a container run
51 ```sh
52 docker run \
53  -ti \ #start interactive for manual configuration
54  --restart=always \ #if you want maximum uptime
55  --network="host" \ #if your sql server is on the same machine
56  --name="tgs" \ #or whatever else you wanna call it
57  --cap-add=sys_nice \ #allows tgs to schedule DreamDaemon as a higher priority process
58  --init \ #reaps potential zombie processes
59  -p <tgs port>:80 \
60  -p 0.0.0.0:<public game port>:<public game port> \
61  -v /path/to/your/configfile/directory:/config_data \ #only if you want to use manual configuration
62  -v /path/to/store/instances:/tgs4_instances \
63  -v /path/to/your/log/folder:/tgs_logs \
64  tgstation/server:<release version> #replace this with <your tag name> if you built the image locally
65 ```
66 with any additional options you desire (i.e. You'll have to expose more game ports in order to host more than one instance).
67 
68 Note although `/app/lib` is specified as a volume mount point in the `Dockerfile`, unless you REALLY know what you're doing. Do not mount any volumes over this for fear of breaking your container.
69 
70 The configuration option `General:ValidInstancePaths` will be preconfigured to point to `/tgs4_instances`. It is recommended you don't change this.
71 
72 Note that this container is meant to be long running. Updates are handled internally as opposed to at the container level.
73 
74 If using manual configuration, before starting your container make sure the aforementioned `appsettings.Production.json` is setup properly. See below
75 
76 ### Configuring
77 
78 The first time you run TGS4 you should be prompted with a configuration wizard which will guide you through setting up your appsettings.Production.json
79 
80 This wizard will, generally, run whenever the server is launched without detecting the config json. Follow the instructions below to perform this process manually.
81 
82 #### Manual Configuration
83 
84 Create an `appsettings.Production.json` file next to `appsettings.json`. This will override the default settings in appsettings.json with your production settings. There are a few keys meant to be changed by hosts. Modifying any config files while the server is running will trigger a safe restart (Keeps DreamDaemon's running). Note these are all case-sensitive:
85 
86 - `General:MinimumPasswordLength`: Minimum password length requirement for database users
87 
88 - `General:ValidInstancePaths`: Array meant to limit the directories in which instances may be created.
89 
90 - `General:UserLimit`: Maximum number of users that may be created
91 
92 - `General:InstanceLimit`: Maximum number of instances that may be created
93 
94 - `General:GitHubAccessToken`: Specify a GitHub personal access token with no scopes here to highly mitigate the possiblity of 429 response codes from GitHub requests
95 
96 - `FileLogging:Directory`: Override the default directory where server logs are stored. Default is C:/ProgramData/tgstation-server/logs on Windows, /usr/share/tgstation-server/logs otherwise
97 
98 - `FileLogging:LogLevel`: Can be one of `Trace`, `Debug`, `Information`, `Warning`, `Error`, or `Critical`. Restricts what is put into the log files. Currently `Debug` is reccommended for help with error reporting.
99 
100 - `Kestrel:Endpoints:Http:Url`: The URL (i.e. interface and ports) your application should listen on. General use case should be `http://localhost:<port>` for restricted local connections. See the Remote Access section for configuring public access to the World Wide Web. This doesn't need to be changed using the docker setup and should be mapped with the `-p` option instead
101 
102 - `Database:DatabaseType`: Can be one of `SqlServer`, `MariaDB`, `MySql`, or `Sqlite`.
103 
104 - `Database:MySqlServerVersion`: The version of MySql/MariaDB the database resides on, can be left as null for attempted auto detection. Used by the MySQL/MariaDB provider for selection of [certain features](https://github.com/PomeloFoundation/Pomelo.EntityFrameworkCore.MySql/blob/2.2.6/src/EFCore.MySql/Storage/Internal/ServerVersion.cs) ignore at your own risk. A string in the form `<major>.<minor>.<patch>`
105 
106 - `Database:ConnectionString`: Connection string for your database. Click [here](https://www.developerfusion.com/tools/sql-connection-string/) for an SQL Server generator or see [here](https://www.connectionstrings.com/mysql/) for a MySQL guide ([You should probably use '127.0.0.1' instead of 'localhost'](https://stackoverflow.com/questions/19712307/mysql-localhost-127-0-0-1)).
107 
108 - `ControlPanel:Enable`: Enable the javascript based control panel to be served from the server via /index.html
109 
110 - `ControlPanel:AllowAnyOrigin`: Set the Access-Control-Allow-Origin header to * for all responses (also enables all headers and methods)
111 
112 - `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`
113 
114 ### Database Configuration
115 
116 If using a MariaDB/MySQL server, our client library [recommends you set 'utf8mb4' as your default charset](https://github.com/PomeloFoundation/Pomelo.EntityFrameworkCore.MySql#1-recommended-server-charset) disregard at your own risk.
117 
118 The user created for the application will need the privilege to create databases on the first run, do not create the database for it. Once the initial set of migrations is run, the create right may be revoked. The user should maintain DDL rights though for applying future migrations
119 
120 Note that the ratio of application installations to databases is 1:1. Do not attempt to share a database amongst multiple TGS installations.
121 
122 ### Starting
123 
124 For the Windows service version start the `tgstation-server-4` service. If it fails to start, check the Windows event log under Windows/Application for entries from tgstation-server-4 for errors.
125 
126 For the console version run `dotnet Tgstation.Server.Host.Console.dll` in the installation directory. The `tgs.bat` and `tgs.sh` shell scripts are shortcuts for this. If on Windows, you must do this as admin to give the server permission to install the required DirectX dependency for certain 512 BYOND versions as well as create symlinks.
127 
128 For the docker version run `docker start <your container name>`
129 
130 Test your server is running by visiting the local port in your browser. You should receive a 401 Unauthorized response (You may need to view the developer console). Otherwise an error page will be present.
131 
132 ### Stopping
133 
134 Note that the live detach for DreamDaemon servers is only supported for updates or restarts via the API at this time. Stopping tgstation-server will TERMINATE ALL CHILD DREAMDAEMON SERVERS.
135 
136 For the Windows service version stop the `tgstation-server-4` service
137 
138 For the console version press `Ctrl+C` or send a SIGQUIT to the ORIGINAL dotnet process
139 
140 For the docker version run `docker stop <your container name>`
141 
142 ## Integrating
143 
144 tgstation-server 4 currently REQUIRES the DMAPI to be integrated into any BYOND codebase which plans on being used by it. The integration process is a fairly simple set of code changes.
145 
146 1. Copy the [latest release of the DMAPI](https://github.com/tgstation/tgstation-server/releases) anywhere in your code base. `tgs.dm` can be seperated from the `tgs` folder, but do not modify or move the contents of the `tgs` folder
147 2. Modify your `.dme`(s) to include the `tgs.dm` and `tgs/includes.dm` files (ORDER OF APPEARANCE IS MANDATORY)
148 3. Follow the instructions in `tgs.dm` to integrate the API with your codebase.
149 
150 The DMAPI is fully backwards compatible and should function with any tgstation-server version to date. Updates can be performed in the same manner. Using the `TGS_EXTERNAL_CONFIGURATION` is recommended in order to make the process as easy as replacing `tgs.dm` and the `tgs` folder with a newer version
151 
152 ### Example
153 
154 Here is a bare minimum example project that implements the essential code changes for integrating the DMAPI
155 
156 Before `tgs.dm`:
157 ```dm
158 //Remember, every codebase is different, you probably have better methods for these defines than the ones given here
159 #define TGS_EXTERNAL_CONFIGURATION
160 #define TGS_DEFINE_AND_SET_GLOBAL(Name, Value) var/global/##Name = ##Value
161 #define TGS_READ_GLOBAL(Name) global.##Name
162 #define TGS_WRITE_GLOBAL(Name, Value) global.##Name = ##Value
163 #define TGS_WORLD_ANNOUNCE(message) world << ##message
164 #define TGS_INFO_LOG(message) world.log << "TGS Info: [##message]"
165 #define TGS_ERROR_LOG(message) world.log << "TGS Error: [##message]"
166 #define TGS_NOTIFY_ADMINS(event) world.log << "TGS Admin Message: [##event]"
167 #define TGS_CLIENT_COUNT global.client_cout
168 #define TGS_PROTECT_DATUM(Path) // Leave blank if your codebase doesn't give administrators code reflection capabilities
169 ```
170 
171 Anywhere else:
172 ```dm
173 var/global/client_count = 0
174 
175 /world/New()
176  ..()
177  TgsNew()
178  TgsInitializationsComplete()
179 
180 /world/Reboot()
181  TgsReboot()
182  ..()
183 
184 /world/Topic()
185  TGS_TOPIC
186  ..()
187 
188 /client/New()
189  ..()
190  ++global.client_count
191 
192 /client/Del()
193  ..()
194  --global.client_count
195 ```
196 
197 ## Remote Access
198 
199 tgstation-server is an [ASP.Net Core](https://docs.microsoft.com/en-us/aspnet/core/) app based on the Kestrel web server. This section is meant to serve as a general use case overview, but the entire Kestrel configuration can be modified to your liking with the configuration JSON. See [the official documentation](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel) for details.
200 
201 Exposing the builtin Kestrel server to the internet directly over HTTP is highly not reccommended due to the lack of security. The recommended way to expose tgstation-server to the internet is to host it through a reverse proxy with HTTPS support. Here are some step by step examples to achieve this for major web servers.
202 
203 System administrators will most likely have their own configuration plans, but here are some basic guides for beginners.
204 
205 Once complete, test that your configuration worked by visiting your proxy site from a browser on a different computer. You should recieve a 401 Unauthorized response.
206 
207 ### IIS (Reccommended for Windows)
208 
209 1. Acquire an HTTPS certificate. The easiet free way for Windows is [win-acme](https://github.com/PKISharp/win-acme) (requires you to set up the website first)
210 2. Install the [Web Platform Installer](https://www.microsoft.com/web/downloads/platform.aspx)
211 3. Open the web platform installer in the IIS Manager and install the Application Request Routing 3.0 module
212 4. Create a new website, bind it to HTTPS only with your chosen certificate and exposed port. The physical path won't matter since it won't be used. Use `Require Server Name Indication` if you want to limit requests to a specific URL prefix.
213 5. Close and reopen the IIS Manager
214 5. Open the site and navigate to the `URL Rewrite` module
215 6. In the `Actions` Pane on the right click `Add Rule(s)...`
216 7. For the rule template, select `Reverse Proxy` under `Inbound and Outbound Rules` and click `OK`
217 8. You may get a prompt about enabling proxy functionality. Click `OK`
218 9. In the window that appears set the `Inbound Rules` textbox to the URL of your tgstation-server i.e. `http://localhost:5000`. Ensure `Enable SSL Offloading` is checked, then click `OK`
219 
220 ### Caddy (Reccommended for Linux, or those unfamilar with configuring NGINX or Apache)
221 
222 1. Setup a basic website configuration. Instructions on how to do so are out of scope.
223 2. In your Caddyfile, under a server entry, add the following (replace 8080 with the port TGS is hosted on):
224 ```
225 proxy /tgs localhost:8080 {
226  transparent
227 }
228 ```
229 
230 See https://caddyserver.com/docs/proxy
231 
232 ### NGINX (Reccommended for Linux)
233 
234 1. Setup a basic website configuration. Instructions on how to do so are out of scope.
235 2. Acquire an HTTPS certificate, likely via Let's Encrypt, and configure NGINX to use it.
236 3. Setup a path under a server like the following (replace 8080 with the port TGS is hosted on):
237 ```
238 location /tgs {
239  proxy_pass http://127.0.0.1:8080;
240  break;
241 }
242 ```
243 
244 See https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/
245 
246 ### Apache
247 
248 1. Ensure the `mod_proxy` extension is installed.
249 2. Setup a basic website configuration. Instructions on how to do so are out of scope.
250 3. Acquire an HTTPS certificate, likely via Let's Encrypt, and configure Apache to use it.
251 4. Under a VirtualHost entry, setup the following (replace 8080 with the port TGS is hosted on):
252 ```
253 ProxyPass / http://127.0.0.1:8080
254 ProxyPassReverse / http://127.0.0.1:8080
255 ```
256 
257 See https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html
258 
259 Example VirtualHost Entry
260 ```
261 <IfModule mod_ssl.c>
262 <VirtualHost *:443>
263  ServerName tgs_subdomain.example.com
264 
265  SSLEngine on
266  SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
267  SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
268 
269  ProxyPass / http://127.0.0.1:8080/
270  ProxyPassReverse / http://127.0.0.1:8080/
271 </VirtualHost>
272 </IfModule>
273 ```
274 
275 ## Usage
276 
277 tgstation-server v4 is controlled via a RESTful HTTP json API. Documentation on this API can be found [here](https://tgstation.github.io/tgstation-server/api.html). This section serves to document the concepts of the server. The API is versioned separately from the release version. A specification for it can be found in the api-vX.X.X git releases/tags.
278 
279 ### Users
280 
281 All actions apart from logging in must be taken by a user. TGS installs with one default user whose credentials can be found [here](src/Tgstation.Server.Api/Models/User.cs). It is recommended to disable this user ASAP as it is used to create Jobs that are started by the server itself. If access to all users is lost, the default user can be reset using the `Database:ResetAdminPassword` configuration setting.
282 
283 Users can be enabled/disabled and have a very granular set of rights associated to them that determine the actions they are allowed to take (i.e. Modify the user list or create instances). Users can be _database based_ or _system based_. Database users are your standard web users with a username and password. System users, on the otherhand, are authenticated with the host OS. These users cannot have their password or names changed by TGS as they are managed by the system (and in reverse, login tokens don't expire when their password changes). The benefit to having these users is it allows the use of system ACLs for static file control. More on that later.
284 
285 ### Instances
286 
287 A TGS deployment is made up with a set of instances, which each represent a production BYOND server. As many instances as desired can be created. Be aware, however, due to the nature of BYOND, this will quickly result in system resource exhaustion.
288 
289 An instance is stored in a single folder anywhere on a system and is made up of several components: The source code git repository, the BYOND installations, the compiler, the watchdog, chat bots, and static file management systems.
290 
291 ##### Instance Users
292 
293 All users with access to an instance have an InstanceUser object associated with the two that defines more rights specific to that instance (i.e. Deploy code, modify bots, edit other InstanceUsers).
294 
295 #### Repository
296 
297 The `Repository` folder is a git repository containing the code of the game you wish to host. It can be cloned from any public or private remote repository and has capabilities to affect changes back to it. All the standard benefits of git are utilized (i.e. check out any revision or reference).
298 
299 Additional features become available if the remote repository is hosted on https://github.com/. Namely the Test Merge feature, which allows you to take a pull request opened on the repository and compile it into a game deployment for testing. Information about test merges is available in game via the DMAPI and via the main API as well.
300 
301 Manual operations on the repository while an instance is running may lead to git data corruption. Thankfully, it's simple enough to delete and reclone the repository via the API.
302 
303 #### Byond
304 
305 The `Byond` folder contains installations of [BYOND](https://secure.byond.com/) versions. The version which is used by your game code can be changed on a whim (Note that only versions >= 511.1385 have been thouroughly tested. Lower versions should work but if one doesn't function, please open an issue report) and the server will take care of installing it.
306 
307 #### Compiler
308 
309 The compiler deploys code from the `Repository` folder to the `Game` folder and compiles it either by autodetecting the `.dme` or having it set by configuration. Several other step are also run such as validating the DMAPI version and creating symlinks for static files are done at this point. The compiler also applies server side code modifications and duplicates compiled code for the watchdog as well (See following section).
310 
311 #### Watchdog
312 
313 The watchdog is responsible for starting and keeping your server running. It functions by launching two servers which are hot-swapped on `/world/Reboot`s and during crashes to prevent downtime. This hot swapping feature is also what allows TGS to deploy updates to live servers without bringing them down.
314 
315 DreamDaemon can be finicky and will crash with several high load games or bad DM code. The watchdog has several failure prevention methods to keep at least one server running while these issues are sorted out.
316 
317 #### Chat Bots
318 
319 TGS supports creating infinite chat bots for notifying staff or players of things like code deployments and uptime in. Currently the following providers are supported
320 
321 - Internet Relay Chat (IRC)
322 - Discord
323 
324 More can be added by providing a new implementation of the [IProvider](src/Tgstation.Server.Host/Components/Chat/Providers/IProvider.cs) interface
325 
326 Bots have a set of built-in commands that can be triggered via `!tgs`, mentioning, or private messaging them. Along with these, custom commands can be defined using the DMAPI by creating a subtype of the `/datum/tgs_chat_command` type (See `tgs.dm` for details). Invocation for custom commands can be restricted to certain channels.
327 
328 #### Static Files
329 
330 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.
331 
332 The `StaticFiles` folder contains 3 root folders which cannot be deleted and operate under special rules
333  - `CodeModifications`
334  - `EventScripts`
335  - `GameStaticFiles`
336 
337 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.
338 
339 This folder may be freely modified manually just beware this may cause in-progress deployments to error if done on Windows systems.
340 
341 #### CodeModifications
342 
343 When a deployment is made by the compiler, all the contents of this folder are copied over the repository contents. Then one of two code change modes are selected based on the prescense of certain files.
344 
345 If `<target dme>.dm` is present, that .dme will be used instead of the repository's `.dme`
346 
347 Otherwise the files `HeadInclude.dm` and `TailInclude.dm` are searched for and added as include lines to the top and bottom of the target `.dme` repsectively if they exist. These files can contain any valid DreamMaker code (Including `#include`ing other `.dm` files!) allowing you to modify the a repository's code on a per instance basis
348 
349 #### EventScripts
350 
351 This folder can contain anything. But, when certain events occur in the instance, TGS will look here for `.bat` or `.sh` files with the same name and run those with corresponding arguments. List of supported events can be found [here](src/Tgstation.Server.Host/Components/StaticFiles/Configuration.cs#L28) (subject to expansion) list of event parameters can be found [here](src/Tgstation.Server.Host/Components/EventType.cs)
352 
353 #### GameStaticFiles
354 
355 Any files and folders contained in this root level of this folder will be symbolically linked to all deployments at the time they are created. This allows persistent game data (BYOND `.sav`s or code configuration files for example) to persist across all deployments. This folder contains a .tgsignore file which can be used to prevent symlinks from being generated by entering the names of files and folders (1 per line)
356 
357 ### Updating
358 
359 TGS 4 can self update without stopping your DreamDaemon servers. Any V4 release made to this repository is bound by a contract that allows changes of the runtime assemblies without stopping your servers. Database migrations are automatically applied as well. Because of this REVERTING TO LOWER VERSIONS IS NOT OFFICIALLY SUPPORTED, do so at your own risk (check changes made to `/src/Tgstation.Server.Host/Models/Migrations`).
360 
361 ### Clients
362 
363 Here are tools for interacting with the TGS 4 web API
364 
365 - [tgstation-server-control-panel]: Official client and included with the server. A react web app for using tgstation-server.
366 - [Tgstation.Server.ControlPanel](https://github.com/tgstation/Tgstation.Server.ControlPanel): Official client. A cross platform GUI for using tgstation-server
367 - [Tgstation.Server.Client](https://www.nuget.org/packages/Tgstation.Server.Client): A nuget .NET Standard 2.0 TAP based library for communicating with tgstation-server
368 - [Tgstation.Server.Api](https://www.nuget.org/packages/Tgstation.Server.Api): A nuget .NET Standard 2.0 library containing API definitions for tgstation-server
369 - [Postman](https://www.getpostman.com/): This repository contains [TGS.postman_collection.json](tools/TGS.postman_collection.json) which is used during development for testing. Contains example requests for all endpoints but takes some knowledge to use (Note that the pre-request script is configured to login the default admin user for every request)
370 
371 Contact project maintainers to get your client added to this list
372 
373 ## Backup/Restore
374 
375 Note that tgstation-server is NOT a backup solution, the onus is on the server runners.
376 
377 The `Repository` folder should be backed up on the remote server, do not rely on the instance copy to store changes.
378 
379 The `BYOND` and `Game` folders should never be backed up due to being intertwined with instance data.
380 
381 The `Configuration` folder should be fully backed up.
382 
383 The database should be fully backed up.
384 
385 To restore an installation from backups, first restore the instance `Configuration` folder in its new home. Then restore the database, modifying the `Path` column in the `Instances` table where necessary to point to the new instances. Then start the server pointed at the new database.
386 
387 Should you end up with a lost database for some reason or want to reattach a detached instance you can reattach an existing folder by creating an empty file named `TGS4_ALLOW_INSTANCE_ATTACH` inside it (This is automatically created when detaching instances). Then create a new instance with that path, this will bypass the empty folder check. Note that this will not restore things such as user permissions, server config options, or deployment metadata. Those must be reconfigured manually.
388 
389 ## Troubleshooting
390 
391 Feel free to ask for help at the coderbus discord in \#hosting-questions: https://discord.gg/Vh8TJp9. Cyberboss#8246 can answer most questions.
392 
393 ## Contributing
394 
395 * See [CONTRIBUTING.md](.github/CONTRIBUTING.md)
396 
397 ## Licensing
398 
399 * The DMAPI for the project is licensed under the MIT license.
400 * The /tg/station 13 icon is licensed under [Creative Commons 3.0 BY-SA](http://creativecommons.org/licenses/by-sa/3.0/).
401 * The remainder of the project is licensed under [GNU AGPL v3](http://www.gnu.org/licenses/agpl-3.0.html)
402 
403 See the files in the `/src/DMAPI` tree for the MIT license
+Go to the documentation of this file.
1 # tgstation-server v4:
2 
3 [![Build status](https://ci.appveyor.com/api/projects/status/7t1h7bvuha0p9j5f/branch/master?svg=true)](https://ci.appveyor.com/project/Cyberboss/tgstation-server-tools/branch/master) [![Build Status](https://travis-ci.org/tgstation/tgstation-server.svg?branch=master)](https://travis-ci.org/tgstation/tgstation-server) [![codecov](https://codecov.io/gh/tgstation/tgstation-server/branch/master/graph/badge.svg)](https://codecov.io/gh/tgstation/tgstation-server)
4 
5 [![GitHub license](https://img.shields.io/github/license/tgstation/tgstation-server.svg)](LICENSE) [![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/tgstation/tgstation-server.svg)](http://isitmaintained.com/project/tgstation/tgstation-server "Average time to resolve an issue") [![NuGet version](https://img.shields.io/nuget/v/Tgstation.Server.Api.svg)](https://www.nuget.org/packages/Tgstation.Server.Api) [![NuGet version](https://img.shields.io/nuget/v/Tgstation.Server.Client.svg)](https://www.nuget.org/packages/Tgstation.Server.Client)
6 
7 [![forthebadge](http://forthebadge.com/images/badges/made-with-c-sharp.svg)](http://forthebadge.com) [![forinfinityandbyond](https://user-images.githubusercontent.com/5211576/29499758-4efff304-85e6-11e7-8267-62919c3688a9.gif)](https://www.reddit.com/r/SS13/comments/5oplxp/what_is_the_main_problem_with_byond_as_an_engine/dclbu1a)
8 
9 [![forthebadge](http://forthebadge.com/images/badges/built-with-love.svg)](http://forthebadge.com) [![forthebadge](http://forthebadge.com/images/badges/60-percent-of-the-time-works-every-time.svg)](http://forthebadge.com)
10 
11 This is a toolset to manage production BYOND servers. It includes the ability to update the server without having to stop or shutdown the server (the update will take effect on a "reboot" of the server) the ability start the server and restart it if it crashes, as well as systems for managing code and game files, and merging GitHub Pull Requests for test deployments.
12 
13 ### Legacy Servers
14 
15 Older server versions can be found in the V# branches of this repository. Note that V4 is nearly fully incompatible with existing installations. Only some static files may be copied over: https://github.com/tgstation/tgstation-server#static-files
16 
17 ## Setup
18 
19 ### Pre-Requisites
20 
21 - [ASP .NET Core Runtime (>= v3.1)](https://dotnet.microsoft.com/download/dotnet-core/current/runtime) (Choose the option to `Run Server Apps` for your system) If you plan to install tgstation-server as a Windows service, you should also ensure that your .NET Framework runtime version is >= v4.7.2 (Download can be found on same page). Ensure that the `dotnet` executable file is in your system's `PATH` variable (or that of the user's that will be running the server).
22 - A [MariaDB](https://downloads.mariadb.org/), MySQL, or [Microsoft SQL Server](https://www.microsoft.com/en-us/download/details.aspx?id=55994) database engine is required
23 
24 ### Installation
25 
26 1. [Download the latest V4 release .zip](https://github.com/tgstation/tgstation-server/releases/latest). The `ServerService` package will only work on Windows. Choose `ServerConsole` if that is not your target OS or you prefer not to use the Windows service.
27 2. Extract the .zip file to where you want the server to run from. Note the account running the server must have write and delete access to the `lib` subdirectory.
28 
29 #### Windows
30 
31 If you wish to install the TGS as a service, run `Tgstation.Server.Host.Service.exe`. It should prompt you to install it. Click `Yes` and accept a potential UAC elevation prompt and the setup wizard should run.
32 
33 #### Linux (Native)
34 
35 We recommend using Docker for Linux installations, see below. The content of this parent section may be skipped if you choose to do so.
36 
37 The following dependencies are required to run tgstation-server on Linux alongside the .NET Core runtime
38 
39 - libc6-i386
40 - libstdc++6:i386
41 - libssl1.0.0
42 - gcc-multilib (Only on 64-bit systems)
43 
44 Note that tgstation-server has only ever been tested on Linux via it's [docker environment](build/Dockerfile#L22). If you are having trouble with something in a native installation, or figure out a required workaround, please contact project maintainers so this documentation may be better updated.
45 
46 #### Docker (Linux)
47 
48 tgstation-server supports running in a docker container and is the recommended deployment method for Linux systems. 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 <your tag name>` in the repository root.
49 
50 To create a container run
51 ```sh
52 docker run \
53  -ti \ #start interactive for manual configuration
54  --restart=always \ #if you want maximum uptime
55  --network="host" \ #if your sql server is on the same machine
56  --name="tgs" \ #or whatever else you wanna call it
57  --cap-add=sys_nice \ #allows tgs to schedule DreamDaemon as a higher priority process
58  --init \ #reaps potential zombie processes
59  -p <tgs port>:80 \
60  -p 0.0.0.0:<public game port>:<public game port> \
61  -v /path/to/your/configfile/directory:/config_data \ #only if you want to use manual configuration
62  -v /path/to/store/instances:/tgs4_instances \
63  -v /path/to/your/log/folder:/tgs_logs \
64  tgstation/server:<release version> #replace this with <your tag name> if you built the image locally
65 ```
66 with any additional options you desire (i.e. You'll have to expose more game ports in order to host more than one instance).
67 
68 - Important note about port exposure: The internal port used by DreamDaemon _**MUST**_ match the port you want users to connect on. If it doesn't, you'll still be able to have them connect HOWEVER links from the BYOND hub will point at what DreamDaemon thinks the port is.
69 
70 Note although `/app/lib` is specified as a volume mount point in the `Dockerfile`, unless you REALLY know what you're doing. Do not mount any volumes over this for fear of breaking your container.
71 
72 The configuration option `General:ValidInstancePaths` will be preconfigured to point to `/tgs4_instances`. It is recommended you don't change this.
73 
74 Note that this container is meant to be long running. Updates are handled internally as opposed to at the container level.
75 
76 If using manual configuration, before starting your container make sure the aforementioned `appsettings.Production.json` is setup properly. See below
77 
78 ### Configuring
79 
80 The first time you run TGS4 you should be prompted with a configuration wizard which will guide you through setting up your appsettings.Production.json
81 
82 This wizard will, generally, run whenever the server is launched without detecting the config json. Follow the instructions below to perform this process manually.
83 
84 #### Manual Configuration
85 
86 Create an `appsettings.Production.json` file next to `appsettings.json`. This will override the default settings in appsettings.json with your production settings. There are a few keys meant to be changed by hosts. Modifying any config files while the server is running will trigger a safe restart (Keeps DreamDaemon's running). Note these are all case-sensitive:
87 
88 - `General:MinimumPasswordLength`: Minimum password length requirement for database users
89 
90 - `General:ValidInstancePaths`: Array meant to limit the directories in which instances may be created.
91 
92 - `General:UserLimit`: Maximum number of users that may be created
93 
94 - `General:InstanceLimit`: Maximum number of instances that may be created
95 
96 - `General:GitHubAccessToken`: Specify a GitHub personal access token with no scopes here to highly mitigate the possiblity of 429 response codes from GitHub requests
97 
98 - `FileLogging:Directory`: Override the default directory where server logs are stored. Default is C:/ProgramData/tgstation-server/logs on Windows, /usr/share/tgstation-server/logs otherwise
99 
100 - `FileLogging:LogLevel`: Can be one of `Trace`, `Debug`, `Information`, `Warning`, `Error`, or `Critical`. Restricts what is put into the log files. Currently `Debug` is reccommended for help with error reporting.
101 
102 - `Kestrel:Endpoints:Http:Url`: The URL (i.e. interface and ports) your application should listen on. General use case should be `http://localhost:<port>` for restricted local connections. See the Remote Access section for configuring public access to the World Wide Web. This doesn't need to be changed using the docker setup and should be mapped with the `-p` option instead
103 
104 - `Database:DatabaseType`: Can be one of `SqlServer`, `MariaDB`, `MySql`, or `Sqlite`.
105 
106 - `Database:MySqlServerVersion`: The version of MySql/MariaDB the database resides on, can be left as null for attempted auto detection. Used by the MySQL/MariaDB provider for selection of [certain features](https://github.com/PomeloFoundation/Pomelo.EntityFrameworkCore.MySql/blob/2.2.6/src/EFCore.MySql/Storage/Internal/ServerVersion.cs) ignore at your own risk. A string in the form `<major>.<minor>.<patch>`
107 
108 - `Database:ConnectionString`: Connection string for your database. Click [here](https://www.developerfusion.com/tools/sql-connection-string/) for an SQL Server generator or see [here](https://www.connectionstrings.com/mysql/) for a MySQL guide ([You should probably use '127.0.0.1' instead of 'localhost'](https://stackoverflow.com/questions/19712307/mysql-localhost-127-0-0-1)).
109 
110 - `ControlPanel:Enable`: Enable the javascript based control panel to be served from the server via /index.html
111 
112 - `ControlPanel:AllowAnyOrigin`: Set the Access-Control-Allow-Origin header to * for all responses (also enables all headers and methods)
113 
114 - `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`
115 
116 ### Database Configuration
117 
118 If using a MariaDB/MySQL server, our client library [recommends you set 'utf8mb4' as your default charset](https://github.com/PomeloFoundation/Pomelo.EntityFrameworkCore.MySql#1-recommended-server-charset) disregard at your own risk.
119 
120 The user created for the application will need the privilege to create databases on the first run, do not create the database for it. Once the initial set of migrations is run, the create right may be revoked. The user should maintain DDL rights though for applying future migrations
121 
122 Note that the ratio of application installations to databases is 1:1. Do not attempt to share a database amongst multiple TGS installations.
123 
124 ### Starting
125 
126 For the Windows service version start the `tgstation-server-4` service. If it fails to start, check the Windows event log under Windows/Application for entries from tgstation-server-4 for errors.
127 
128 For the console version run `dotnet Tgstation.Server.Host.Console.dll` in the installation directory. The `tgs.bat` and `tgs.sh` shell scripts are shortcuts for this. If on Windows, you must do this as admin to give the server permission to install the required DirectX dependency for certain 512 BYOND versions as well as create symlinks.
129 
130 For the docker version run `docker start <your container name>`
131 
132 Test your server is running by visiting the local port in your browser. You should receive a 401 Unauthorized response (You may need to view the developer console). Otherwise an error page will be present.
133 
134 ### Stopping
135 
136 Note that the live detach for DreamDaemon servers is only supported for updates or restarts via the API at this time. Stopping tgstation-server will TERMINATE ALL CHILD DREAMDAEMON SERVERS.
137 
138 For the Windows service version stop the `tgstation-server-4` service
139 
140 For the console version press `Ctrl+C` or send a SIGQUIT to the ORIGINAL dotnet process
141 
142 For the docker version run `docker stop <your container name>`
143 
144 ## Integrating
145 
146 tgstation-server 4 currently REQUIRES the DMAPI to be integrated into any BYOND codebase which plans on being used by it. The integration process is a fairly simple set of code changes.
147 
148 1. Copy the [latest release of the DMAPI](https://github.com/tgstation/tgstation-server/releases) anywhere in your code base. `tgs.dm` can be seperated from the `tgs` folder, but do not modify or move the contents of the `tgs` folder
149 2. Modify your `.dme`(s) to include the `tgs.dm` and `tgs/includes.dm` files (ORDER OF APPEARANCE IS MANDATORY)
150 3. Follow the instructions in `tgs.dm` to integrate the API with your codebase.
151 
152 The DMAPI is fully backwards compatible and should function with any tgstation-server version to date. Updates can be performed in the same manner. Using the `TGS_EXTERNAL_CONFIGURATION` is recommended in order to make the process as easy as replacing `tgs.dm` and the `tgs` folder with a newer version
153 
154 ### Example
155 
156 Here is a bare minimum example project that implements the essential code changes for integrating the DMAPI
157 
158 Before `tgs.dm`:
159 ```dm
160 //Remember, every codebase is different, you probably have better methods for these defines than the ones given here
161 #define TGS_EXTERNAL_CONFIGURATION
162 #define TGS_DEFINE_AND_SET_GLOBAL(Name, Value) var/global/##Name = ##Value
163 #define TGS_READ_GLOBAL(Name) global.##Name
164 #define TGS_WRITE_GLOBAL(Name, Value) global.##Name = ##Value
165 #define TGS_WORLD_ANNOUNCE(message) world << ##message
166 #define TGS_INFO_LOG(message) world.log << "TGS Info: [##message]"
167 #define TGS_ERROR_LOG(message) world.log << "TGS Error: [##message]"
168 #define TGS_NOTIFY_ADMINS(event) world.log << "TGS Admin Message: [##event]"
169 #define TGS_CLIENT_COUNT global.client_cout
170 #define TGS_PROTECT_DATUM(Path) // Leave blank if your codebase doesn't give administrators code reflection capabilities
171 ```
172 
173 Anywhere else:
174 ```dm
175 var/global/client_count = 0
176 
177 /world/New()
178  ..()
179  TgsNew()
180  TgsInitializationsComplete()
181 
182 /world/Reboot()
183  TgsReboot()
184  ..()
185 
186 /world/Topic()
187  TGS_TOPIC
188  ..()
189 
190 /client/New()
191  ..()
192  ++global.client_count
193 
194 /client/Del()
195  ..()
196  --global.client_count
197 ```
198 
199 ## Remote Access
200 
201 tgstation-server is an [ASP.Net Core](https://docs.microsoft.com/en-us/aspnet/core/) app based on the Kestrel web server. This section is meant to serve as a general use case overview, but the entire Kestrel configuration can be modified to your liking with the configuration JSON. See [the official documentation](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel) for details.
202 
203 Exposing the builtin Kestrel server to the internet directly over HTTP is highly not reccommended due to the lack of security. The recommended way to expose tgstation-server to the internet is to host it through a reverse proxy with HTTPS support. Here are some step by step examples to achieve this for major web servers.
204 
205 System administrators will most likely have their own configuration plans, but here are some basic guides for beginners.
206 
207 Once complete, test that your configuration worked by visiting your proxy site from a browser on a different computer. You should recieve a 401 Unauthorized response.
208 
209 ### IIS (Reccommended for Windows)
210 
211 1. Acquire an HTTPS certificate. The easiet free way for Windows is [win-acme](https://github.com/PKISharp/win-acme) (requires you to set up the website first)
212 2. Install the [Web Platform Installer](https://www.microsoft.com/web/downloads/platform.aspx)
213 3. Open the web platform installer in the IIS Manager and install the Application Request Routing 3.0 module
214 4. Create a new website, bind it to HTTPS only with your chosen certificate and exposed port. The physical path won't matter since it won't be used. Use `Require Server Name Indication` if you want to limit requests to a specific URL prefix.
215 5. Close and reopen the IIS Manager
216 5. Open the site and navigate to the `URL Rewrite` module
217 6. In the `Actions` Pane on the right click `Add Rule(s)...`
218 7. For the rule template, select `Reverse Proxy` under `Inbound and Outbound Rules` and click `OK`
219 8. You may get a prompt about enabling proxy functionality. Click `OK`
220 9. In the window that appears set the `Inbound Rules` textbox to the URL of your tgstation-server i.e. `http://localhost:5000`. Ensure `Enable SSL Offloading` is checked, then click `OK`
221 
222 ### Caddy (Reccommended for Linux, or those unfamilar with configuring NGINX or Apache)
223 
224 1. Setup a basic website configuration. Instructions on how to do so are out of scope.
225 2. In your Caddyfile, under a server entry, add the following (replace 8080 with the port TGS is hosted on):
226 ```
227 proxy /tgs localhost:8080 {
228  transparent
229 }
230 ```
231 
232 See https://caddyserver.com/docs/proxy
233 
234 ### NGINX (Reccommended for Linux)
235 
236 1. Setup a basic website configuration. Instructions on how to do so are out of scope.
237 2. Acquire an HTTPS certificate, likely via Let's Encrypt, and configure NGINX to use it.
238 3. Setup a path under a server like the following (replace 8080 with the port TGS is hosted on):
239 ```
240 location /tgs {
241  proxy_pass http://127.0.0.1:8080;
242  break;
243 }
244 ```
245 
246 See https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/
247 
248 ### Apache
249 
250 1. Ensure the `mod_proxy` extension is installed.
251 2. Setup a basic website configuration. Instructions on how to do so are out of scope.
252 3. Acquire an HTTPS certificate, likely via Let's Encrypt, and configure Apache to use it.
253 4. Under a VirtualHost entry, setup the following (replace 8080 with the port TGS is hosted on):
254 ```
255 ProxyPass / http://127.0.0.1:8080
256 ProxyPassReverse / http://127.0.0.1:8080
257 ```
258 
259 See https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html
260 
261 Example VirtualHost Entry
262 ```
263 <IfModule mod_ssl.c>
264 <VirtualHost *:443>
265  ServerName tgs_subdomain.example.com
266 
267  SSLEngine on
268  SSLCertificateFile /etc/letsencrypt/live/example.com/fullchain.pem
269  SSLCertificateKeyFile /etc/letsencrypt/live/example.com/privkey.pem
270 
271  ProxyPass / http://127.0.0.1:8080/
272  ProxyPassReverse / http://127.0.0.1:8080/
273 </VirtualHost>
274 </IfModule>
275 ```
276 
277 ## Usage
278 
279 tgstation-server v4 is controlled via a RESTful HTTP json API. Documentation on this API can be found [here](https://tgstation.github.io/tgstation-server/api.html). This section serves to document the concepts of the server. The API is versioned separately from the release version. A specification for it can be found in the api-vX.X.X git releases/tags.
280 
281 ### Users
282 
283 All actions apart from logging in must be taken by a user. TGS installs with one default user whose credentials can be found [here](src/Tgstation.Server.Api/Models/User.cs). It is recommended to disable this user ASAP as it is used to create Jobs that are started by the server itself. If access to all users is lost, the default user can be reset using the `Database:ResetAdminPassword` configuration setting.
284 
285 Users can be enabled/disabled and have a very granular set of rights associated to them that determine the actions they are allowed to take (i.e. Modify the user list or create instances). Users can be _database based_ or _system based_. Database users are your standard web users with a username and password. System users, on the otherhand, are authenticated with the host OS. These users cannot have their password or names changed by TGS as they are managed by the system (and in reverse, login tokens don't expire when their password changes). The benefit to having these users is it allows the use of system ACLs for static file control. More on that later.
286 
287 ### Instances
288 
289 A TGS deployment is made up with a set of instances, which each represent a production BYOND server. As many instances as desired can be created. Be aware, however, due to the nature of BYOND, this will quickly result in system resource exhaustion.
290 
291 An instance is stored in a single folder anywhere on a system and is made up of several components: The source code git repository, the BYOND installations, the compiler, the watchdog, chat bots, and static file management systems.
292 
293 ##### Instance Users
294 
295 All users with access to an instance have an InstanceUser object associated with the two that defines more rights specific to that instance (i.e. Deploy code, modify bots, edit other InstanceUsers).
296 
297 #### Repository
298 
299 The `Repository` folder is a git repository containing the code of the game you wish to host. It can be cloned from any public or private remote repository and has capabilities to affect changes back to it. All the standard benefits of git are utilized (i.e. check out any revision or reference).
300 
301 Additional features become available if the remote repository is hosted on https://github.com/. Namely the Test Merge feature, which allows you to take a pull request opened on the repository and compile it into a game deployment for testing. Information about test merges is available in game via the DMAPI and via the main API as well.
302 
303 Manual operations on the repository while an instance is running may lead to git data corruption. Thankfully, it's simple enough to delete and reclone the repository via the API.
304 
305 #### Byond
306 
307 The `Byond` folder contains installations of [BYOND](https://secure.byond.com/) versions. The version which is used by your game code can be changed on a whim (Note that only versions >= 511.1385 have been thouroughly tested. Lower versions should work but if one doesn't function, please open an issue report) and the server will take care of installing it.
308 
309 #### Compiler
310 
311 The compiler deploys code from the `Repository` folder to the `Game` folder and compiles it either by autodetecting the `.dme` or having it set by configuration. Several other step are also run such as validating the DMAPI version and creating symlinks for static files are done at this point. The compiler also applies server side code modifications and duplicates compiled code for the watchdog as well (See following section).
312 
313 #### Watchdog
314 
315 The watchdog is responsible for starting and keeping your server running. It functions by launching two servers which are hot-swapped on `/world/Reboot`s and during crashes to prevent downtime. This hot swapping feature is also what allows TGS to deploy updates to live servers without bringing them down.
316 
317 DreamDaemon can be finicky and will crash with several high load games or bad DM code. The watchdog has several failure prevention methods to keep at least one server running while these issues are sorted out.
318 
319 #### Chat Bots
320 
321 TGS supports creating infinite chat bots for notifying staff or players of things like code deployments and uptime in. Currently the following providers are supported
322 
323 - Internet Relay Chat (IRC)
324 - Discord
325 
326 More can be added by providing a new implementation of the [IProvider](src/Tgstation.Server.Host/Components/Chat/Providers/IProvider.cs) interface
327 
328 Bots have a set of built-in commands that can be triggered via `!tgs`, mentioning, or private messaging them. Along with these, custom commands can be defined using the DMAPI by creating a subtype of the `/datum/tgs_chat_command` type (See `tgs.dm` for details). Invocation for custom commands can be restricted to certain channels.
329 
330 #### Static Files
331 
332 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.
333 
334 The `StaticFiles` folder contains 3 root folders which cannot be deleted and operate under special rules
335  - `CodeModifications`
336  - `EventScripts`
337  - `GameStaticFiles`
338 
339 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.
340 
341 This folder may be freely modified manually just beware this may cause in-progress deployments to error if done on Windows systems.
342 
343 #### CodeModifications
344 
345 When a deployment is made by the compiler, all the contents of this folder are copied over the repository contents. Then one of two code change modes are selected based on the prescense of certain files.
346 
347 If `<target dme>.dm` is present, that .dme will be used instead of the repository's `.dme`
348 
349 Otherwise the files `HeadInclude.dm` and `TailInclude.dm` are searched for and added as include lines to the top and bottom of the target `.dme` repsectively if they exist. These files can contain any valid DreamMaker code (Including `#include`ing other `.dm` files!) allowing you to modify the a repository's code on a per instance basis
350 
351 #### EventScripts
352 
353 This folder can contain anything. But, when certain events occur in the instance, TGS will look here for `.bat` or `.sh` files with the same name and run those with corresponding arguments. List of supported events can be found [here](src/Tgstation.Server.Host/Components/StaticFiles/Configuration.cs#L28) (subject to expansion) list of event parameters can be found [here](src/Tgstation.Server.Host/Components/EventType.cs)
354 
355 #### GameStaticFiles
356 
357 Any files and folders contained in this root level of this folder will be symbolically linked to all deployments at the time they are created. This allows persistent game data (BYOND `.sav`s or code configuration files for example) to persist across all deployments. This folder contains a .tgsignore file which can be used to prevent symlinks from being generated by entering the names of files and folders (1 per line)
358 
359 ### Updating
360 
361 TGS 4 can self update without stopping your DreamDaemon servers. Any V4 release made to this repository is bound by a contract that allows changes of the runtime assemblies without stopping your servers. Database migrations are automatically applied as well. Because of this REVERTING TO LOWER VERSIONS IS NOT OFFICIALLY SUPPORTED, do so at your own risk (check changes made to `/src/Tgstation.Server.Host/Models/Migrations`).
362 
363 ### Clients
364 
365 Here are tools for interacting with the TGS 4 web API
366 
367 - [tgstation-server-control-panel]: Official client and included with the server. A react web app for using tgstation-server.
368 - [Tgstation.Server.ControlPanel](https://github.com/tgstation/Tgstation.Server.ControlPanel): Official client. A cross platform GUI for using tgstation-server
369 - [Tgstation.Server.Client](https://www.nuget.org/packages/Tgstation.Server.Client): A nuget .NET Standard 2.0 TAP based library for communicating with tgstation-server
370 - [Tgstation.Server.Api](https://www.nuget.org/packages/Tgstation.Server.Api): A nuget .NET Standard 2.0 library containing API definitions for tgstation-server
371 - [Postman](https://www.getpostman.com/): This repository contains [TGS.postman_collection.json](tools/TGS.postman_collection.json) which is used during development for testing. Contains example requests for all endpoints but takes some knowledge to use (Note that the pre-request script is configured to login the default admin user for every request)
372 
373 Contact project maintainers to get your client added to this list
374 
375 ## Backup/Restore
376 
377 Note that tgstation-server is NOT a backup solution, the onus is on the server runners.
378 
379 The `Repository` folder should be backed up on the remote server, do not rely on the instance copy to store changes.
380 
381 The `BYOND` and `Game` folders should never be backed up due to being intertwined with instance data.
382 
383 The `Configuration` folder should be fully backed up.
384 
385 The database should be fully backed up.
386 
387 To restore an installation from backups, first restore the instance `Configuration` folder in its new home. Then restore the database, modifying the `Path` column in the `Instances` table where necessary to point to the new instances. Then start the server pointed at the new database.
388 
389 Should you end up with a lost database for some reason or want to reattach a detached instance you can reattach an existing folder by creating an empty file named `TGS4_ALLOW_INSTANCE_ATTACH` inside it (This is automatically created when detaching instances). Then create a new instance with that path, this will bypass the empty folder check. Note that this will not restore things such as user permissions, server config options, or deployment metadata. Those must be reconfigured manually.
390 
391 ## Troubleshooting
392 
393 Feel free to ask for help at the coderbus discord in \#hosting-questions: https://discord.gg/Vh8TJp9. Cyberboss#8246 can answer most questions.
394 
395 ## Contributing
396 
397 * See [CONTRIBUTING.md](.github/CONTRIBUTING.md)
398 
399 ## Licensing
400 
401 * The DMAPI for the project is licensed under the MIT license.
402 * The /tg/station 13 icon is licensed under [Creative Commons 3.0 BY-SA](http://creativecommons.org/licenses/by-sa/3.0/).
403 * The remainder of the project is licensed under [GNU AGPL v3](http://www.gnu.org/licenses/agpl-3.0.html)
404 
405 See the files in the `/src/DMAPI` tree for the MIT license
Generated by   diff --git a/index.html b/index.html index f7bf936368..0173a3c90c 100644 --- a/index.html +++ b/index.html @@ -121,6 +121,9 @@ var searchBox = new SearchBox("searchBox", "search",false,'Search');

Docker (Linux)

tgstation-server supports running in a docker container and is the recommended deployment method for Linux systems. 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 <your tag name> in the repository root.

To create a container run

1 docker run \
2  -ti \ #start interactive for manual configuration
3  --restart=always \ #if you want maximum uptime
4  --network="host" \ #if your sql server is on the same machine
5  --name="tgs" \ #or whatever else you wanna call it
6  --cap-add=sys_nice \ #allows tgs to schedule DreamDaemon as a higher priority process
7  --init \ #reaps potential zombie processes
8  -p <tgs port>:80 \
9  -p 0.0.0.0:<public game port>:<public game port> \
10  -v /path/to/your/configfile/directory:/config_data \ #only if you want to use manual configuration
11  -v /path/to/store/instances:/tgs4_instances \
12  -v /path/to/your/log/folder:/tgs_logs \
13  tgstation/server:<release version> #replace this with <your tag name> if you built the image locally

with any additional options you desire (i.e. You'll have to expose more game ports in order to host more than one instance).

+

Note although /app/lib is specified as a volume mount point in the Dockerfile, unless you REALLY know what you're doing. Do not mount any volumes over this for fear of breaking your container.

The configuration option General:ValidInstancePaths will be preconfigured to point to /tgs4_instances. It is recommended you don't change this.

Note that this container is meant to be long running. Updates are handled internally as opposed to at the container level.