Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make watchdog guide more noob friendly #94

Merged
merged 3 commits into from
Dec 11, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 1 addition & 37 deletions src/en/general-development/setup/server-hosting-tutorial.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,43 +169,7 @@ This is for people running their own codebase and server and/or those who want a
[`SS14.Watchdog`](https://github.com/space-wizards/SS14.Watchdog/) (codename Ian) is our server-hosting wrapper thing, similar to TGS for BYOND (but much simpler for the time being). It handles auto updates, monitoring, automatic restarts, and administration. We recommend you use this for proper deployments.

### Installation
1. Download or clone the latest `SS14.Watchdog` source code (linked above)
2. Run `dotnet publish -c Release -r linux-x64 --no-self-contained`, replacing `linux-x64` with an identifier for your platform
3. Copy the `SS14.Watchdog/bin/Release/net6.0/linux-x64/publish` directory (check this path for your platform as necessary) to where you want to store your SS14 server files.

### Configuration
Configure the watchdog to add servers. Edit `appsettings.yml` inside the installed watchdog directory.

1. Uncomment and set `BaseURL`. This is the address that your game servers will use to communicate with the watchdog. The default value is fine for small setups. For example:
```yml
BaseUrl: https://builds.spacestation14.io/watchdog/
```

2. At the bottom of the config file, add a `Servers` YAML block, and then a `Instances` block inside of that. Inside the `Instances` block, add a block for each server that you plan to serve from this watchdog. For example:

```yml

Servers:
Instances:
wizards_den: # ID of your server.
Name: "Wizard's Den" # Name of the server - Note that this is NOT the name of the server on the hub, that is set for each server under game.hostname in their respective config.toml files.
ApiToken: "foobar" # A secret password that you make up (API token) for the watchdog to control this server (e.g. update, restart)
ApiPort: 1212 # API port OF THE GAME SERVER. This has to match the 1212 HTTP status API (described below). Otherwise the watchdog can't contact the game server for stuff.

# Auto update configuration. This can be left out if you do not need auto updates. Example is for our officially hosted builds.
# See below for alternatives.
UpdateType: "Manifest"
Updates:
ManifestUrl: "https://central.spacestation14.io/builds/wizards/manifest.json"

# Any environment variables you may want to specify.
EnvironmentVariables:
Foo: bar
wizards_den_two:
# Name of the second server
Name: "Wizard's Den 2"
# etc...
```
[`Refeer to this`](https://docs.spacestation14.com/en/server-hosting/setting-up-ss14-watchdog.html) for intructions on building and configuring Watchdog.

### Server Instance Folder

Expand Down
113 changes: 66 additions & 47 deletions src/en/server-hosting/setting-up-ss14-watchdog.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,10 @@ It is also worth going through the custom codebases section, especially if you i
Some of it's sort of altered slightly.
-->

<!--
Thanks I hate it
-->

[`SS14.Watchdog`](https://github.com/space-wizards/SS14.Watchdog/) (codename Ian) is our server-hosting wrapper thing, similar to TGS for BYOND (but much simpler for the time being). It handles auto updates, monitoring, automatic restarts, and administration. We recommend you use this for proper deployments.

## Setup Process
Expand All @@ -27,6 +31,8 @@ You need to have:

Both of these can be found at the [.NET 6 download page](https://dotnet.microsoft.com/en-us/download/dotnet/6.0).

On Linux/MacOS use your favourite package manager (apt, dnf, pacman, brew etc)

### 2. Build

The following set of commands should build the Watchdog on a Linux system. You'll have to adjust it according to your actual system, of course.
Expand All @@ -44,24 +50,8 @@ dotnet publish -c Release -r linux-x64 --no-self-contained

The contents of `SS14.Watchdog/bin/Release/net6.0/linux-x64/publish` can then be copied to some other place.

### 3. Configure

Before continuing, it is worth mentioning that the `SS14.Watchdog` executable assumes all configuration (such as `appsettings.yml`) and data is located in the current directory, not the directory the executable is in.

As such, for simplicity in updating the Watchdog, you should arrange a directory as so:

```
bin/ : This is the /publish/ directory previously created.
instances/ : This directory contains one subdirectory for each instance you have defined, i.e.:
instances/ERZ2/ : Directory for game instance ID `ERZ2`.
See "Server Instance Folder" below for details on the insides of one of these.
appsettings.yml : The configuration for the Watchdog.
This should initially be copied from `bin/appsettings.yml`.
```

The different aspects to the configuration are listed in the following sections.

### 4. Run
### 3. Run

Assuming you've followed the structure laid out above, you simply need to have a terminal at the "main directory", and run `bin/SS14.Watchdog`.

Expand Down Expand Up @@ -177,15 +167,13 @@ Secondly, you may want to simply force a server to be restarted.

These tasks can be achieved with the following commands:

`curl -v -X POST -u myInstance:spooky http://localhost:5000/instances/myInstance/restart`

`curl -v -X POST -u myInstance:spooky http://localhost:5000/instances/myInstance/update`
`curl -v -X POST -u myInstance:ApiToken http://localhost:5000/instances/myInstance/restart`

Here, `spooky` is the `ApiToken` of the instance `myInstance`.
`curl -v -X POST -u myInstance:ApiToken http://localhost:5000/instances/myInstance/update`

## Update Types

### For Vanilla Servers
### Manifest Update

```admonish info
The server still won't automatically be notified of updates, so see above for instructions.
Expand All @@ -203,36 +191,16 @@ Servers:
ManifestUrl: "https://central.spacestation14.io/builds/wizards/manifest.json"
```

### "Dummy" Update Provider

<!-- Nobody needs to know.
```admonish info
The "Local" update provider is the originally intended way to do what this update provider does.
However, since it's creation the game server itself has taken over what independent functionality the update provider had, and there are other disadvantages making Local more complicated to setup - so basically it's just worse.
```
-->

The "Dummy" update provider will fake an update whenever it is queried, and otherwise simply assume that a server has already been extracted to `bin/`.

As the Watchdog does not automatically periodically check for updates, the fake updates shouldn't get in the way.

To configure this, use the following update configuration in your `appsettings.yml`, in the entry for your server instance:

```yml
Servers:
Instances:
example:
# (skipped...)
UpdateType: "Dummy"
```

You will have to manually move files around and extract the server binaries.

Note that you should not move around or attempt to delete the files of a running server.

<!-- They keep breaking.
### Git-based Updates

```admonish danger "Here be dragons!"
Git-based update method is unmaintained. While it's the easiest to get started we can't really help you if it breaks. You are mostly on your own.
```

```admonish warning
Using Git-based updates in the intended manner may be in various states of "broken" because of various ways in which the repository can get into a state best described as, well, *broken*.
This shouldn't apply if you're just shipping precompiled updates to the server using Git, but that's also messy and not the intended way things were meant to work.
Expand Down Expand Up @@ -262,7 +230,6 @@ Servers:
# As of the introduction of delta updating this is now the better way to handle this.
HybridACZ: true
```
-->

### Jenkins Updates

Expand All @@ -279,6 +246,29 @@ Servers:
JobName: "Star"
```

### "Dummy" Update Provider

<!-- Nobody needs to know.
```admonish info
The "Local" update provider is the originally intended way to do what this update provider does.
However, since it's creation the game server itself has taken over what independent functionality the update provider had, and there are other disadvantages making Local more complicated to setup - so basically it's just worse.
```
-->

The "Dummy" update provider will fake an update whenever it is queried, and otherwise simply assume that a server has already been extracted to `bin/`.

As the Watchdog does not automatically periodically check for updates, the fake updates shouldn't get in the way.

To configure this, use the following update configuration in your `appsettings.yml`, in the entry for your server instance:

```yml
Servers:
Instances:
example:
# (skipped...)
UpdateType: "Dummy"
```

### Custom Auto Updates

Not supported, but it should be relatively trivial to edit the code for `SS14.Watchdog` to add support for whatever update mechanism you need. See `UpdateProvider.cs`.
Expand Down Expand Up @@ -346,6 +336,35 @@ nowish = datetime.datetime.now().isoformat()
print(json.dumps({"builds":{nowish: {"time": nowish, "client": {"url": "", "sha256": ""}, "server": {"linux-x64": {"url": "http://localhost:9283/SS14.Server_linux-x64.zip", "sha256": ""}}}}}))
```

## Systemd service

To allow the service to automatically start up with the server, you can make a service file. It will look something like this.

Of course, change it to the actual directory of your watchdog.

```/etc/systemd/system/SS14.Watchdog.service```
```toml
[Unit]
Description=SS14 Watchdog
After=network.target

[Service]
ExecStart=/path/to/SS14.Watchdog
WorkingDirectory=/path/to
Restart=always
# This is used for git method to not fail instantly.
Environment="DOTNET_CLI_HOME=/tmp"

[Install]
WantedBy=default.target
```
Now reload your systemd daemon and enable the service as you normally would.

```
systemctl daemon-reload
systemctl enable --now SS14.Watchdog
```

## General Troubleshooting

### Server keeps restarting every 30 seconds
Expand Down