https://github.com/neonwatty/kamal-quake
A simple recipe for self-hosting quakejs in an https-friendly manner using kamal.
https://github.com/neonwatty/kamal-quake
docker kamal kamal2 quakejs
Last synced: 3 months ago
JSON representation
A simple recipe for self-hosting quakejs in an https-friendly manner using kamal.
- Host: GitHub
- URL: https://github.com/neonwatty/kamal-quake
- Owner: neonwatty
- Created: 2024-11-12T23:07:34.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-12-14T14:14:07.000Z (10 months ago)
- Last Synced: 2025-04-08T06:35:29.554Z (6 months ago)
- Topics: docker, kamal, kamal2, quakejs
- Language: Ruby
- Homepage:
- Size: 2.66 MB
- Stars: 4
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# kamal-quake
This repo contains a [work-in-progress](#remaining-challenges) simple recipe for self-hosting [quakejs](https://github.com/inolen/quakejs) in an https-friendly manner using [kamal 2](https://kamal-deploy.org/). Setting up quakejs with https has been traditionally rather complex, but kamal (and docker) makes it a breeze. Docker nicely containerizes the app while kamal makes creating / managing a reverse proxy - as well as the required self-signed SSL certs using letsencrypt - a total breeze.
A table of contents for recommended setup and deployment using this pattern is below:
- [hosting requirements](#hosting-requirements)
- [hosting provider](#hosting-provider)
- [minimum machine specs](#minimum-machine-specs)
- [docker registry](#docker-registry)
- [ssh into your machine](#ssh-into-your-machine)
- [firewall ports](#firewall-ports)
- [kamal deployment](#kamal-deployment)
- [installing kamal](#installing-kamal)
- [customizing the config](#customizing-the-config)
- [deploy](#deploy)
- [multiplayer gaming](#multiplayer-gaming)
- [what every player should see](#what-every-player-should-see)
- [keyboard controls](#keyboard-controls)
- [creating a multiplayer game](#creating-a-multiplayer-game)
- [joining a multiplayer game](#joining-a-multiplayer-game)
- [remaining challenges](#remaining-challenges)
## hosting requirements
### hosting providers
Any hosting provider - including a self-hosted machine - is just fine. Kamal makes the setup / deployment process using any available machine - regardless of provider - the same.
### minimum machine specs
A minimum of 1 GB of ram is recommended [by the creators of quakejs](https://github.com/inolen/quakejs).
### docker registry
Kamal 2 currently requires an available registry to push your version of the image to. Any docker registry (e.g., github, dockerhub, etc.,) works fine. All you need is your registry name and login secret.
The Kamal team is working to relax this requirement so that in the future no registry will be required.
### ssh into your machine
After ssh-ing into your machine, create a docker user group
```bash
sudo groupadd docker
```
Next, add your default user to the docker user group
```bash
sudo usermod -aG docker
```
### firewall ports
Depending on your choice of usage (http vs https) certain ports must be left open on the security settings / firewall of your hosting instance
- **for http usage:** ports 80 and 27960 must be set open to the web
- **for https usage:** ports 443 and 27960 must be set open to the web
If this is **not** done, you will be stuck in the loading screen of the game.
## kamal deployment
### installing kamal
Once you've setup a hosting machine and docker registry as described above, you are ready to setup / deploy your instance of quakejs (using http or https at your discretion).
First install kamal
```bash
gem install kamal
```
If you need to install ruby first [follow these instructions](https://www.ruby-lang.org/en/documentation/installation/).
### customizing the config
Next pull this repository and adjust its kamal deployment config file, located at
```bash
config/deployyml`
```
This config file is repeated below, with `#TODO` annotations indicating the key-value pairs you must customize. These include the IP address of your machine, your url, docker registry, and docker registry credentials.
```yaml
service: quakejs # <-- (optional) replace with the name of your service
image: / # TODO
servers:
web:
hosts:
- # TODO
options:
publish:
- "27961:27961" # <-- for https usage
- "27960:27960" # <-- for http usage
expose:
- "80"
proxy:
ssl: true
host: # TODO
app_port: 80
healthcheck:
interval: 3
path: /
timeout: 10
env:
SERVER: # TODO
HTTP_PORT: 80
registry:
server: # TODO
username: # TODO
password:
- #TODO
builder:
arch: amd64
ssh:
user: ubuntu
```
### deploy
With the previous steps completed, execute the following at the root of this repository to create your instance of quakejs.
```bash
kamal setup
```
This will pull all requisite images, push your version to your preferred docker registry, setup a reverse proxy for https, and create requisite SSL certs via letsencrypt.
## creating a multiplayer game
### what every player should see
Every player should see the following sequence of screens **when they first visit your url**. These screens correctly cue the player to accept game asset download to their browser, and show download progress of game assets.
#### Screen 1: install accept screen
The first screen every user should see is shown below. It requests permission from the player to download game assets to their chosen browser.
#### Screen 2: download progress screen
The next screen every user should see is shown below. It shows the download progress (to their browser) of game assets.
#### Screen 3: player lobby screen
Once all assets are downloaded the player enters a lobby screen that will look like the one below.
If no multiplayer game has been created, players will stay in this screen forever.
#### Screen 4: game options menu
The game host / first player should create a multiplayer game by pressing `escape` to enter the game options menu.
From there a game may be setup by navigating to the `multiplayer` option in the menu.
## joining a multiplayer game
Once a multiplayer game is started every new player will be directed to it automatically.
If this does not happen press escape to access the game menu. Navigate to multiplayer games, and choose the game you wish to join.
## Remaining challenges
- **Proper secure socket wss setup**: at present this limits play to single player. The fork of quakejs used under the hoo details secure setup in the section titled [Running Secure Servers (Content, Dedicated, and Web) Quick-Start](https://github.com/begleysm/quakejs?tab=readme-ov-file#baseq3-server-step-by-step), perhaps there is a clue there on how to proceed.