{"id":13645538,"url":"https://github.com/criticalstack/quake-kube","last_synced_at":"2025-04-21T14:31:30.581Z","repository":{"id":56156947,"uuid":"284508326","full_name":"criticalstack/quake-kube","owner":"criticalstack","description":"Quake 3 on Kubernetes","archived":true,"fork":false,"pushed_at":"2021-11-17T19:22:31.000Z","size":7286,"stargazers_count":332,"open_issues_count":4,"forks_count":54,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-02-26T01:51:21.614Z","etag":null,"topics":["kubernetes","quake","quake3"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/criticalstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-08-02T17:23:15.000Z","updated_at":"2024-12-27T19:14:04.000Z","dependencies_parsed_at":"2022-08-15T13:50:15.619Z","dependency_job_id":null,"html_url":"https://github.com/criticalstack/quake-kube","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/criticalstack%2Fquake-kube","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/criticalstack%2Fquake-kube/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/criticalstack%2Fquake-kube/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/criticalstack%2Fquake-kube/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/criticalstack","download_url":"https://codeload.github.com/criticalstack/quake-kube/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250070173,"owners_count":21369839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kubernetes","quake","quake3"],"created_at":"2024-08-02T01:02:36.818Z","updated_at":"2025-04-21T14:31:29.415Z","avatar_url":"https://github.com/criticalstack.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Due to changes in the priorities, this project is currently not being supported. The project is archived as of 11/17/21 and will be available in a read-only state. Please note, since archival, the project is not maintained or reviewed. #\n\n![Build Status](https://github.com/criticalstack/quake-kube/workflows/Push%20Image/badge.svg)\n\n# QuakeKube\n\nQuakeKube is a Kubernetes-ified version of [QuakeJS](https://github.com/inolen/quakejs) that runs a dedicated [Quake 3](https://en.wikipedia.org/wiki/Quake_III_Arena) server in a Kubernetes Deployment, and then allow clients to connect via QuakeJS in the browser.\n\n## Quick start\n\n### With an existing K8s cluster\n\nDeploy the example manifest:\n\n```shell\n$ kubectl apply -f https://raw.githubusercontent.com/criticalstack/quake-kube/master/example.yaml\n```\n\n\n### Without an existing K8s cluster\n\nStart an instance of Kubernetes locally using [cinder](https://docs.crit.sh/cinder-guide/what-is-cinder.html) (or [kind](https://kind.sigs.k8s.io/)):\n\n```shell\n$ cinder create cluster\n```\n\nDeploy the example manifest:\n\n```shell\n$ kubectl apply -f example.yaml\n```\n\nFinally, navigate to `http://$(cinder get ip):30001` in the browser.\n\n## How it works\n\nQuakeKube makes use of [ioquake](https://www.ioquake.org) for the Quake 3 dedicated server, and [QuakeJS](https://github.com/inolen/quakejs), a port of ioquake to javascript using [Emscripten](http://github.com/kripken/emscripten), to provide an in-browser game client.\n\n### Networking\n\nThe client/server protocol of Quake 3 uses UDP to synchronize game state. Browsers do not natively support sending UDP packets so QuakeJS wraps the client and dedicated server net code in websockets, allowing the browser-based clients to send messages and enable multiplayer for other clients. This ends up preventing the browser client from using any other Quake 3 dedicated server. In order to use other Quake 3 dedicated servers, a proxy handles websocket traffic coming from browser clients and translates that into UDP to the backend. This gives the flexibility of being able to talk to other existing Quake 3 servers, but also allows using ioquake (instead of the javascript translation of it), which uses *considerably* less CPU and memory.\n\nQuakeKube also uses a cool trick with [cmux](https://github.com/cockroachdb/cmux) to multiplex the client and websocket traffic into the same connection. Having all the traffic go through the same address makes routing a client to its backend much easier (since it can just use its `document.location.host`).\n\n### Quake 3 demo EULA\n\nThe Quake 3 dedicated server requires an End-User License Agreement be agreed to by the user before distributing the Quake 3 demo files that are used (maps, textures, etc). To ensure that the installer is aware of, and agrees to, this EULA, the flag `--agree-eula` must be passed to `q3 server` at runtime. This flag is not set by default in the container image and is therefore required for the dedicated server to pass the prompt for EULA. The [example.yaml](example.yaml) manifest demonstrates usage of this flag to agree to the EULA.\n\n## Configuration\n\nThe server and maps are configured via ConfigMap that is mounted to the container:\n\n```yaml\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: quake3-server-config\ndata:\n  config.yaml: |\n    fragLimit: 25\n    timeLimit: 15m\n    game:\n      motd: \"Welcome to Critical Stack\"\n      type: FreeForAll\n      forceRespawn: false\n      inactivity: 10m\n      quadFactor: 3\n      weaponRespawn: 3\n    server:\n      hostname: \"quakekube\"\n      maxClients: 12\n      password: \"changeme\"\n    maps:\n    - name: q3dm7\n      type: FreeForAll\n    - name: q3dm17\n      type: FreeForAll\n    - name: q3wctf1\n      type: CaptureTheFlag\n      captureLimit: 8\n    - name: q3tourney2\n      type: Tournament\n    - name: q3wctf3\n      type: CaptureTheFlag\n      captureLimit: 8\n    - name: ztn3tourney1\n      type: Tournament\n```\n\nThe time limit and frag limit can be specified with each map (it will change it for subsequent maps in the list):\n\n```yaml\n- name: q3dm17\n  type: FreeForAll\n  fragLimit: 30\n  timeLimit: 30\n```\n\nCapture limit for CTF maps can also be configured:\n\n```yaml\n- name: q3wctf3\n  type: CaptureTheFlag\n  captureLimit: 8\n```\n\nAny commands not captured by the config yaml can be specified in the `commands` section:\n\n```yaml\ncommands:\n- seta g_inactivity 600\n- seta sv_timeout 120\n```\n\n### Add bots\n\nBots can be added individually to map rotations using the `commands` section of the config:\n\n```yaml\ncommands:\n  - addbot crash 1\n  - addbot sarge 2\n```\n\nThe `addbot` server command requires the name of the bot and skill level (crash and sarge are a couple of the built-in bots).\n\nAnother way to add bots is by setting a minimum number of players to allow the server to add bots up to a certain value (removed when human players join):\n\n```yaml\nbot:\n  minPlayers: 8\ngame:\n  singlePlayerSkill: 2\n```\n\n`singlePlayerSkill` can be used to set the skill level of the automatically added bots (2 is the default skill level).\n\n### Setting a password\n\nA password should be set for the server to allow remote administration and is found in the server configuration settings:\n\n```yaml\nserver:\n  password: \"changeme\"\n```\n\nThis will allow clients to use `\\rcon changeme \u003ccmd\u003e` to remotely administrate the server. To create a password that must be provided by clients to connect:\n\n```yaml\ngame:\n  password: \"letmein\"\n```\n\nThis will add an additional dialog to the in-browser client to accept the password. It will only appear if the server indicates it needs a password.\n\n### Add custom maps\n\nThe content server hosts a small upload app to allow uploading `pk3` or `zip` files containing maps. The content server in the [example.yaml](example.yaml) shares a volume with the game server, effectively \"side-loading\" the map content, however, in the future the game server will introspect into the maps and make sure that it can fulfill the users map configuration before starting.\n\n### Development\n\nThe easiest way to develop quake-kube is building the binary locally with `make` and running it directly. This only requires that you have the `ioq3ded` binary in your path:\n\n```shell\n$ bin/q3 server -c config.yaml --assets-dir $HOME/.q3a --agree-eula\n```\n\n### Multi-platform images\n\nContainer images are being cross-compiled with [Docker Buildx](https://docs.docker.com/buildx/working-with-buildx/) so it can run on hardware with different architectures and operating systems. Currently, it is building for `linux/amd64` and `linux/arm64`. While not specifically compiling to the macOS platform (`darwin/amd64`) QuakeKube should also work on macOS and maybe even Windows. This is due to the fact that they both use a linux VM to provide container support.\n\nDocker Buildx uses [QEMU](https://www.qemu.org/) to virtualize non-native platforms, which has unfortunately had long-running issues running the Go compiler:\n\n* [golang/go#24656](https://github.com/golang/go/issues/24656)\n* [https://bugs.launchpad.net/qemu/+bug/1696773](https://bugs.launchpad.net/qemu/+bug/1696773)\n\nThis issue is circumvented by ensuring that the Go compiler does not run across multiple hardware threads, which is why the affinity is being limited in the Dockerfile.\n\n## Credits\n\n* [inolen/quakejs](https://github.com/inolen/quakejs) - The really awesome QuakeJS project that makes this possible.\n* [ioquake/ioq3](https://github.com/ioquake/ioq3) - The community supported version of Quake 3 used by QuakeJS. It is licensed under the GPLv2.\n* [begleysm/quakejs](https://github.com/begleysm/quakejs) - Information in the README.md (very helpful) was used as a guide, as well as, some forked assets of this project (which came from quakejs-web originally) were used.\n* [joz3d.net](http://www.joz3d.net/html/q3console.html) - Useful information about configuration values.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcriticalstack%2Fquake-kube","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcriticalstack%2Fquake-kube","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcriticalstack%2Fquake-kube/lists"}