docs: 📝 Improve documentation and project structure (#25)

* build: add auto-labeler and sponsors information (#17)

* Update README.md

* Create sponsors.yml

* Create label.yml

* test: resolve issue thing

* style: remove typo

* chore: update

* build(deps): bump softprops/action-gh-release from 1 to 2 (#18)

Bumps [softprops/action-gh-release](https://github.com/softprops/action-gh-release) from 1 to 2.
- [Release notes](https://github.com/softprops/action-gh-release/releases)
- [Changelog](https://github.com/softprops/action-gh-release/blob/master/CHANGELOG.md)
- [Commits](softprops/action-gh-release@v1...v2)

---
updated-dependencies:
- dependency-name: softprops/action-gh-release
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* build(deps): bump actions/checkout from 3 to 4 (#19)

Bumps [actions/checkout](https://github.com/actions/checkout) from 3 to 4.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](actions/checkout@v3...v4)

---
updated-dependencies:
- dependency-name: actions/checkout
  dependency-type: direct:production
  update-type: version-update:semver-major
...

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

* docs: 📝 Improve documentation (#21)

* docs: docker whale image

* Update README.md

* Update README.md

* Update README.md

* docs: add more examples

* docs: add more examples

* docs: improve docs

* Update README.md

* Update README.md

* Update README.md

* test

* Update BUILDING_AN_IMAGE.md

* Update label.yml

* Delete crowbar.png

* Update README.md

* Update sponsors.yml

* docs: more doc improvements/spell checks etc

* Deploying to beta from @ ee94d7c 🚀

* Update sponsors.yml

* Update README.md

* docs: server -> joinable not error

* Update CUSTOM_MODS.md

* Update SERVER_CONFIGS_AND_PLUGINS.md

* Update README.md

* Update README.md

* Update BUG.yml

* docs: fix clipping issue

* build: 🔧 adjust docker-compose.local to docker-compose.build as it more accurately describes its task

* feat: split things into container dir

* docs: shuffle docs around

* Update beta.yml

* Update publish.yml

* Update README.md

* docs: improve REAMDE

* Update README.md

* Update CONTRIBUTING.md

* docs: remove old examples

* docs: cleanup docs

* Update Dockerfile

* Update Dockerfile

* Update Dockerfile

* docs: more doc examples.

* Update docker-compose.yml

* Update .gitignore

* Update entrypoint.sh

---------

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: JamesIves <[email protected]>

.github/ISSUE_TEMPLATE/BUG.yml

@@ -25,7 +25,8 @@ body:
       label: Approach
       description: How are you running the container image?
       options:
-        - I am using a pre-built image on Dockerhub
+        - I am using a pre-built image on Dockerhub (jives/hlds)
+        - I am using a pre-built image on the GitHub Container Registry (ghcr.io/jamesives/hlds)
         - I built the image myself
       default: 0
     validations:

.github/workflows/beta.yml

@@ -37,6 +37,7 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Replace fallback value in Dockerfile and entrypoint.sh
+        working-directory: ./container
         run: |
           sed -i "s/\${GAME:-valve}/\${GAME:-${{ matrix.game }}}/g" Dockerfile
           sed -i "s/\${GAME:-valve}/\${GAME:-${{ matrix.game }}}/g" entrypoint.sh
@@ -46,7 +47,7 @@ jobs:
         env:
           GAME: ${{ matrix.game }}
         with:
-          context: .
+          context: ./container
           push: true
           tags: jives/hlds:${{ matrix.game }}-beta
           build-args: GAME=${{ matrix.game }}
@@ -60,7 +61,7 @@ jobs:
         env:
           GAME: ${{ matrix.game }}
         with:
-          context: .
+          context: ./container
           push: true
           tags: ghcr.io/${{ steps.repo_owner.outputs.repo_owner }}/hlds:${{ matrix.game }}-beta
           build-args: GAME=${{ matrix.game }}

.github/workflows/publish.yml

@@ -16,7 +16,7 @@ jobs:
 
       - name: Bump Version and Create Tag 🏷️
         id: create_tag
-        uses: anothrNick/github-tag-action@1.69.0
+        uses: anothrNick/github-tag-action@1.70.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           WITH_V: true
@@ -56,6 +56,7 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Replace fallback value in Dockerfile and entrypoint.sh
+        working-directory: ./container
         run: |
           sed -i "s/\${GAME:-valve}/\${GAME:-${{ matrix.game }}}/g" Dockerfile
           sed -i "s/\${GAME:-valve}/\${GAME:-${{ matrix.game }}}/g" entrypoint.sh
@@ -65,7 +66,7 @@ jobs:
         env:
           GAME: ${{ matrix.game }}
         with:
-          context: .
+          context: ./container
           push: true
           tags: |
             jives/hlds:${{ matrix.game }}
@@ -81,7 +82,7 @@ jobs:
         env:
           GAME: ${{ matrix.game }}
         with:
-          context: .
+          context: ./container
           push: true
           tags: |
             ghcr.io/${{ steps.repo_owner.outputs.repo_owner }}/hlds:${{ matrix.game }}
@@ -102,7 +103,7 @@ jobs:
       - name: Bump Version and Create Tag 🏷️
         id: create_tag
         if: github.ref == 'refs/heads/main'
-        uses: anothrNick/github-tag-action@1.69.0
+        uses: anothrNick/github-tag-action@1.70.0
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           WITH_V: true

.gitignore

@@ -1,3 +1,4 @@
 .DS_Store
 
-mods/*
+mods/*
+config/*

CONTRIBUTING.md

@@ -14,7 +14,7 @@ The four main requirements for this project are:
 ## Process
 
 1. File an issue on the [Issues board](https://github.com/JamesIves/hlds-docker/issues), or create a discussion on the [Discussions board](https://github.com/JamesIves/hlds-docker/discussions).
-2. Once discussed and agreed upon, clone the project.
+2. Once discussed and agreed upon, clone the project and base your changes on the `beta` branch.
 3. Make your changes.
 4. Validate your changes; at the very least, please build the image and start a server. [You can learn how to build the images using the guide located here](docs/BUILDING_AN_IMAGE.md).
 5. Submit a pull request to the `beta` branch.

README.md

@@ -1,7 +1,7 @@
-<img align="right" width="180" height="auto"  src="./.github/docs/docker.svg" alt="Docker in the Half-Life Colours">
-
 # hlds-docker
 
+<img align="right" width="180" height="auto"  src="./.github/docs/docker.svg" alt="Docker in the Half-Life Colours">
+
 [Half-Life Dedicated Server](https://help.steampowered.com/en/faqs/view/081A-106F-B906-1A7A) powered by [Docker](https://www.docker.com). It supports all the classic [GoldSrc](https://developer.valvesoftware.com/wiki/GoldSrc) Half-Life games and mods, including the ability to add custom configurations and plugins.
 
 Special thank you to all the past and present [GitHub Sponsors](https://github.com/sponsors/JamesIves) 💖.
@@ -57,6 +57,6 @@ If you'd prefer to configure your server using [Docker Compose](https://docs.doc
 
 To customize the server client further, please check out the following advanced setup guides.
 
-- [Server Configs and Plugins](docs/SERVER_CONFIGS_AND_PLUGINS.md)
-- [Custom Mods](docs/CUSTOM_MODS.md)
-- [Building a Custom Image](docs/BUILDING_AN_IMAGE.md)
+- [Server Configs and Plugins](config/README.md)
+- [Custom Mods](mods/README.md)
+- [Building a Custom Image](container/README.md)

config/README.md

@@ -1 +1,24 @@
-For details on how to use this directory refer to the Server Configuration section of the README.
+# Configs and Plugins
+
+If you wish to add server configurations, such as add-ons, plugins, map rotations, etc, you can add them to the `config` directory. The `config` directory is volume-mapped within the directory for the game for which you're starting the container. For example, if you're starting a container for `cstrike`, you can add things like `mapcycle.txt` or `motd.txt` here, and it would appear within the corresponding `cstrike` directory on the server.
+
+> [!NOTE]  
+> The startup examples posted in the project README already have this directory volume mapped accordingly. If you've strayed from the suggested setup, [please refer back to it to get started](../../README.md).
+
+```
+├── hlds
+│   ├── cstrike
+│   │   ├── models
+│   │   ├── maps
+│   │   ├── mapcycle.txt
+│   │   ├── motd.txt
+```
+
+> [!TIP]  
+> You can use this method to install server plugins such as AMX Mod, Meta Mod, etc., as the directory can handle nested folders too; for example, these can be placed in `config/addons/amxmodx` etc.
+
+1. Create a folder called `config` alongside where you would typically start the server process. If you've cloned this project locally, you'd place it alongside this README file.
+2. Add your config files to the directory.
+3. Start the image as you usually would, either with `docker run` or `docker compose up`.
+
+For a list of all the available server configuration types, [refer to the Valve Developer Wiki](https://developer.valvesoftware.com/wiki/Main_Page).

Dockerfile → container/Dockerfile

@@ -1,14 +1,20 @@
 FROM ubuntu:18.04
 
+LABEL org.opencontainers.image.title="hlds"
+LABEL org.opencontainers.image.description="🐋 📦 Half-Life Dedicated Server powered by Docker. Supports all the classic GoldSrc Half-Life games and mods, including the ability to add custom configurations and plugins."
+LABEL org.opencontainers.image.vendor="https://jamesiv.es"
+LABEL org.opencontainers.image.authors="James Ives"
+LABEL org.opencontainers.image.licenses="MIT"
+LABEL org.opencontainers.image.url="https://github.com/jamesives/hlds-docker"
+LABEL org.opencontainers.image.documentation="https://github.com/jamesives/hlds-docker"
+LABEL org.opencontainers.image.source="https://github.com/jamesives/hlds-docker"
+
 # Sets an environment variable for the game to install.
 # Supported games: valve, cstrike, czero, dod, dmc, gearbox, ricochet, tfc
 # Default is valve. This get replaced when building the image with --build-arg GAME=<game>
 ARG GAME=valve
 ENV GAME ${GAME}
 
-LABEL vendor="jives.dev" \
-    maintainer="James Ives"
-
 RUN dpkg --add-architecture i386 && \
     apt-get update && \
     apt-get install -y --no-install-recommends curl rsync file libc6:i386 lib32stdc++6 ca-certificates && \
@@ -25,14 +31,15 @@ WORKDIR /opt/steam
 
 COPY ./hlds.txt /opt/steam
 
-# Replace $GAME with the requested mod to install in hlds.txt.
+# Replaces $GAME with the requested mod to install in hlds.txt.
 RUN sed -i "s/\$GAME/${GAME}/g" /opt/steam/hlds.txt
 
 RUN curl -v -sL media.steampowered.com/client/installer/steamcmd_linux.tar.gz | tar xzvf - && \
     file /opt/steam/linux32/steamcmd && \
     ./steamcmd.sh +runscript /opt/steam/hlds.txt
 
 # Writes the steam_appid.txt file to the hlds directory with the title id for Half-Life.
+# Patches a known issue with the Steam client.
 RUN mkdir -p $HOME/.steam \
     && ln -s /opt/steam/linux32 $HOME/.steam/sdk32 \
     && echo 70 > /opt/steam/hlds/steam_appid.txt

docs/BUILDING_AN_IMAGE.md → container/README.md

@@ -23,13 +23,13 @@ Before continuing to the following steps, verify that the environment variable i
 > - `dod` ([Day of Defeat](https://store.steampowered.com/app/30/Day_of_Defeat/))
 > - `tfc` ([Team Fortress Classic](https://store.steampowered.com/app/20/Team_Fortress_Classic/))
 
-3. Build the image.
+3. Navigate to the `container` folder (where this README file is) and build the image.
 
 ```sh
-docker compose -f docker-compose.local.yml build
+docker compose build
 ```
 
-4. If you want to modify the server startup arguments, you can provide a `command` property within `docker-compose.local.yml`; [for a list of available arguments, visit the Valve Developer Wiki](https://developer.valvesoftware.com/wiki/Half-Life_Dedicated_Server).
+4. If you want to modify the server startup arguments, you can provide a `command` property within `docker-compose.yml`; [for a list of available arguments, visit the Valve Developer Wiki](https://developer.valvesoftware.com/wiki/Half-Life_Dedicated_Server).
 
 > [!NOTE]  
 > In most cases, you'll need to specify `+map` for the server to be joinable.
@@ -43,8 +43,15 @@ services:
 5. Start the image. Once the Half-Life Dedicated Server client starts, you'll receive a stream of messages, including the server's public IP address and any startup errors.
 
 ```bash
-docker compose -f docker-compose.local.yml up
+docker compose up
 ```
 
 6. Connect to your server via the public IP address by loading the game on [Steam](https://store.steampowered.com/). To play, you must own a copy of the game on Steam.
-7. _Optional_: If you want to start a custom mod, you can modify your `$GAME` environment variable once the image is built before running `docker compose -f docker-compose.local.yml up`. This allows you to add custom scripts to the server image while telling the dedicated server client what mod to use.
+7. _Optional_: If you want to start a custom mod, you can modify your `$GAME` environment variable once the image is built before running `docker compose up`. This allows you to add custom scripts to the server image while telling the dedicated server client what mod to use. If you're building a custom image with the intent on playing a custom mod it's recommended that you set the `$GAME` variable to `valve` for the initial build.
+
+```bash
+$export GAME=valve
+$ docker compose build
+$export GAME=decay
+$ docker compose up
+```

container/config/README.md

@@ -0,0 +1,27 @@
+# Configs and Plugins
+
+> [!WARNING]  
+> Configs added here will be included in the distributed image. This means users must override them on startup when using a distributed version.
+
+If you wish to add server configurations, such as add-ons, plugins, map rotations, etc, you can add them to the `config` directory. The `config` directory is volume-mapped within the directory for the game for which you're starting the container. For example, if you're starting a container for `cstrike`, you can add things like `mapcycle.txt` or `motd.txt` here, and it would appear within the corresponding `cstrike` directory on the server.
+
+> [!NOTE]  
+> The startup examples posted in the project README already have this directory volume mapped accordingly. If you've strayed from the suggested setup, [please refer back to it to get started](../../README.md).
+
+```
+├── hlds
+│   ├── cstrike
+│   │   ├── models
+│   │   ├── maps
+│   │   ├── mapcycle.txt
+│   │   ├── motd.txt
+```
+
+> [!TIP]  
+> You can use this method to install server plugins such as AMX Mod, Meta Mod, etc., as the directory can handle nested folders too; for example, these can be placed in `config/addons/amxmodx` etc.
+
+1. Create a folder called `config` alongside where you would typically start the server process. If you've cloned this project locally, you'd place it alongside this README file.
+2. Add your config files to the directory.
+3. Start the image as you usually would, either with `docker run` or `docker compose up`.
+
+For a list of all the available server configuration types, [refer to the Valve Developer Wiki](https://developer.valvesoftware.com/wiki/Main_Page).

entrypoint.sh → container/entrypoint.sh

@@ -7,6 +7,7 @@ if echo "$@" | grep -qv "+map"; then
   echo -e "\e[33mWarning: No +map specified in the command. Server will start but may not be joinable.\e[0m"
 fi
 
+# Push mods and config files from their temp directories to the server directories.
 if [ -d /temp/mods ]
 then
   rsync --chown=steam:steam /temp/mods/* /opt/steam/hlds
@@ -19,4 +20,5 @@ fi
 
 echo -e "\e[32mStarting Half-Life Dedicated Server for $GAME...\e[0m"
 
+# Start the server with the specified game and any additional arguments.
 ./hlds_run "-game $GAME $@"

container/mods/README.md

@@ -0,0 +1,38 @@
+# Custom Mods
+
+> [!WARNING]  
+> Mods added here will be included in the distributed image. This means users must override them on startup when using a distributed version.
+
+If you want to run a custom mod, you can do so with the `mods` directory. The `mods` directory is volume mapped within the root directory of the Half-Life Dedicated Server client on startup. For example, if you wanted to add a mod named `decay`, you'd place it as a subfolder here, i.e., `mods/decay`. Once the container starts, it would be placed in the following directory.
+
+```
+├── hlds
+│   ├── cstrike
+│   │   ├── models
+│   │   ├── maps
+│   │   ├── autoexec.cfg
+│   ├── valve
+│   │   ├── models
+│   │   ├── maps
+│   │   ├── autoexec.cfg
+│   ├── decay
+│   │   ├── models
+│   │   ├── maps
+│   │   ├── autoexec.cfg
+```
+
+> [!NOTE]  
+> The startup examples posted in the project README already have this directory volume mapped accordingly. If you've strayed from the suggested setup, [please refer back to it to get started](../README.md).
+
+1. Create a folder called `mods` alongside where you would normally start the server process. If you've cloned this project locally, you'd place it alongside this README file.
+2. Add your mod files as a sub-directory of `mods`. For example if the mod name is `decay`, you'd place it in `mods/decay`.
+3. Define the `GAME` environment variable for your mod name. The dedicated server client will use this to ensure that it starts a server for the correct mod, which corresponds with the directory name that was just created.
+
+```bash
+export GAME=decay
+```
+
+4. Start the image as you usually would, either with `docker run` or `docker compose up`. Most Half-Life mods require specific startup arguments. For more details, refer to the [Valve Developer Wiki](https://developer.valvesoftware.com/wiki/Half-Life_Dedicated_Server) and the instructions for the mod you're trying to run.
+
+> [!TIP]  
+> When using a pre-built image, you'll likely want to use the `valve` base image (`jives/hlds:valve`).

docker-compose.yml

@@ -1,9 +1,17 @@
 services:
   hlds:
     build: docker
-    # 📣 Adjust the image value here with the desired game you want the server to use.
+    # 📣 Adjust the image value here with the desired game you want the server to use. Options include:
+    # 🔧 jives/hlds:valve (Half-Life Deathmatch)
+    # 🔧 jives/hlds:cstrike (Counter-Strike)
+    # 🔧 jives/hlds:czero (Counter-Strike: Condition Zero)
+    # 🔧 jives/hlds:dmc (Deathmatch Classic)
+    # 🔧 jives/hlds:gearbox (Half-Life Opposing Force)
+    # 🔧 jives/hlds:ricochet (Ricochet)
+    # 🔧 jives/hlds:dod (Day of Defeat)
+    # 🔧 jives/hlds:tfc (Team Fortress Classic)
     image: jives/hlds:cstrike
-    # 📣 Learn more about these volumes in the advanced setup guides.
+    # 📣 Learn more about these volumes in the advanced setup guides: https://github.com/JamesIves/hlds-docker?tab=readme-ov-file#advanced-setup-%EF%B8%8F
     volumes:
       - "./config:/temp/config"
       - "./mods:/temp/mods"
@@ -13,6 +21,7 @@ services:
       - "26900:2690/udp"
     environment:
       - GAME=${GAME}
-    # 📣 Modify your server startup commands here.
+    # 📣 Modify your server startup commands here, you can add more flags as needed (see: https://developer.valvesoftware.com/wiki/Half-Life_Dedicated_Server),
     # 📣 Remember: Stating map is based on the game, and will likely be different between images.
-    command: +maxplayers 12 +map cs_italy
+    # 📣 You should also modify the rcon_password value so you can use server admin commands.
+    command: +log on +rcon_password "changeme" +maxplayers 12 +map cs_italy