feat: add config subcommand to generate default config files (minekube#608)

* feat: add config subcommand to generate default config files

- Add 'gate config' subcommand to output default configuration templates
- Support multiple config types: full, minimal, simple, lite, bedrock
- Add --write flag to write directly to config.yml
- Embed config files using go:embed for distribution
- Add sync-configs Makefile target and go:generate directives
- Update documentation with config generation examples and templates

* docs: update quick-start guide for configuration file generation

- Change wording from "default configuration file" to "simple configuration file" for clarity.
- Update command example to reflect the new syntax for generating a simple configuration file with the `-t simple -w` flags.

* docs: update configuration menu item text for clarity

- Changed menu item text from "Complete Configuration" to "Configuration & Templates" to better reflect the content.

Author: robinbraemer

.web/docs/.vitepress/config.ts

@@ -199,7 +199,7 @@ export default defineConfig({
           text: 'Configuration',
           items: [
             {
-              text: '📋 Complete Configuration',
+              text: '📋 Configuration & Templates',
               link: '/guide/config/',
             },
             {

.web/docs/guide/config/index.md

@@ -1,10 +1,61 @@
 ---
-title: "Gate Configuration Guide - Proxy Settings"
-description: "Configure Gate Minecraft proxy with YAML settings, server routes, authentication, and advanced proxy features."
+title: 'Gate Configuration Guide - Proxy Settings'
+description: 'Configure Gate Minecraft proxy with YAML settings, server routes, authentication, and advanced proxy features.'
 ---
 
 # Configuration
 
-```yaml config.yml
+Gate uses a YAML configuration file (`config.yml`) to configure all proxy settings.
+
+## Config File Location
+
+Gate looks for `config.yml` in the current working directory by default. Use `--config` or `-c` to specify a custom path:
+
+```sh console
+$ gate                    # Uses ./config.yml
+$ gate -c /path/to/config.yml
+```
+
+Gate supports YAML (`.yml`, `.yaml`), JSON (`.json`), and environment variables with `GATE_` prefix. You can mix formats - use a config file and override values with environment variables.
+
+## Configuration Templates
+
+Generate configuration files using the `gate config` command, or create them manually:
+
+```sh console
+# Write to config.yml
+$ gate config --write
+$ gate config --type <type> --write
+
+# Write to custom file using pipe redirection
+$ gate config > my-config.yml
+$ gate config --type <type> > my-config.yml
+```
+
+You can also create the `config.yml` file manually using any of the templates below as a starting point.
+
+::: code-group
+
+```yaml [Full (default)]
 <!--@include: ../../../../config.yml -->
 ```
+
+```yaml [Simple]
+<!--@include: ../../../../config-simple.yml -->
+```
+
+```yaml [Lite]
+<!--@include: ../../../../config-lite.yml -->
+```
+
+```yaml [Bedrock]
+<!--@include: ../../../../config-bedrock.yml -->
+```
+
+```yaml [Minimal]
+<!--@include: ../../../../internal/configs/config-minimal.yml -->
+```
+
+:::
+
+For most users, the full configuration is recommended. You can generate it and then edit the `servers` section to point to your backend Minecraft servers.

.web/docs/guide/quick-start.md

@@ -76,7 +76,13 @@ Gate supports:
 
 Gate connects to your Minecraft servers and forwards client connections to them.
 
-You can do this by creating and editing the `config.yml` file.
+You can generate a simple configuration file using:
+
+```sh console
+$ gate config -t simple -w
+```
+
+Then edit the `config.yml` file to configure your backend servers:
 
 ```yaml config.yml
 <!--@include: ../../../config-simple.yml -->

Makefile

@@ -1,7 +1,15 @@
 all: fmt vet mod lint
 
+# Sync embedded config files from root directory
+sync-configs:
+	cp config.yml internal/configs/config.yml
+	cp config-simple.yml internal/configs/config-simple.yml
+	cp config-lite.yml internal/configs/config-lite.yml
+	cp config-bedrock.yml internal/configs/config-bedrock.yml
+	# Note: config-minimal.yml is maintained directly in internal/configs, not synced from root
+
 # Build Gate with version information
-build:
+build: sync-configs
 	@VERSION=$$(git describe --tags --always --dirty 2>/dev/null || echo "dev-$$(git rev-parse --short HEAD 2>/dev/null || echo unknown)") && \
 	echo "Building Gate version: $$VERSION" && \
 	go build -ldflags="-s -w -X 'go.minekube.com/gate/pkg/version.Version=$$VERSION'" -o gate gate.go

cmd/gate/config.go

@@ -0,0 +1,77 @@
+package gate
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/urfave/cli/v2"
+	"go.minekube.com/gate/internal/configs"
+)
+
+func configCommand() *cli.Command {
+	return &cli.Command{
+		Name:  "config",
+		Usage: "Output default configuration file",
+		Description: `Output the default configuration file to stdout or a file.
+You can redirect to a file or use the --write flag:
+
+	gate config > config.yml
+	gate config --write              # Writes to config.yml
+
+Available config types:
+  - full (default): Full configuration with all options
+  - minimal: Empty/minimal configuration (uses all defaults)
+  - simple: Minimal configuration example with servers
+  - lite: Lite mode configuration example
+  - bedrock: Bedrock cross-play configuration example`,
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:    "type",
+				Aliases: []string{"t"},
+				Usage:   "Config type: full, minimal, simple, lite, or bedrock",
+				Value:   "full",
+			},
+			&cli.BoolFlag{
+				Name:    "write",
+				Aliases: []string{"w"},
+				Usage:   "Write config to config.yml instead of stdout",
+			},
+		},
+		Action: func(c *cli.Context) error {
+			configType := c.String("type")
+			var configBytes []byte
+
+			switch configType {
+			case "full":
+				configBytes = configs.DefaultConfigBytes
+			case "minimal":
+				configBytes = configs.MinimalConfigBytes
+			case "simple":
+				configBytes = configs.SimpleConfigBytes
+			case "lite":
+				configBytes = configs.LiteConfigBytes
+			case "bedrock":
+				configBytes = configs.BedrockConfigBytes
+			default:
+				return cli.Exit(fmt.Sprintf("unknown config type: %s (valid types: full, minimal, simple, lite, bedrock)", configType), 1)
+			}
+
+			if c.Bool("write") {
+				outputFile := "config.yml"
+				err := os.WriteFile(outputFile, configBytes, 0644)
+				if err != nil {
+					return cli.Exit(fmt.Errorf("error writing config to %q: %w", outputFile, err), 1)
+				}
+				fmt.Printf("Configuration written to %s\n", outputFile)
+				return nil
+			}
+
+			_, err := os.Stdout.Write(configBytes)
+			if err != nil {
+				return cli.Exit(fmt.Errorf("error writing config: %w", err), 1)
+			}
+
+			return nil
+		},
+	}
+}

cmd/gate/root.go

@@ -49,6 +49,10 @@ func App() *cli.App {
 
 Visit the website https://gate.minekube.com/ for more information.`
 
+	app.Commands = []*cli.Command{
+		configCommand(),
+	}
+
 	var (
 		debug        bool
 		configFile   string

internal/configs/config-bedrock.yml

@@ -0,0 +1,25 @@
+config:
+  bind: 0.0.0.0:25565
+  onlineMode: true
+  servers:
+    server1: 0.0.0.0:25566
+  try:
+    - server1
+  # forwarding:
+  # mode: legacy
+  # velocitySecret: 'bedrock-crossplay-secret'
+  status:
+    motd: |
+      §bGate + Geyser Cross-Play
+      §eJava & Bedrock Players Welcome!
+
+  # Enable Bedrock edition support
+  bedrock:
+    managed: true
+    # Geyser will connect to this address that Gate listens on in parallel to the bind address.
+    # localhost is recommended for same-machine setups (use 0.0.0.0 for Docker Compose)
+    geyserListenAddr: 'localhost:25567'
+    # Username format for Bedrock players to avoid conflicts
+    usernameFormat: '.%s'
+    # Path to Floodgate key for authentication
+    floodgateKeyPath: '.examples/bedrock/geyser/key.pem'

internal/configs/config-lite.yml

@@ -0,0 +1,135 @@
+# This is a simplified config where the rest of the
+# settings are omitted and will be set by default.
+# See config.yml for the full configuration options.
+config:
+  # The bind address to listen for Minecraft client connections.
+  bind: 0.0.0.0:25565
+  # Lite mode is a lightweight reverse proxy mode that acts as thin layer between the client and the backend server.
+  # Full documentation: https://gate.minekube.com/guide/lite
+  #
+  # It efficiently routes client connections based on the virtual host address received in the handshake packet.
+  # This allows to protect multiple backend servers behind a single port Gate Lite proxy instance.
+  # Player connections (including ping requests and player authentication) is forwarded to the destined backend server.
+  # This means Lite mode supports proxy behind proxy setups, but advanced features like server switching or proxy commands are no longer available
+  # and have no effect in Lite mode when extensions use higher level Gate APIs and events.
+  lite:
+    # Enable Lite mode.
+    # If disabled, the proxy will act as a full proxy with all features enabled just like BungeeCord/Velocity.
+    # If enabled, the proxy will act as a lightweight reverse proxy to support new types of deployment architecture.
+    # Default: false
+    enabled: true
+    # The routes that the proxy redirects player connections to based on matching the virtual host address.
+    # The routes are matched in order of appearance.
+    # Examples:
+    routes:
+      # Match the virtual host address to the backend server.
+      - host: localhost
+        # The backend server to connect to if matched.
+        backend: localhost:25566
+        # The optional fallback status response when all backends of this route are offline.
+        fallback:
+          motd: |
+            §cLocalhost server is offline.
+            §eCheck back later!
+          version:
+            name: '§cTry again later!'
+            protocol: -1
+          #players:
+          #  online: 0
+          #  max: 1000
+          # The optional favicon to show in the server list (optimal 64x64).
+          # Accepts a path of an image file or the base64 data uri.
+          favicon: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAAB6JgAAgIQAAPoAAACA6AAAdTAAAOpgAAA6mAAAF3CculE8AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH5AgJCgs6JBZy0AAAB+lJREFUeNrtmGuMXVUZht/LOvcz7diWklbJaKGCWKXFUiiBQjAEhRSLSCEqIKAiogRTmiriBeSiUUhjMCZe2qQxNE0EUZSCidAgYMBSLBJCDC1taAg4xaq1cz/788feZzqgocCoP2Q/f87JOXvvfOtd73dZGygpKSkpKSkpKSkpKSkpKSkpKSkpKXnzwNd7w+ULD0NEBtmQBFqQBNuICFRYwzc3bf7/E+Cyo+cgAIiEbESWJdl1WSQ5VGvWRwnk/0XgpnvfmAhrv3h+HhgFFeJCBCLw8Wt//B8XIB3ogs8umJMHAOCQvtnYtfP5eRGxVNaxMmdKgqzdWSfbIuuuocHBLa2ednx16WJcd9fvXn9EAQSQyGgBwUCMMbAvAvHfcIAOaBHnl0REY9fO56+itFHSjbI/JHuxrMWyl8r6mq27m+3WKpJ1kvjG2UtevyUtyDqK0t2UNklaLalu63+fAp9bNBdZFogsq0j6OsVVkix7L8WNkh6VLVuLlXyapKbsMUkrR4aGV9caNbRnTkWKPC0kgdpv7e7n2GgH7ant8WgiYomoX8uqUXoIwKm1Rn0wJQMAGu0mBv8xhEZPAxIhOX9W8byR4VHUGjUcf86qyaVApVrB6MgYIC4leaUsS/oLySsprQcwBgRkVW1fIfsGWVVJn29Naf8CwPYUedAjQ8OsNxuHApiHwAwAIwB2AtjaaNX/CgQAiuQM27NIhixQqqaU+mTtA9AfEUMA0JzSRERMB3BUIPoCgQjsiIg/NHuaewDg0TtvxqJlK964A6447nAE0CLwM0mnygbFGzujY19WMhD5bjgZTu6hdLekE4qduDAi1jWntIEseimuIHmBrLfJVuGAAdmbZV1t6yGnNI3kBkkLaE2zRNnDsnbLGiR1EcUHK5WKlbyc5BdkvUdSPXeAB21tln3D6PDIvdV6DQBeVYRXdYDyvHsXyYW5dd1PYoNURafTwS2/fRIAsPKU+eg96C17EVhNcavskPgCQCDCtK4RuaLY0WdlPWW7T9a7JS+RdYukpbJHip3PcoHctXUmKyMZkuBK+jTJb8tqSeqn9ICthuyFsk4kubZar50P4DeTSgHZAHAEyd6i7z9LYgcA9M6chuuXnwzLoPLWiIjbKd7ezfV8B+JIkp+gVNzPj0jaKvsQ2xtkLZI1n+TRo8Mj99QatY85+WRJ62TXJW0leb6kfZ2xzp/rzcZ8ktcUi98B4hJZD1KqyLqU5E0AZgH4EoDfA/j7GxbAuc0PpshCgJcoDiHGOxIDMZfgdACh5InFbRuJflA1kffJNsVNtXptS7GzOyJii6RFsqqkZjsZ1XqtX/aLJLPiOcOSnsuybLA1tQ2S51CcXQi/RvZ9TgaBEZA/BHAugEUAjgMwH8ADkxAgARGaULlJERGAJESWWdK1kpZJHJMUyncaFD+TZdltTumxl17oP3f2nEN6Jc0DeSmIWQAato/tVm5KjbzwVos5iONiklSlVoHtOsljKMFWJvswWSsmtHMCqBffWwCOnJwANgKxp7soWdNJNYAYcTKyTLBlSklWWK7ISnnQqgDAvMXz4pmt2z4gcRWlYwrrTsxvOC+uRBSuA0AS+8UhUqUC2XWK04tYJOmCA6R476RqgJMRgW0SB2Q1Zb+dZB+JJyQByDqUrpP0fVGZk1fSOsO5AJCNbX/cfoKsNZJmSRqguE7SJol7bH9K1umyUaz/XwSgVIzfgpMySmOSQHIUwG1FK504JXVQ9NQD7f5rLILxlKRtebvxQbLOlvWELIyOjIbkJ11JqNaqMxAxOz8cGRLzRUgflTSrsPIaklcC6NgJqZJOG0+viQIExgsrRZAqnuUBWbuKHBeAXwL46cSeHnnezwCQAXh6UqNwqiTUW80XndJ6O3X7/WVO6RxSmjKtF+3eNqq16hSSVyt5vu3udXjh2V1w8ludjPz3tKNSq3ZaU3tQrVdnyn6fnf+n4h6Nf0/dexq2VKlVIWsMwKauQQGcPSHnEcA7AawHcA+ANQAOnpQDsixDZBlk/Uj2SbZOk3WQ5B/IOhOIxyNQp3iKpJOK9naErDpJ9B15GGxvL4oWZF+i5L0A/kZruaT3jhc6KSGimwIDpMaK8fZwSStJPgLgfgB3ALgAwEIAZwEYALARQA+ACwEcUYR/RwB/4mTOAgBw43nvR6okSJoj61uyz7RV3T/Pu7uAp2ytln2LrDapiyWudUoLZK2XfbgnnAEo7bb9sKwzC6tfjyy+Um81EMAMST+XdXxeawAAzwM4EcB2AMcDuBXAgn8T8kjhgpUA+ic1CeaFMN89kNudfBGlU2V9UPZcWQ1JeyU9RvInTmk3xdmSWpSeQAC2Hpd9nqxPyjpKsmTtJLlByS+KfFqSKW4OZHAlgcBuAJdTugTAoUWcOwDsLcJ6GMAyAMsLUWYCGAWwragLGwtnYNIOAICbLz4DKe0/0R13+hI8fv+jDVlJ0miWZUOykZLHT3sUQRAUUa3X8OGrvotf3bqyRYlOaSCyLJvoIjIPpd5uoG/uO/DcMzu743i1iHOsk3U6BMffPnXPbEUdyCJigOTL3htM6jD0Sr53+VmQ07gQ432aQiBQq9cAomhdQgBo9bQg7x+eim6AyDJUm00gAikRlLCvswc9noZqT6uozvGyELvvRI5ddhUeufM7ebcgX/k+BXwNCy8pKSkpKSkpKSkpKSkpKSkpKSkpKXkz8k8RHxEbZN/8lgAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAyMC0wOC0wOVQxMDoxMTo0MyswMDowMN6nNEYAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMjAtMDgtMDlUMTA6MTE6NDMrMDA6MDCv+oz6AAAAAElFTkSuQmCC
+      # You can also use * wildcard to match any subdomain.
+      - host: '*.example.com'
+        backend: 172.16.0.12:25566
+        proxyProtocol: true # Use proxy protocol to connect to backend.
+        tcpShieldRealIP: true # Optionally you can also use TCPShield's RealIP protocol.
+      # Use hostname parameters in backend addresses with $1, $2, etc.
+      # Example: abc.domain.com → abc.servers.svc:25565
+      - host: '*.domain.com'
+        backend: '$1.servers.svc:25565'
+      # You can also match to multiple hosts to one or multiple backends.
+      - host: [127.0.0.1, localhost]
+        backend: [172.16.0.12:25566, backend.example.com:25566]
+        # Load balancing strategy when multiple backends are available.
+        # See https://gate.minekube.com/guide/lite#load-balancing-strategies for detailed guide.
+        # Options: sequential, random, round-robin, least-connections, lowest-latency
+        # Default: sequential (tries backends in config order)
+        # strategy: random  # Uncomment to use random instead of sequential
+        # Ping responses are cached per backend address by default.
+        # To disable motd caching set it to -1.
+        # Default: 10s
+        cachePingTTL: 60s
+        # Modifies the virtual host to match the backend address in the handshake request.
+        # This is useful when backends require players to connect with a specific domain.
+        # Lite will modify the player's handshake packet's virtual host field from `localhost` -> `backend.example.com`
+        # before forwarding the connection to the backend.
+        # Default: false
+        modifyVirtualHost: true
+      # Match all as last item routes any other host to a default backend.
+      - host: '*'
+        backend: 10.0.0.10:25565
+        fallback:
+          motd: §eNo server available for this host.
+          version:
+            name: §eTry example.com
+            protocol: -1
+          #players:
+          #  online: 0
+          #  max: 1000
+          #favicon: server-icon.png
+
+  # The follow settings from standard Gate also apply to Lite mode.
+  #
+  # The time Gate waits to connect to a server before timing out.
+  connectionTimeout: 5s
+  # The time Gate waits to receive data from a server before timing out.
+  # If you use Forge, you may need to increase this setting.
+  readTimeout: 30s
+  # Enabled extra debug logging (only for debugging purposes).
+  debug: false
+  # Proxy protocol (HA-Proxy) determines whether Gate should support proxy protocol for players.
+  # Do not enable this if you don't know what it is.
+  proxyProtocol: false
+  # The quota settings allows rate-limiting IP (last block cut off) for certain operations.
+  # ops: The allowed operations per second.
+  # burst: The maximum operations per second (queue like). One burst unit per seconds is refilled.
+  # maxEntries: The maximum IPs to keep track of in cache for rate-limiting (if full, deletes oldest).
+  quota:
+    # Limit how many new connections can be established by the same IP range.
+    connections:
+      enabled: true
+      ops: 5
+      burst: 10
+      maxEntries: 1000
+
+# Configuration for Connect, a network that organizes all Minecraft servers/proxies
+# and makes them universally accessible for all players.
+# Among a lot of other features it even allows players to join locally hosted
+# Minecraft servers without having an open port or public IP address.
+#
+# Visit https://connect.minekube.com/
+connect:
+  # Enabling Connect makes Gate register itself to Connect network.
+  # This feature is disabled by default, but you are encouraged to
+  # enable it and get empowered by the additional network services
+  # and by the growing community in this ecosystem.
+  enabled: false
+  # The endpoint name is a globally unique identifier of your server.
+  # If Connect is enabled, but no name is specified a random name is
+  # generated on every restart (only recommended for testing).
+  #
+  # It is supported to run multiple Gates on the same endpoint name for load balancing
+  # (use the same connect.json token file from first Gate instance).
+  #name: your-endpoint-name
+
+# Gate HTTP API configuration.
+# See https://gate.minekube.com/guide/api for more information.
+api:
+  # Whether to enable the API for Gate.
+  # Default: false
+  enabled: false
+  # The bind address to listen for API connections.
+  # Default: localhost:8080
+  bind: localhost:8080

internal/configs/config-minimal.yml

@@ -0,0 +1,3 @@
+# Minimal Gate configuration
+# All other settings will use their default values
+config: {}

internal/configs/config-simple.yml

@@ -0,0 +1,11 @@
+# This is a simplified config where the rest of the
+# settings are omitted and will be set by default.
+# See config.yml for the full configuration options.
+config:
+  bind: 0.0.0.0:25565
+  servers:
+    server1: localhost:25566
+    server2: localhost:25567
+  try:
+    - server1
+    - server2