Deploy a PaperMC Minecraft server to DigitalOcean Kubernetes using GitOps principles.
Note: The server runs Minecraft 1.21.11.
In the Minecraft Launcher, create an installation for version 1.21.11 (Installations → New installation) and use it to connect. The latest client version will not join a 1.21.11 server.
-
Fork this repository to your GitHub account.
-
GitHub disables workflows on forks by default. Go to the Actions tab in your fork and click "I understand my workflows, enable them".
-
The workflow runs two jobs on every push:
secret-scanandbuild. Thesecret-scanjob uses TruffleHog to scan your git history for leaked credentials (like your DigitalOcean token) and blocks the build if it finds any. Make a small commit tomainto trigger the workflow, then verify both jobs pass. Once complete, your container image will be available atghcr.io/<your-github-username>/msud-cmute-gitops-workshop:latest. -
By default, the package GitHub builds is private and your cluster will not be able to pull it. Go to your fork's Packages →
msud-cmute-gitops-workshop→ Package settings → Change visibility → Public.
- Install and authenticate doctl:
doctl auth init --access-token <YOUR_DO_TOKEN>- Provision your DOKS cluster:
cd infra/tofu
cp terraform.tfvars.example terraform.tfvars-
Edit
terraform.tfvars— replace<YOUR_NAME>incluster_namewith your name (lowercase, no spaces). -
Apply:
tofu init
tofu plan
tofu applyCluster creation takes ~8 minutes. Grab some water.
- Save your kubeconfig:
doctl kubernetes cluster kubeconfig save paper-<YOUR_NAME>Example:
doctl kubernetes cluster kubeconfig save paper-test- Verify access:
kubectl get nodesYou should see a single node in Ready status.
Example:
NAME STATUS ROLES AGE VERSION
default-37gop8 Ready <none> 14m v1.36.0- Install the Gateway API CRDs and Envoy Gateway:
kubectl apply --server-side --force-conflicts \
-f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.5.1/experimental-install.yamlYou should see:
customresourcedefinition.apiextensions.k8s.io/backendtlspolicies.gateway.networking.k8s.io serverside-applied
customresourcedefinition.apiextensions.k8s.io/gatewayclasses.gateway.networking.k8s.io serverside-applied
customresourcedefinition.apiextensions.k8s.io/gateways.gateway.networking.k8s.io serverside-applied
customresourcedefinition.apiextensions.k8s.io/grpcroutes.gateway.networking.k8s.io serverside-applied
customresourcedefinition.apiextensions.k8s.io/httproutes.gateway.networking.k8s.io serverside-applied
customresourcedefinition.apiextensions.k8s.io/listenersets.gateway.networking.k8s.io serverside-applied
customresourcedefinition.apiextensions.k8s.io/referencegrants.gateway.networking.k8s.io serverside-applied
customresourcedefinition.apiextensions.k8s.io/tcproutes.gateway.networking.k8s.io serverside-applied
customresourcedefinition.apiextensions.k8s.io/tlsroutes.gateway.networking.k8s.io serverside-applied
customresourcedefinition.apiextensions.k8s.io/udproutes.gateway.networking.k8s.io serverside-applied
validatingadmissionpolicy.admissionregistration.k8s.io/safe-upgrades.gateway.networking.k8s.io serverside-applied
validatingadmissionpolicybinding.admissionregistration.k8s.io/safe-upgrades.gateway.networking.k8s.io serverside-applied
customresourcedefinition.apiextensions.k8s.io/xbackendtrafficpolicies.gateway.networking.x-k8s.io serverside-applied
customresourcedefinition.apiextensions.k8s.io/xmeshes.gateway.networking.x-k8s.io serverside-appliedhelm install eg oci://docker.io/envoyproxy/gateway-helm \
--version v1.8.2 \
-n envoy-gateway-system \
--create-namespace \
--skip-crdskubectl apply -f infra/envoy-gateway/gatewayclass.yamlVerify Envoy Gateway is running and the GatewayClass is accepted:
kubectl get pods -n envoy-gateway-system
kubectl get gatewayclass egNAME CONTROLLER ACCEPTED AGE
eg gateway.envoyproxy.io/gatewayclass-controller True 14s- Install cert-manager:
kubectl apply --server-side -f https://github.com/cert-manager/cert-manager/releases/download/v1.21.0/cert-manager.yamlkubectl wait --for=condition=available deployment/cert-manager -n cert-manager --timeout=120s- Create the DigitalOcean DNS-01 secret and ClusterIssuer (use the same DO token from earlier):
NOTE: BE SURE TO REPLACE THE EMAIL LINE!!!
kubectl create secret generic digitalocean-dns \
--namespace cert-manager \
--from-literal=access-token=<YOUR_DO_TOKEN>Edit infra/cert-manager/clusterissuer.yaml and replace <YOUR_EMAIL> with your email. Then run:
kubectl apply -f infra/cert-manager/clusterissuer.yaml- Install ArgoCD:
kubectl create namespace argocd
kubectl apply -n argocd --server-side -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml- Verify ArgoCD is running:
kubectl wait --for=condition=available deployment/argocd-server -n argocd --timeout=120sThe single paper-gateway (defined in k8s/gateway.yaml) has two listeners: a TCP listener for Minecraft and an HTTPS listener for the ArgoCD UI. They share the same LoadBalancer IP.
- Tell ArgoCD not to terminate TLS itself (the Gateway does it):
kubectl patch deployment argocd-server -n argocd --type='json' \
-p='[{"op": "add", "path": "/spec/template/spec/containers/0/args/-", "value": "--insecure"}]'
kubectl rollout status deployment/argocd-server -n argocd- Edit
k8s/argocd-httproute.yamland replace<YOUR_NAME>with your name, then apply:
kubectl apply -f k8s/argocd-httproute.yaml-
Look at all files in
k8s/:namespace.yamlconfigmap.yamlpersistentvolumeclaim.yamldeployment.yamlIMPORTANT: replace<YOUR_GITHUB_USERNAME>with your GitHub username (must be lowercase)service.yamlgateway.yamlIMPORTANT: replace<YOUR_NAME>in the ArgoCD HTTPS listener hostnametcproute.yamlcertificate.yamlIMPORTANT: replace<YOUR_NAME>in both certs (matches your DNS records below)
-
In
argocd/application.yaml, look at the file and replace<YOUR_GITHUB_USERNAME>with your GitHub username. -
Check that you didn't miss any placeholders:
grep -rn "YOUR_NAME\|YOUR_GITHUB" k8s/ argocd/ && echo "^^ FIX THESE BEFORE CONTINUING" || echo "all placeholders replaced"- Commit and push:
git add -A
git commit -m "chore: configure k8s manifests with my values"
git push- Apply the ArgoCD application:
kubectl apply -f argocd/application.yaml- Watch ArgoCD deploy everything:
kubectl get applications -n argocd
kubectl get pods -n paperThe paper pod takes 1–2 minutes to become 1/1 Ready (the startup probe waits for the Minecraft server to boot).
All traffic (Minecraft and the ArgoCD UI) flows through the single Gateway LoadBalancer.
- Get your Gateway's external IP:
kubectl get gateway paper-gateway -n paperThe ADDRESS field takes 1–3 minutes to appear while DigitalOcean provisions the load balancer. Your certificates take another 1–3 minutes to become Ready — check with:
kubectl get certificates -n paper- (Optional) Verify the Minecraft port is reachable through the Gateway:
timeout 3 bash -c '</dev/tcp/<GATEWAY_EXTERNAL_IP>/25565' && echo OPEN || echo CLOSEDIf this prints OPEN, Envoy is routing TCP traffic to your server. If it prints CLOSED, wait a minute and try again before debugging.
- Create a DNS record for ArgoCD pointing to the Gateway IP:
doctl compute domain records create cmute.cloud \
--record-type A \
--record-name "argocd.<YOUR_NAME>.mc.labs" \
--record-data <GATEWAY_EXTERNAL_IP> \
--record-ttl 300- Create a DNS record for your Minecraft server pointing to the same Gateway IP:
doctl compute domain records create cmute.cloud \
--record-type A \
--record-name "<YOUR_NAME>.mc.labs" \
--record-data <GATEWAY_EXTERNAL_IP> \
--record-ttl 300- Get the initial ArgoCD admin password and log in at
https://argocd.<YOUR_NAME>.mc.labs.cmute.cloud:
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d; echo- Connect with your Minecraft client (version 1.21.11) to
<YOUR_NAME>.mc.labs.cmute.cloud.
Make a change and watch ArgoCD sync it automatically.
-
Edit
k8s/configmap.yaml. Changemax-playersto50. -
Edit
k8s/deployment.yaml. Change theconfigmap-hashannotation to any new value (ex:"2"). This triggers a pod restart so Minecraft picks up the new config. -
Commit and push.
-
Watch the sync:
kubectl get pods -n paperWithin about 3 minutes, ArgoCD will detect the change and roll out a new pod automatically. You'll briefly be disconnected from the server while the pod restarts — that's the deployment happening. Watch it live in the ArgoCD UI.
Add Prometheus metrics and a Grafana dashboard for your server: extras/observability
Cluster teardown is handled by the instructor after the workshop. Leave your cluster running.