/ioquake3-server-gcloud

the fastest way to deploy your own ioquake3 server using docker, kubernetes and google cloud

Primary LanguageShell

ioQuake3 Arena

The fastest way to create your own quake3 server using Docker, Kubernetes and Google Cloud

Prerequisites 📋

  1. Google Cloud account
  2. Google Cloud CLI installed, configured and linked to your account
  3. Docker
  4. Git

1. Add environment variables 💎

Copy the .env.example -> .env and fill the environment variables for the project and cluster sections by taking the project-id from your google cloud account.

Note

Is not necessary to create the cluster, the script will do it for you given the zone

# project
PROJECT_ID=norse-lotus-3621XX
CONTAINER_IMAGE=quake3:latest

# cluster specific
CLUSTER=quake3-cluster-1
ZONE=us-central1

Read about cluster zones +

2. Configure the Server ⚙️

You can customize the server by editing the server.cfg file.

This step is not necessary, the repository comes with a ready-made server configuration.

Note

You will need to rebuild the docker image every time your server.cfg file changes

3. Q3 server to Google Cloud 🌐

Get your server ready to play in 1 command:

./q3s create:remote

This will:

  1. add permissions to all scripts
  2. download all pk3 files
  3. create the google cloud cluster in your account
  4. build the docker image
  5. deploy the image to your google cloud cluster

Important

Your Google Cloud CLI need to be properly linked to your account

After a couple of minutes your server should be online and ready to play 👾

Run the following command to get the IP:

./q3s ip

Until the external-ip is resolved:

NAME     TYPE           CLUSTER-IP     EXTERNAL-IP     PORT(S)           AGE
quake3   LoadBalancer   11.104.2.XXX   35.172.21.XXX   27960:32108/UDP   0s

Note

The connection to the server may succeed after a couple of seconds that the external-ip is resolved

4. Run server on localhost 🚀

Please follow the steps 1-3 described in the next section: 5. Build and deploy manually (recommended)

Alternatively you can run each command (advanced)
  1. Copy all pk3 files inside lib/baseq3 or let the script download them for you
./scripts/prepare.sh
  1. Build the docker image
docker build -t quake3 .
  1. Run the docker container
docker run -p 27960:27960/udp -it quake3

Important 💡

You only need to do this process once, after that, you will need to rebuild the image only if changes are applied to your server.cfg file.

Next time you want to run your server locally just use the ./q3s start command.

After the process, you should be able to connect to your local server from the multiplayer section in your client quake3.

5. Build and deploy manually 💻

In order to have more control during the building and/or deployment process, you can go through the following steps:

  1. Copy the pk3 dependencies into the lib/baseq3 folder or let the script download them for you
./q3s prepare
  1. Build the Docker image
./q3s build
  1. Run the server in a container
./q3s start

At this step you have the server running on localhost 🚀

  1. Create Google Cloud cluster
./q3s create:cluster
  1. Deploy the image to the cluster
./q3s deploy

Now is live on Google Cloud 🌐

6. Erase server from Google Cloud ⭕

To erase your server completely, run the following command:

./q3s delete:remote

Warning

This will permanently erase your cluster, forever. You can not revert this process.

This works very well when you want to prevent your server from incurring increased costs on Google Cloud. No cost will be generated because your server will be completely erased.

You can play with the create:remote and delete:remote commands for only have your server live when you are using it.

7. Considerations 🔶

All deployments to Google Cloud Kubernetes will trigger changes only if a new commit is detected in the repository.

The deploy system provided here uses the latest commit hash in order to identify changes in the environment and tell to Kubernetes that the container must be re-deployed.

If you want to force the deploy without committing your changes, you can run:

./q3s deploy:force

Internally, this will run the deploy script using the -a flag which means allow-empty.

In this case, the deploy system will use a timestamp as hash in order to cause changes in the environment allowing deploy as normal.

8. Command list ❔

You can list all the commands available from your terminal by running:

./q3s help

Help: commands

+----------------+-----------------------------------------------------------------------------+
| command        | description                                                                 |
+================+=============================================================================+
| permissions    | give to scripts necessary permissions to run in the system                  |
+----------------+-----------------------------------------------------------------------------+
| prepare        | give permissions to the scripts and download dependencies                   |
+----------------+-----------------------------------------------------------------------------+
| build          | build docker image                                                          |
+----------------+-----------------------------------------------------------------------------+
| start          | create container and run the server in localhost                            |
+----------------+-----------------------------------------------------------------------------+
| create:cluster | create cluster in google cloud                                              |
+----------------+-----------------------------------------------------------------------------+
| deploy         | deploy the server to the cluster in google cloud                            |
+----------------+-----------------------------------------------------------------------------+
| deploy:force   | force deploy the server even when there are no new commits                  |
+----------------+-----------------------------------------------------------------------------+
| create:remote  | create cluster in google cloud, download dependencies and deploy the server |
+----------------+-----------------------------------------------------------------------------+
| delete:remote  | deletes the cluster from google cloud                                       |
+----------------+-----------------------------------------------------------------------------+
| ip             | displays the server public ip                                               |
+----------------+-----------------------------------------------------------------------------+

9. Troubleshooting ⚡️

1. Permission denied when running the scripts

# for the main script
chmod +x q3s

# for the task scripts
./q3s permissions

2. Server is deployed but I cannot connect

Check that the pk3 files are not corrupted, this can cause an error when exposing the q3 server.

Try deleting all the files inside lib/baseq3 and then running the ./q3s prepare command for download them again.

After that, you need to rebuild the docker image and redeploy it to google cloud by running:

./q3s build
./q3s deploy:force

You should be able to connect to your server after a couple of seconds.

diegoulloao · 2024