Add Helm chart

.env.example

@@ -0,0 +1,5 @@
+DB_HOST=db
+DB_PORT=3306
+DB_NAME=cosmic
+DB_USER=root
+DB_PASS=

.gitignore

@@ -3,6 +3,7 @@
 !.idea/codeStyles/
 *.iml
 /target
+.env
 
 # build files
 /build/

README.md

@@ -48,15 +48,75 @@ The project follows the [semantic versioning](https://semver.org/) scheme using
 * *General changes or improvements* are treated as MINOR: 1.__2__.3 -> 1.__3.0__
 * *Major changes* are treated as MAJOR: __1__.2.3 -> __2.0.0__
 
-## Getting started
-Follow along as I go through the steps to play the game on your local computer from start to finish. I won't go into extreme detail, so if you don't have prior experience with Java or git, you might struggle.
+## Quick start
+
+### Prerequisite
+
+1.  [Docker](https://www.docker.com)
+2.  [Docker Compose](https://docs.docker.com/compose/install)
+
+### Set up environment variables
+
+Create `.env` file by copying the `.env.example` file:
+
+```
+cp .env.example .env
+```
+
+Then, check and edit the `.env` file if necessary.
+
+> Note: Though `.env.example` already contains default settings that make
+> Cosmic work, it is recommended to set settings like `DB_PASS` with reasonable
+> values.
+
+### Start services
+
+To start all services, run:
+
+```bash
+docker compose up -d
+```
+
+Then you can use
+
+```bash
+docker compose logs -f maplestory
+```
+
+to check the logs of Cosmic server.
+
+Once the server is ready, you will see a message like:
+
+```log
+07:24:20.269 [main] INFO  server.Server - Cosmic is now online after 14547 ms.
+```
+
+### Stop services
+
+```bash
+docker compose down
+```
+
+### Rebuild
+
+You must rebuild images after any code changes:
+
+```bash
+docker compose build
+```
+
+## Deploying to Kubernetes
+
+See [charts/cosmic](./charts/cosmic).
+
+## Local setup
+You can also run Cosmic on your actual machine.
 
 We will set up the following:
 - Database - the database is used by the server to store game data such as accounts, characters and inventory items.
 - Server - the server is the "brain" and routes network traffic between the clients.
-- Client - the client is the application used to _play the game_, i.e. MapleStory.exe.
 
-### 1 - Database 
+### 1 - Database
 You will start by installing the database server and database client. Then you will connect to the server with the client to create a new database schema.
 
 #### Steps
@@ -82,17 +142,12 @@ You will start by cloning the repository, then configure the database properties
 #### Steps
 
 1. Clone Cosmic into a new project. In IntelliJ, you would create a new project from version control.
-2. Open _config.yaml_. Find "DB_PASS" and set it to your database root user password.
+2. [Create `.env` file](#set-up-environment-variables) and then load it into current shell session by `. .env` command.
 3. Start the server. The main method is located in `net.server.Server`.
 4. If you see "Cosmic is now online" in the console, it means the server is online and ready to serve traffic. Yay!
 
 Below, I list other ways of running the server which are completely optional.
 
-#### Docker
-Support for Docker is also provided out of the box, as an alternative to running straight in the IDE. If you have [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed it's as easy as running `docker compose up`.
-
-Making changes becomes a bit more tedious though as you have to rebuild the server image via `docker compose up --build`.
-
 #### Jar
 Another option is to start the server from a terminal by running a jar file. You first need to build the jar file from source which requires [Maven](https://maven.apache.org/). Fortunately, [Maven Wrapper](https://maven.apache.org/wrapper/) is provided so you don't have to install Maven separately.
 
@@ -102,15 +157,17 @@ To run the jar, a ``launch.bat`` file is provided for convenience. Simply double
 
 Alternatively, run the jar file from the terminal. Just remember to provide the `wz-path` system property pointing to your wz directory.
 
-### 3 - Client
-The client files are located in a separate repository: https://github.com/P0nk/Cosmic-client
+## Client
+Client is the application used to _play the game_, i.e. MapleStory.exe.
+
+The files are located in a separate repository: https://github.com/P0nk/Cosmic-client
 
 Follow the installation guide in the README.
 
-### 4 - Getting into the game
-You have successfully started the client, and you're looking at the login screen. 
+## Getting into the game
+You have successfully started the client, and you're looking at the login screen.
 
-#### Logging in
+### Logging in
 At this point, you can log in to the admin account using the following credentials:
 * Username: "admin"
 * Password: "admin"
@@ -119,7 +176,7 @@ At this point, you can log in to the admin account using the following credentia
 
 You can also create a new regular account by typing in your desired username & password and attempting to log in. This "automatic registration" feature lets you create new accounts to play around with. It is enabled by default (see _config.yaml_).
 
-#### Entering the game
+### Entering the game
 Create a new character as you normally would, and then select it to enter the game. Hooray, finally we're in!
 
 If you log in to the "Admin" character, you'll notice that the character looks almost invisible. This is hide mode, which is enabled by default when you log in to a GM character. You won't be visible to normal players and no mobs will move if you're alone on the map. Toggle hide mode on or off by typing "@hide" in the in-game chat.

charts/cosmic/.gitignore

@@ -0,0 +1 @@
+charts/

charts/cosmic/.helmignore

@@ -0,0 +1,23 @@
+# Patterns to ignore when building packages.
+# This supports shell glob matching, relative path matching, and
+# negation (prefixed with !). Only one pattern per line.
+.DS_Store
+# Common VCS dirs
+.git/
+.gitignore
+.bzr/
+.bzrignore
+.hg/
+.hgignore
+.svn/
+# Common backup files
+*.swp
+*.bak
+*.tmp
+*.orig
+*~
+# Various IDEs
+.project
+.idea/
+*.tmproj
+.vscode/

charts/cosmic/Chart.lock

@@ -0,0 +1,6 @@
+dependencies:
+- name: mysql
+  repository: oci://registry-1.docker.io/bitnamicharts
+  version: 11.1.4
+digest: sha256:d94b54340014411a896f39f1ae33c71b3b935fe2c92ec11b9bab8dd738baffc8
+generated: "2026-05-09T11:51:40.568682Z"

charts/cosmic/Chart.yaml

@@ -0,0 +1,11 @@
+apiVersion: v2
+name: cosmic
+description: A Helm chart for Cosmic MapleStory server
+type: application
+version: 0.1.0
+appVersion: "1.1.3"
+
+dependencies:
+  - name: mysql
+    version: "11.1.4"
+    repository: "oci://registry-1.docker.io/bitnamicharts"

charts/cosmic/README.md

@@ -0,0 +1,48 @@
+# Helm Chart for Cosmic
+
+## Quick Start
+
+1.  Build the image for Cosmic and push it to your own image repository.
+
+    ```bash
+    docker build -t <image repository>:<image tag> ../../
+    docker image push <image repository>:<image tag>
+    ```
+
+2.  Fetch dependencies.
+
+    ```bash
+    helm dependency build
+    ```
+
+3.  Create `values-override.yaml`.
+
+    ```bash
+    cat <<EOF > values-override.yaml
+    image:
+      repository: <image repository>
+      tag: <image tag>
+    EOF
+    ```
+
+4.  Install the Helm chart into your cluster.
+
+    ```
+    helm install cosmic-release . -f values-override.yaml
+    ```
+
+## Custom Config
+
+1.  Create a copy of `config.yaml` and edit it.
+
+    ```bash
+    cp ../../config.yaml ./config.yaml
+    vim config.yaml
+    ```
+
+2.  Install the Helm chart with your custom config file.
+
+    ```bash
+    helm install cosmic-release ../cosmic -f values-override.yaml \
+      --set-file cosmic.configuration=./config.yaml
+    ```

charts/cosmic/templates/NOTES.txt

@@ -0,0 +1,16 @@
+1. Get the application URL by running these commands:
+{{- if contains "NodePort" .Values.service.type }}
+  export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "cosmic.fullname" . }})
+  export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
+  echo http://$NODE_IP:$NODE_PORT
+{{- else if contains "LoadBalancer" .Values.service.type }}
+     NOTE: It may take a few minutes for the LoadBalancer IP to be available.
+           You can watch its status by running 'kubectl get --namespace {{ .Release.Namespace }} svc -w {{ include "cosmic.fullname" . }}'
+  export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "cosmic.fullname" . }} --template "{{ "{{ (index .status.loadBalancer.ingress 0).ip }}" }}")
+  echo http://$SERVICE_IP:{{ .Values.service.ports.login }}
+{{- else if contains "ClusterIP" .Values.service.type }}
+  export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "cosmic.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
+  export CONTAINER_PORT=$(kubectl get pod --namespace {{ .Release.Namespace }} $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
+  echo "Visit http://127.0.0.1:8080 to use your application"
+  kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:$CONTAINER_PORT
+{{- end }}

charts/cosmic/templates/_helpers.tpl

@@ -0,0 +1,62 @@
+{{/*
+Expand the name of the chart.
+*/}}
+{{- define "cosmic.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Create a default fully qualified app name.
+We truncate at 63 chars because some Kubernetes name fields are limited to this (by the DNS naming spec).
+If release name contains chart name it will be used as a full name.
+*/}}
+{{- define "cosmic.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Create chart name and version as used by the chart label.
+*/}}
+{{- define "cosmic.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Common labels
+*/}}
+{{- define "cosmic.labels" -}}
+helm.sh/chart: {{ include "cosmic.chart" . }}
+{{ include "cosmic.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Selector labels
+*/}}
+{{- define "cosmic.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "cosmic.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Create the name of the service account to use
+*/}}
+{{- define "cosmic.serviceAccountName" -}}
+{{- if .Values.serviceAccount.create }}
+{{- default (include "cosmic.fullname" .) .Values.serviceAccount.name }}
+{{- else }}
+{{- default "default" .Values.serviceAccount.name }}
+{{- end }}
+{{- end }}

charts/cosmic/templates/configmap.yaml

@@ -0,0 +1,11 @@
+{{- if .Values.cosmic.configuration -}}
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ include "cosmic.fullname" . }}
+  labels:
+    {{- include "cosmic.labels" . | nindent 4 }}
+data:
+  config.yaml: |-
+    {{ .Values.cosmic.configuration | nindent 4 }}
+{{- end -}}