From 2a16bd94adfb98e3733c1201232b8add3d83cfe1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20St=C3=A4ding?= Date: Sun, 31 Mar 2024 00:39:42 +0100 Subject: [PATCH 1/4] Start docs --- .editorconfig | 2 +- docs/getting-started/docker-compose.md | 206 +++++++++++++++++++++++++ docs/getting-started/kubernetes.md | 0 docs/getting-started/legacy.md | 0 docs/index.md | 17 ++ docs/overview/what-is-catalyst.md | 9 ++ docs/reference/commands.md | 0 mkdocs.yml | 73 +++++++++ 8 files changed, 306 insertions(+), 1 deletion(-) create mode 100644 docs/getting-started/docker-compose.md create mode 100644 docs/getting-started/kubernetes.md create mode 100644 docs/getting-started/legacy.md create mode 100644 docs/index.md create mode 100644 docs/overview/what-is-catalyst.md create mode 100644 docs/reference/commands.md create mode 100644 mkdocs.yml diff --git a/.editorconfig b/.editorconfig index f37d48bd..f25377a3 100644 --- a/.editorconfig +++ b/.editorconfig @@ -11,5 +11,5 @@ trim_trailing_whitespace = true ij_kotlin_allow_trailing_comma_on_call_site = true ij_kotlin_allow_trailing_comma = true -[*.{json,yml,yaml,xml}] +[*.{json,yml,yaml,xml,md}] indent_size = 2 diff --git a/docs/getting-started/docker-compose.md b/docs/getting-started/docker-compose.md new file mode 100644 index 00000000..ae3c8a7f --- /dev/null +++ b/docs/getting-started/docker-compose.md @@ -0,0 +1,206 @@ +[Docker Compose](https://docs.docker.com/compose/) is a tool for defining and running multi-container applications. +In the context of Minecraft, it simplifies the setup for a multi-server network. + +Using Docker Compose, it is possible to declaratively configure a full server network. +The configuration is a yaml file named `docker-compose.yaml` that can be used with the `docker-compose` command. +Place the configuration file in a directory and open this directory in a terminal. +Then, use the command `docker-compose up` to start the servers. + +```shell +cd path/to/dir # Open working directory +nano docker-compose.yaml # Edit docker compose configuration +docker-compose up # Start servers +# ctrl-c to stop servers +``` + +Alternatively: + +```shell +docker-compose up -d # Start servers in "detached mode" without attached log output +docker-compose down # Stop servers +``` + +For a full working example with Catalyst already set up, +you can check out the [Catalyst Example](https://github.com/anvilpowered/catalyst/tree/master/examples). +By downloading the repository, building Catalyst and running `docker-compose up` in the `examples/docker-compose` directory, +you can start the servers. +Remember to restart the servers once before joining. See +the [README](https://github.com/anvilpowered/catalyst/tree/master/examples/docker-compose) for more information. + +## Basic Compose Structure + +Essentially, the Compose configuration file has approximately the following structure, +which tells Docker which servers to start and how to configure them. + + + +!!! note + This is not a full working example; + there is some additional configuration required to configure the paper servers to accept + connections from the velocity proxy + + +```yaml +services: + # Velocity Proxy + proxy: + image: itzg/bungeecord:java21 + ports: # Expose ports to the host system + - "25565:25565" + environment: + TYPE: VELOCITY + + # Paper 0 + paper-0: + image: itzg/minecraft-server:java21 + expose: # Only expose ports within docker network and not externally + - 25565 + environment: + TYPE: PAPER + VERSION: "1.20.4" + EULA: true # By using this environment variable, you are indicating your acceptance of the Minecraft EULA + ONLINE_MODE: false + + # Paper 1 + paper-1: + image: itzg/minecraft-server:java21 + expose: # Only expose ports within docker network and not externally + - 25565 + environment: + TYPE: PAPER + VERSION: "1.20.4" + EULA: true # By using this environment variable, you are indicating your acceptance of the Minecraft EULA + ONLINE_MODE: false +``` + +In this example, there are three services defined: one Velocity proxy and two Paper backend servers +using [itzg's](https://hub.docker.com/r/itzg/minecraft-server/) minecraft images. + +
+ +```mermaid +stateDiagram-v2 + paper0: Paper 0 + paper1: Paper 1 + pc: Player Connections + + pc --> Velocity + Velocity --> paper0 + Velocity --> paper1 +``` + +
+ +These images have *extensive* customization support and their own [docs](https://docker-minecraft-server.readthedocs.io/en/latest/) along +with a discord server for any questions related to the images themselves. +This page will only cover the details relevant for a Catalyst deployment. + +## Adding config patches + +To complete the basic setup, it is necessary to configure paper to accept connections from velocity. +Instead of manually editing `paper-global.yml`, we will use the +[patching system](https://docker-minecraft-server.readthedocs.io/en/latest/configuration/interpolating/#patching-existing-files) +to modify only the options that need to be modified. +This way, we can easily apply the settings to multiple servers +and have a good overview of which options have been changed from their default value. + +A patch set is a set of declarative definitions that modify specific parts of a target file. +The following patch set targets the file `/data/config/paper-global.yml`. + +!!!note +Read more about the patch files [here](https://github.com/itzg/mc-image-helper?tab=readme-ov-file#patch-schemas) + +```yaml +{ + "patches": [ + { + "file": "/data/config/paper-global.yml", + "ops": [ + { + "$set": { + "path": "$.proxies.velocity.enabled", + "value": "true", + "value-type": "bool" + } + }, + { + "$set": { + "path": "$.proxies.velocity.online-mode", + "value": "true", + "value-type": "bool" + } + }, + { + "$set": { + "path": "$.proxies.velocity.secret", + "value": "donotusethisforproduction" + } + } + ] + } + ] +} +``` + +To use this patch definition, place it in a directory accessible from your `docker-compose.yaml`. +See [catalyst/examples](https://github.com/anvilpowered/catalyst/tree/master/examples) for + +## Full Example + +Here is an example of a simple two backend-server configuration with a velocity proxy in front +using + +```yaml +version: "3.8" + +services: + proxy: + image: itzg/bungeecord:java21 + ports: + - "25565:25565" + environment: + TYPE: VELOCITY + VELOCITY_VERSION: 3.3.0-SNAPSHOT + VELOCITY_BUILD_ID: 363 + PLUGINS: | + https://download.luckperms.net/1532/velocity/LuckPerms-Velocity-5.4.119.jar + https://cdn.modrinth.com/data/7IbzD4Zm/versions/eeGwpMZV/SignedVelocity-Proxy-1.2.3.jar + volumes: + - ../config/velocity.toml:/server/velocity.toml + - ../config/forwarding.secret:/server/forwarding.secret + - ../config/velocity-patch-set.json:/server/velocity-patch-set.json + - ./proxy/plugins:/server/plugins + + paper-0: + image: itzg/minecraft-server:java21 + expose: + - 25565 + environment: + TYPE: PAPER + VERSION: "1.20.4" + EULA: true # By using this environment variable, you are indicating your acceptance of the Minecraft EULA + ONLINE_MODE: false + PATCH_DEFINITIONS: /config/paper-patch-set.json + PLUGINS: | + https://cdn.modrinth.com/data/7IbzD4Zm/versions/ngDdLdWA/SignedVelocity-Paper-1.2.3.jar + volumes: + - ./paper-0:/data + - ../config/paper-patch-set.json:/config/paper-patch-set.json:ro + + paper-1: + image: itzg/minecraft-server:2024.2.2-java21 + expose: + - 25565 + environment: + TYPE: PAPER + VERSION: "1.20.4" + EULA: true # By using this environment variable, you are indicating your acceptance of the Minecraft EULA + ONLINE_MODE: false + PATCH_DEFINITIONS: /config/paper-patch-set.json + PLUGINS: | + https://cdn.modrinth.com/data/7IbzD4Zm/versions/ngDdLdWA/SignedVelocity-Paper-1.2.3.jar + volumes: + - ./paper-1:/data + - ../config/paper-patch-set.json:/config/paper-patch-set.json:ro + +``` diff --git a/docs/getting-started/kubernetes.md b/docs/getting-started/kubernetes.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/getting-started/legacy.md b/docs/getting-started/legacy.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..000ea345 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,17 @@ +# Welcome to MkDocs + +For full documentation visit [mkdocs.org](https://www.mkdocs.org). + +## Commands + +* `mkdocs new [dir-name]` - Create a new project. +* `mkdocs serve` - Start the live-reloading docs server. +* `mkdocs build` - Build the documentation site. +* `mkdocs -h` - Print help message and exit. + +## Project layout + + mkdocs.yml # The configuration file. + docs/ + index.md # The documentation homepage. + ... # Other markdown pages, images and other files. diff --git a/docs/overview/what-is-catalyst.md b/docs/overview/what-is-catalyst.md new file mode 100644 index 00000000..308f6524 --- /dev/null +++ b/docs/overview/what-is-catalyst.md @@ -0,0 +1,9 @@ +Catalyst is a [Velocity](https://papermc.io/software/velocity) plugin targeted at medium to large sized networks. It main focus areas are: + +- Name and message formatting +- Dynamic placeholder resolution +- Chat channels +- Discord chat synchronization + - Account synchronization (planned) +- Private messaging +- Tab list configuration diff --git a/docs/reference/commands.md b/docs/reference/commands.md new file mode 100644 index 00000000..e69de29b diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..254170d6 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,73 @@ +# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json + +site_name: Catalyst +repo_name: anvilpowered/catalyst +repo_url: https://github.com/anvilpowered/catalyst +theme: + name: material + palette: + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: teal + accent: cyan + toggle: + icon: material/lightbulb + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: teal + accent: indigo + toggle: + icon: material/lightbulb-outline + name: Switch to light mode + features: + - navigation.instant + - navigation.sections + - content.code.copy + - content.code.select + +nav: + - Overview: + - What is Catalyst?: overview/what-is-catalyst.md + - Getting Started: + - Docker Compose Setup: getting-started/docker-compose.md + - Kubernetes Setup: getting-started/kubernetes.md + - Legacy Setup: getting-started/legacy.md + +#nav: +# - Vorbereitung: +# - "Terminal Verwendung": "preparation/terminal.md" +# - Paket Manager: preparation/packagemanager.md +# - Installieren von Java: preparation/installation-java.md +# - Installieren von IntelliJ: preparation/installation-intellij.md +# - Installieren von DrRacket: preparation/installation-racket.md +# - Installieren von Git: preparation/installation-git.md +# - Hinzufügen der Matrikelnummer: preparation/matriculation-number.md +# - Hausübungen: +# - Herunterladen und importieren: exercises/download-import.md +# - Bearbeiten von Hausübungen: exercises/edit.md +# - Beheben von häufigen Fehlern: exercises/fix-errors.md +# - Exportieren und Hochladen: exercises/export-upload.md +# - Nicht Unterstützte IDEs: exercises/download-import-unsupported.md +# - Dokumentation von Java-Quellcode: exercises/documentation.md +# - Beanstandungen: exercises/complaints.md +# - Sprechstunden: +# - Bevor Sie eine Sprechstunde besuchen ...: support/good-bad-questions.md + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.tabbed: + alternate_style: true + - admonition + - pymdownx.details From d2a6bfc085fc3b592130577fc3422832e912715c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20St=C3=A4ding?= Date: Fri, 5 Apr 2024 11:09:28 +0200 Subject: [PATCH 2/4] Work on index and add some feature pages --- docs/features/channels.md | 0 docs/features/formatting.md | 0 docs/features/placeholders.md | 0 docs/index.md | 33 ++++++++++++++++++++----------- docs/overview/what-is-catalyst.md | 9 --------- mkdocs.yml | 6 ++++-- 6 files changed, 25 insertions(+), 23 deletions(-) create mode 100644 docs/features/channels.md create mode 100644 docs/features/formatting.md create mode 100644 docs/features/placeholders.md delete mode 100644 docs/overview/what-is-catalyst.md diff --git a/docs/features/channels.md b/docs/features/channels.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/features/formatting.md b/docs/features/formatting.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/features/placeholders.md b/docs/features/placeholders.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/index.md b/docs/index.md index 000ea345..0058ceb8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,17 +1,26 @@ -# Welcome to MkDocs +# Welcome to Catalyst -For full documentation visit [mkdocs.org](https://www.mkdocs.org). +This velocity plugin is the strong baseline your server network needs to handle the core aspects of a distributed minecraft deployment. -## Commands +[Catalysis](https://en.wikipedia.org/wiki/Catalysis) describes an increased rate of chemical reaction, +and so too, will your network deployment be catapulted into success. -* `mkdocs new [dir-name]` - Create a new project. -* `mkdocs serve` - Start the live-reloading docs server. -* `mkdocs build` - Build the documentation site. -* `mkdocs -h` - Print help message and exit. +## Contact -## Project layout +You can find us on: - mkdocs.yml # The configuration file. - docs/ - index.md # The documentation homepage. - ... # Other markdown pages, images and other files. +- [Discord](https://discord.gg/6gR2YH3) +- [GitHub](https://github.com/anvilpowered) +- [TeamCity](https://ci.anvilpowered.org) + +## Features + +The main focus areas are: + +- [Name and message formatting](features/formatting) +- [Dynamic placeholder resolution](features/placeholders) +- [Chat channels](features/channels) +- Discord chat synchronization + - Account synchronization (planned) +- Private messaging +- Tab list configuration diff --git a/docs/overview/what-is-catalyst.md b/docs/overview/what-is-catalyst.md deleted file mode 100644 index 308f6524..00000000 --- a/docs/overview/what-is-catalyst.md +++ /dev/null @@ -1,9 +0,0 @@ -Catalyst is a [Velocity](https://papermc.io/software/velocity) plugin targeted at medium to large sized networks. It main focus areas are: - -- Name and message formatting -- Dynamic placeholder resolution -- Chat channels -- Discord chat synchronization - - Account synchronization (planned) -- Private messaging -- Tab list configuration diff --git a/mkdocs.yml b/mkdocs.yml index 254170d6..9d57e899 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -30,12 +30,14 @@ theme: - content.code.select nav: - - Overview: - - What is Catalyst?: overview/what-is-catalyst.md + - Welcome to Catalyst: index.md - Getting Started: - Docker Compose Setup: getting-started/docker-compose.md - Kubernetes Setup: getting-started/kubernetes.md - Legacy Setup: getting-started/legacy.md + - Features: + - Formatting: features/formatting.md + - Placeholders: features/placeholders.md #nav: # - Vorbereitung: From cf9c4dcb9e76e342de5605325b3b1d99c9161cc1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20St=C3=A4ding?= Date: Fri, 7 Jun 2024 14:38:23 +0200 Subject: [PATCH 3/4] Work on index page --- docs/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/index.md b/docs/index.md index 0058ceb8..6273b90f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,6 +5,16 @@ This velocity plugin is the strong baseline your server network needs to handle [Catalysis](https://en.wikipedia.org/wiki/Catalysis) describes an increased rate of chemical reaction, and so too, will your network deployment be catapulted into success. +## Getting Started & Installation + +Catalyst supports a wide range of deployments, each of which is thoroughly explained in the respective getting started section: + +- [Docker Compose](getting-started/docker-compose) +- [Kubernetes](getting-started/kubernetes) +- [Legacy](getting-started/legacy) + +If you are unsure about the first two terms, you are probably looking for the [Legacy](getting-started/legacy) instructions. + ## Contact You can find us on: @@ -24,3 +34,4 @@ The main focus areas are: - Account synchronization (planned) - Private messaging - Tab list configuration +- Universal Teleportation (planned) From 95b41f47d13a4fb66a0f4975c369f2d30415513e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20St=C3=A4ding?= Date: Fri, 7 Jun 2024 14:44:51 +0200 Subject: [PATCH 4/4] Update docker compose example --- docs/getting-started/docker-compose.md | 30 ++++++++++++-------------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/docs/getting-started/docker-compose.md b/docs/getting-started/docker-compose.md index ae3c8a7f..91f45282 100644 --- a/docs/getting-started/docker-compose.md +++ b/docs/getting-started/docker-compose.md @@ -21,7 +21,7 @@ docker-compose down # Stop servers ``` For a full working example with Catalyst already set up, -you can check out the [Catalyst Example](https://github.com/anvilpowered/catalyst/tree/master/examples). +you can check out the [Catalyst Example](https://github.com/anvilpowered/catalyst/tree/master/example). By downloading the repository, building Catalyst and running `docker-compose up` in the `examples/docker-compose` directory, you can start the servers. Remember to restart the servers once before joining. See @@ -44,7 +44,7 @@ which tells Docker which servers to start and how to configure them. services: # Velocity Proxy proxy: - image: itzg/bungeecord:java21 + image: itzg/bungeecord:latest ports: # Expose ports to the host system - "25565:25565" environment: @@ -52,23 +52,23 @@ services: # Paper 0 paper-0: - image: itzg/minecraft-server:java21 + image: itzg/minecraft-server:latest expose: # Only expose ports within docker network and not externally - 25565 environment: TYPE: PAPER - VERSION: "1.20.4" + VERSION: "1.20.6" EULA: true # By using this environment variable, you are indicating your acceptance of the Minecraft EULA ONLINE_MODE: false # Paper 1 paper-1: - image: itzg/minecraft-server:java21 + image: itzg/minecraft-server:latest expose: # Only expose ports within docker network and not externally - 25565 environment: TYPE: PAPER - VERSION: "1.20.4" + VERSION: "1.20.6" EULA: true # By using this environment variable, you are indicating your acceptance of the Minecraft EULA ONLINE_MODE: false ``` @@ -92,7 +92,7 @@ stateDiagram-v2 These images have *extensive* customization support and their own [docs](https://docker-minecraft-server.readthedocs.io/en/latest/) along -with a discord server for any questions related to the images themselves. +with a [discord server](https://discord.gg/DXfKpjB) for any questions related to the images themselves. This page will only cover the details relevant for a Catalyst deployment. ## Adding config patches @@ -151,19 +151,17 @@ Here is an example of a simple two backend-server configuration with a velocity using ```yaml -version: "3.8" - services: proxy: - image: itzg/bungeecord:java21 + image: itzg/bungeecord:latest ports: - "25565:25565" environment: TYPE: VELOCITY VELOCITY_VERSION: 3.3.0-SNAPSHOT - VELOCITY_BUILD_ID: 363 + VELOCITY_BUILD_ID: 390 PLUGINS: | - https://download.luckperms.net/1532/velocity/LuckPerms-Velocity-5.4.119.jar + https://download.luckperms.net/1543/velocity/LuckPerms-Velocity-5.4.130.jar https://cdn.modrinth.com/data/7IbzD4Zm/versions/eeGwpMZV/SignedVelocity-Proxy-1.2.3.jar volumes: - ../config/velocity.toml:/server/velocity.toml @@ -172,12 +170,12 @@ services: - ./proxy/plugins:/server/plugins paper-0: - image: itzg/minecraft-server:java21 + image: itzg/minecraft-server:latest expose: - 25565 environment: TYPE: PAPER - VERSION: "1.20.4" + VERSION: "1.20.6" EULA: true # By using this environment variable, you are indicating your acceptance of the Minecraft EULA ONLINE_MODE: false PATCH_DEFINITIONS: /config/paper-patch-set.json @@ -188,12 +186,12 @@ services: - ../config/paper-patch-set.json:/config/paper-patch-set.json:ro paper-1: - image: itzg/minecraft-server:2024.2.2-java21 + image: itzg/minecraft-server:latest expose: - 25565 environment: TYPE: PAPER - VERSION: "1.20.4" + VERSION: "1.20.6" EULA: true # By using this environment variable, you are indicating your acceptance of the Minecraft EULA ONLINE_MODE: false PATCH_DEFINITIONS: /config/paper-patch-set.json