feat: admin documentation/guides (#13)

* feat: add initial work on admin documentation

* fix: cleanup from review

Co-authored-by: haykam821 <24855774+haykam821@users.noreply.github.com>

* chore: more cleanup

* docs: finish documenting services

* fix: typo

Co-authored-by: haykam821 <24855774+haykam821@users.noreply.github.com>

---------

Co-authored-by: haykam821 <24855774+haykam821@users.noreply.github.com>

docs/admin/guides/new-contributor.md

@@ -0,0 +1,48 @@
+# New contributors
+
+Things to do for new contributors.
+
+## Build contributors
+
+- Grant them OP on the build server (feel free to give this out to anyone, the server has frequent backups)
+
+## Code contributors
+
+- Invite them to the GitHub organisation, and encourage minigame repositories that are going on the main server to be transfered to the org.
+
+## Assigning roles
+
+Try to complete all of these when you get the chance
+
+### Discord
+
+Grant them the contributor role, along with whichever specific roles fit (eg. code contributor, build contributor, translations contributor, etc).
+
+### In game
+
+```mcfunction
+/role assign <username> contributor
+/role assign <username> dev # if they are a code contributor
+/role assign <username> builder # if they are a build contributor
+```
+
+### Website cards
+
+1. Create a new file in the [`NucleoidMC/nucleoid-contributors`](https://github.com/NucleoidMC/nucleoid-contributors), under the folder `data/people/` named `theirusername.toml` (use all lower case, and no spaces or special characters).
+2. Fill out the file using the following template:
+```toml
+name = "their preferred display name (if unsure, ask)"
+groups = [
+    "code",
+    "building",
+    "art",
+    "community",
+    "translations",
+    "contributor", # generic contributor role, should only be added if none of the others apply
+]
+
+[socials]
+minecraft = "their minecraft uuid (for consistency, remove the -)"
+```
+3. Commit the file back to the repo, and run `sudo git pull` in `/var/www/nucleoid-contributors` (unfortunately we don't have auto-deployment yet, poke Ash to set it up if you get annoyed by this).
+4. Invite them to update the file (or if they're not familiar with GitHub, provide extras for you to put in) - see [Ash's card](https://github.com/NucleoidMC/nucleoid-contributors/blob/main/data/people/ashhhleyyy.toml) as a template. Members of the GitHub org should automatically get write permissions to the repo, so can update their own.

docs/admin/guides/reboot.md

@@ -0,0 +1,44 @@
+# What to do after a reboot
+
+A short guide on making Nucleoid run again.
+
+## Ensure stuff that is supposed to auto run did actually auto-run
+
+Run `sudo systemctl status` and check that the overall status is not `Degraded`. If it is, run `sudo systemctl`, and find the failed services.
+
+## Start up standalone services
+
+Switch to the `minecraft` user with `sudo su minecraft -s /usr/bin/fish`, and start up the following services under screen (`screen -R <name of service>`) in the following order:
+
+| Service | Path | Launch command |
+| ------- | ---- | -------------- |
+| [mitosis](https://github.com/ashhhleyyy/mitosis) | `/home/minecraft/services/mitosis` | `env RUST_LOG=info ./mitosis` |
+| [face-api](https://github.com/NucleoidMC/player-face-api) | `/home/minecraft/services/face-api` | `./player-face-api` |
+| [backend](https://github.com/NucleoidMC/nucleoid-backend) | `/home/minecraft/services/backend` | `env RUST_LOG=nucleoid_backend=info ./nucleoid-backend` |
+
+Poke Ash and maybe she can turn some of these into systemd services.
+
+## Stats website
+
+As the `minecraft` user, go into `/home/minecraft/services/stats` and run `docker compose start`.
+
+## Minecraft servers
+
+Using the same `screen` commands, as the `minecraft` user, run `./server-wrapper` inside each server directory:
+
+- `/home/minecraft/servers/play`
+- `/home/minecraft/servers/build`
+
+## Velocity
+
+In a `screen` session as the `minecraft` user, `cd` into `/home/minecraft/servers/proxy` and run `java -Xmx256M velocity.jar`.
+
+## BONUS: Modmail
+
+`docker compose start` in `/home/ash/modmail` (please make Ash move it out of her home directory at some point)
+
+## Testing everything is working
+
+First, head to https://nucleoid.xyz and check the contributors section loads correctly and that Minecraft avatars are working.
+
+Then, check on https://stats.nucleoid.xyz/leaderboards that the list has loaded correctly, and that the translations have been loaded.

docs/admin/index.md

@@ -0,0 +1,3 @@
+# About
+
+This section of the docs is for information about running the Nucleoid Minecraft server itself.

docs/admin/infra/index.md

@@ -0,0 +1,3 @@
+# About
+
+This section contains details about running and maintaining Nucleoid's infrastructure.

docs/admin/infra/services/backend.md

@@ -0,0 +1,7 @@
+# Backend
+
+The [backend](https://github.com/NucleoidMC/nucleoid-backend) is run from `/home/minecraft/services/backend/`, using `screen` as the `minecraft` user.
+
+## Updating
+
+Download the latest binary from [GitHub Actions](https://github.com/NucleoidMC/nucleoid-backend/actions) (I use the `gh` cli for this), and put move it to `/home/minecraft/services/backend/nucleoid-backend`. Then connect to the backend `screen` session, ctrl-c and [re-run the backend](../../guides/reboot.md#start-up-standalone-services).

docs/admin/infra/services/minecraft.md

@@ -0,0 +1,15 @@
+# Minecraft
+
+The two Minecraft servers are in `/home/minecraft/servers/{play,build}`. There is also a [Velocity](https://velocitypowered.org) proxy in `/home/minecraft/servers/proxy`.
+
+## Adding/updating mods
+
+Most mods should auto-update from GitHub Actions. Other mods like Fabric API don't and the version has to be updated manually in `destinations.toml` (inside the server directory).
+
+##  Velocity
+
+As we often lag behind the latest releases of Minecraft, our Velocity proxy also has [ViaVersion](https://github.com/ViaVersion/ViaVersion) installed, to allow players on the latest version to join, even if we haven't updated yet.
+
+### Updates
+
+Updating Velocity is as simple as downloading the latest JAR file, and replacing `velocity.jar` in `/home/minecraft/servers/proxy` (make sure to update any plugins too). When restarting Velocity, wait until there are no players online, or ask them to stop after the next game.

docs/admin/infra/services/misc.md

@@ -0,0 +1,23 @@
+# Other services
+
+I have undoubtedly forgotten something, if you notice anything is missing, poke Ash on Discord.
+
+## Grafana
+
+Installed through APT, uses GitHub for logins and pulls data from postgres (which is written to by [backend](backend.md)).
+
+## Databases
+
+Make sure both of these are running before you try to start backend, otherwise it won't work.
+
+### Postgresql
+
+If you have to update this to a new major version, good luck - Google is your friend.
+
+### Clickhouse
+
+Every single update seems to change the default config file, which means apt/dpkg will ask you how to resolve it. When you do, take all the changes from the new config, and re-apply our specific parts (mainly disabling some of the logs as they take up a lot of storage).
+
+## Mitosis and face-api
+
+These are just small standalone serivces, managed in basically the same way as [backend](backend.md).

docs/admin/infra/services/modmail.md

@@ -0,0 +1,7 @@
+# Modmail
+
+We run [a modmail bot](https://github.com/modmail-dev/modmail) for players to contact our moderators on Discord, it is currently running from a docker-compose file in Ash's home directory.
+
+## Updating
+
+To update, run `docker compose pull` to pull the new container image, then `docker compose down` to stop the existing instance, and finally `docker compose up --detatch` to restart it.

docs/admin/infra/services/website.md

@@ -0,0 +1,27 @@
+# Web services
+
+## nucleoid.xyz
+
+The website is served as a static site by apache2 from `/var/www/nucleoid.xyz`. It's built automatically by GitHub Actions, so you just need to `sudo git pull` from that folder to update the site once it has built.
+
+## maven.nucleoid.xyz and build.nucleoid.xyz
+
+These are both also just "static" sites running under `apache2` (well all our web stuff goes through here, but most of them are just proxied).
+
+The maven repository is deployed to using sftp logging in as the `maven` user (ask on Discord for the password if you need to set something up to deploy there).
+
+The build site is just a symlink to the exports directory of the building server.
+
+Both are using [h5ai](https://github.com/lrsjng/h5ai) for a nicer looking static file browser.
+
+## stats.nucleoid.xyz
+
+Running under `docker-compose` from `/home/minecraft/services/stats`.
+
+## api.nucleoid.xyz
+
+Is reverse proxied through to several services:
+
+- [backend](backend.md)
+- [mitosis](misc.md#mitosis-and-face-api)
+- [face-api](misc.md#mitosis-and-face-api)

mkdocs.yml

@@ -40,6 +40,19 @@ nav:
     - build-rush/index.md
     - build-rush/maps.md
     - build-rush/builds.md
+  - Administration:
+    - admin/index.md
+    - Guides:
+      - admin/guides/new-contributor.md
+      - admin/guides/reboot.md
+    - Infra:
+      - admin/infra/index.md
+      - Services:
+        - admin/infra/services/backend.md
+        - admin/infra/services/minecraft.md
+        - admin/infra/services/modmail.md
+        - admin/infra/services/website.md
+        - admin/infra/services/misc.md
 
 extra:
   social: