{"id":25306565,"url":"https://github.com/cbartram/hearthhub-kube-api","last_synced_at":"2025-06-28T06:40:43.282Z","repository":{"id":273596544,"uuid":"920183235","full_name":"cbartram/hearthhub-kube-api","owner":"cbartram","description":"An API running on the dedicated linux machine for interfacing with the Valheim server.","archived":false,"fork":false,"pushed_at":"2025-03-05T19:53:32.000Z","size":504,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-05T20:51:53.279Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cbartram.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-21T17:52:28.000Z","updated_at":"2025-03-05T19:53:36.000Z","dependencies_parsed_at":"2025-01-21T21:24:49.688Z","dependency_job_id":"3876bf01-c7c9-4c88-91ce-4c96d588658c","html_url":"https://github.com/cbartram/hearthhub-kube-api","commit_stats":null,"previous_names":["cbartram/hearthhub-mod-api","cbartram/hearthhub-kube-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbartram%2Fhearthhub-kube-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbartram%2Fhearthhub-kube-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbartram%2Fhearthhub-kube-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cbartram%2Fhearthhub-kube-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cbartram","download_url":"https://codeload.github.com/cbartram/hearthhub-kube-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247604604,"owners_count":20965456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-13T10:35:39.668Z","updated_at":"2025-04-07T06:28:59.330Z","avatar_url":"https://github.com/cbartram.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n   \u003cimg src=\"./resources/logo.webp\" height=\"300\" width=\"300\"\u003e\n\u003c/p\u003e\n\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![MIT License][license-shield]][license-url]\n\n# HearthHub Kube API\n\nAn API running on the dedicated linux machine for interfacing between the internet and Kubernetes. This repository\ncontains a docker image which runs the Valheim server on Kubernetes. Unlike the docker image that comes pre-packaged with the Valheim\ndedicated server this image installs the server directly onto the image rather than running a separate \nscript in a generic ubuntu image. It also pre-installs BepInEx on the server, sets up a PVC, and has routes to configure:\n\n- Mod installation\n- Mod removal\n- Automated world backups (to s3)\n- Configuration installation for mods\n- Existing World uploads\n\nall directly on the Valheim Dedicated Server!\n\n## Architecture\n\nThe diagram below represents the general architecture for this repository.\n\n```mermaid\nflowchart TD\n    A[API Request] --\u003e|POST /api/v1/server/create| B[API Server]\n    B --\u003e|Create Job| D[Plugin Manager Service]\n    B --\u003e|Kubernetes Deploy Create| G[Valheim Server Pod]\n    D --\u003e|Download Plugin| E[Plugin Storage S3]\n    D --\u003e|Extract to Volume| F[Shared Volume]\n    G[Valheim Server Pod] --\u003e|Mount| F\n    \n    subgraph Kubernetes Cluster\n        B\n        D\n        E\n        F\n        G\n    end\n```\n\n## Building\n\nTo build the docker image  for the Valheim server run: `./scripts/build_server.sh 0.0.1` replacing `0.0.1` with\nthe image version you would like to use. You should then update the version in the `./manifests/valheim-server/values.yaml`\nfile to match your built image.\n\nRun the `./scripts/build_api.sh` to do the same for the API image.\n\n## Testing\n\nRun unit tests for this software with:\n\n```shell\ngo test ./... -v\n```\n\nTo generate coverage reports run:\n\n```shell\ngo test -coverprofile=coverage.out ./...\ngo tool cover -html=coverage.out\n```\n\n## Kubernetes Setup \n\n### K3s\n\n[K3's](https://docs.k3s.io) is the preferred deployment option because:\n- You can skip the entire [Networking](#networking-minikube-only) section and omit the `tinyproxy` server since it runs natively on the host\n- You can add additional nodes to the cluster to scale horizontally\n- Does not require any type of additional tunneling to be present i.e. `minikube tunnel` in order to access from the internet\n\nTo setup K3's install via: `curl -sfL https://get.k3s.io | sh -`\n\nThen create a `/etc/rancher/k3s/config.yaml` with the following contents:\n\n```yaml\nkubelet-arg:\n  - --system-reserved=cpu=2000m,memory=8000Mi,ephemeral-storage=256Gi\n  - --eviction-hard=imagefs.available\u003c10%,imagefs.inodesFree\u003c10%,memory.available\u003c1Gi,nodefs.available\u003c10%,nodefs.inodesFree\u003c10%,pid.available\u003c10%\n  - --max-pods=100\n```\n\nThis ensures K3's uses at most 2 CPU core's and 8GB of memory to run leaving some resources for your host system. This is necessary since the\ncluster does not run in a VM and shares the host network space.\n\nFinally run: `./scripts/cluster_init.sh` to initialize the required ingress and load balancer controllers, namespaces, and secrets. See [Deploying\nthe API](#deploying-valheim-server-and-hearthhub-api) for more information on how to deploy.\n\nTo restart K3's and apply any new kubelet-arg's run:\n\n```shell\nsudo systemctl stop k3s\nsudo systemctl daemon-reload\nsudo systemctl start k3s\n```\n\n### MiniKube (Deprecated)\n\n:warning: We do not recommend using MiniKube because of networking issues exposing the API to the internet. See [k3s instead](#k3s).\n\nDeployment can be managed through Helm and Minikube. Follow the [MiniKube setup guide](https://minikube.sigs.k8s.io/docs/start/) to the point where you have your cluster running.\nInstall [Helm](https://helm.sh) using their [installation script](https://helm.sh/docs/intro/install/).\n\nCreate the `hearthhub` namespace on your cluster with: `kubectl create ns hearthhub`. It's also useful to have the \n`Ingress` addon with MiniKube configured. You can configure this with `minikube addons enable ingress`.\n\nSince the API makes updates to custom AWS Cognito user attributes, make sure to enter the AWS Cognito related secrets for running the API:\n\n```shell\n# Cognito Secrets\n kubectl create secret generic cognito-secrets \\\n   --from-literal=USER_POOL_ID=us-east-1_example \\\n   --from-literal=COGNITO_CLIENT_ID=abc123example \\\n   --from-literal=COGNITO_CLIENT_SECRET=supersecretvalue \\\n   -n hearthhub\n\n# AWS Secrets\n kubectl create secret generic aws-creds \\\n --from-literal=AWS_ACCESS_KEY_ID=\u003cKEY\u003e \\\n --from-literal=AWS_SECRET_ACCESS_KEY=\u003cSECRET\u003e \\\n -n hearthhub\n```\n\nFinally, you should update your `/etc/hosts/` file with the DNS entry for your API:\n\n```shell\n# Add this to /etc/hosts\n127.0.0.1 hearthhub-api.example\n```\n\n:warning: For internet access to the API you will also need to deploy a `tinyproxy` or proxy service on a port of your choosing running on the host to proxy\nrequests from the internet to the VM while the tunnel is running. See [networking](#networking-minikube-only) for more information.\n\n### Deploying Valheim Server and HearthHub API\nTo deploy the hearthhub-KUBE-api run:\n\n`helm install hearthhub-kube-api ./manifests/hearthhub-kube-api -f ./manifests/hearthhub-kube-api/values.yaml`\n\nThe API comes with a service which exposes `NodePort` 30000 and can be accessed via: `http://localhost:30000/api/v1/health`\nThe API is pre-configured with basic auth, and you can generate the auth value like so:\n\n```shell\nAUTH_VALUE=$(echo \u003cdiscord_id\u003e:\u003crefresh_token\u003e | base64)\n\ncurl -H \"Authorization: Basic $AUTH_VALUE\" -X GET http://localhost:30000/api/v1/health\n```\n\n### API Routes\n\nComing soon.\n\n### Running Locally\n\nYou can run this API locally but will need to create a `.env` file in the root of the project.\n\n```dotenv\nCOGNITO_CLIENT_SECRET=\u003ccognito_secret\u003e\nCOGNITO_CLIENT_ID=\u003ccognito_client_id\u003e\nUSER_POOL_ID=\u003cuser_pool_id\u003e\n\nAWS_SECRET_ACCESS_KEY=\u003caws_secret_access_key\u003e\nAWS_ACCESS_KEY_ID=\u003caws_access_key_id\u003e\nAWS_REGION=us-east-1\n\nCPU_REQUEST=1\nCPU_LIMIT=1\nMEMORY_REQUEST=4Gi\nMEMORY_LIMIT=4Gi\nBUCKET_NAME=\u003cyour-s3-bucket-no-s3://-prefix\u003e\n\nVALHEIM_IMAGE_NAME=cbartram/hearthhub\nVALHEIM_IMAGE_VERSION=0.0.6\nBACKUP_MANAGER_IMAGE_NAME=cbartram/hearthhub-sidecar\nBACKUP_MANAGER_IMAGE_VERSION=0.0.4\nFILE_MANAGER_IMAGE_NAME=cbartram/hearthhub-plugin-manager\nFILE_MANAGER_IMAGE_VERSION=0.0.9\n\nRABBITMQ_DEFAULT_USER=\u003cusername\u003e\nRABBITMQ_DEFAULT_PASS=\u003cpass\u003e\n```\n\nBuild the API with `go build -o main .` and run with `./main` The API will be running on: `http://localhost:8080`\n\n## Networking (MiniKube only)\n\n:warning: This application has been built and tested on [MiniKube](https://minikube.sigs.k8s.io) however, we strongly recommend using [K3s](https://k3s.io/)\n\nMinikube uses (by default) a Docker VM to run MiniKube which has its own network separate\nfrom your host machine. By running `minikube tunnel` it will forward services from your [MiniKube](https://minikube.sigs.k8s.io) network to your host network and **ONLY**\nyour host network.\n\nWhat this means is that if you have a service like this:\n\n```shell\nNAME                TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE\nhearthhub-kube-api   LoadBalancer   10.99.134.178   127.0.0.1     8080:30616/TCP   9m41s\n```\n\nThen:\n\n`curl http://localhost:8080/api/v1/health` will resolve. However, port forwarding your router and going to: `http://\u003cyour-ip\u003e:8080/api/v1/health` will\nnot resolve. It is only available on your host machine. Great for testing, not great for exposing your service to the internet. You can further verify this\nby opening up and forwarding port `8081` on your router and starting a Python http server.\n\n`python3 -m http.server 8081`\n\nGoing to [CanYouSeeMe.org](https://canyouseeme.org/) for port `8081` will show successful while port `8080` will show nothing even though both are port forwarded\nand HTTP server's are running on both ports.\n\nThe solution: [Tinyproxy](https://tinyproxy.github.io/)\n\nInstall tinyproxy with `sudo apt install tinyproxy`\n\nApply the following configurations to `/etc/tinyproxy/tinyproxy.conf`\n\n- `Port 8081`\n- Comment out all \"Allow\" statements (effectively allow all)\n- `Upstream http 127.0.0.1:8080` (assumes hearthhub-api service's external IP is 127.0.0.1 and its port is 8080)\n\nNow tiny proxy is setup on the host machine to proxy traffic from all external sources to the `minikube tunnel` which is forwarding\nthe Hearthhub Mod API service.\n\n```mermaid\nflowchart LR\n    A[Client Machine] --\u003e|HTTP/HTTPS Request| B[Router\\nPort Forwarding:\\n80 → 8081\\n443 → 8081]\n    B --\u003e|Forward to Port 8081| C[TinyProxy\\nListening on Port 8081]\n    C --\u003e|Proxy Request| D[Minikube Tunnel]\n    D --\u003e|Route to DockerVM| E[DockerVM]\n    E --\u003e|Forward to Service| F[Kubernetes Service]\n    F --\u003e|Route to Pod| G[HearthHub API\\nPort 8080]\n```\n\n### TLDR\n\n```shell\nminikube start --cpus 3 --memory 8192\n\n# In a new window (necessary to expose services in the cluster VM to your host)\n# so the proxy can reach your API.\nminikube tunnel\n\nsudo systemctl start tinyproxy\n\n# Test tinyproxy -\u003e minikube -\u003e service -\u003e pod\ncurl http://127.0.0.1:8081/api/v1/health\n```\n\n## Built With\n\n- [Kubernetes](https://kubernetes.io) - Container orchestration platform\n- [Helm](https://helm.sh) - Manages Kubernetes deployments\n- [Docker](https://docker.io/) - Container build tool\n- [Steam](https://steam.com) - CLI used to install Valheim dedicated server\n\n## Contributing\n\nPlease read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code\nof conduct, and the process for submitting pull requests to us.\n\n## Versioning\n\nWe use [Semantic Versioning](http://semver.org/) for versioning. For the versions\navailable, see the [tags on this\nrepository](https://github.com/cbartran/hearthhub-mod-api/tags).\n\n## Authors\n\n- **cbartram** - *Initial work* - [cbartram](https://github.com/cbartram)\n\n## License\n\nThis project is licensed under the [CC0 1.0 Universal](LICENSE)\nCreative Commons License - see the [LICENSE.md](LICENSE) file for\ndetails\n\n[contributors-shield]: https://img.shields.io/github/contributors/cbartram/hearthhub-kube-api.svg?style=for-the-badge\n[contributors-url]: https://github.com/cbartram/hearthhub-kube-api/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/cbartram/hearthhub-kube-api.svg?style=for-the-badge\n[forks-url]: https://github.com/cbartram/hearthhub-kube-api/network/members\n[stars-shield]: https://img.shields.io/github/stars/cbartram/hearthhub-kube-api.svg?style=for-the-badge\n[stars-url]: https://github.com/cbartram/hearthhub-kube-api/stargazers\n[issues-shield]: https://img.shields.io/github/issues/cbartram/hearthhub-kube-api.svg?style=for-the-badge\n[issues-url]: https://github.com/cbartram/hearthhub-kube-api/issues\n[license-shield]: https://img.shields.io/github/license/cbartram/hearthhub-kube-api.svg?style=for-the-badge\n[license-url]: https://github.com/cbartram/hearthhub-kube-api/blob/master/LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbartram%2Fhearthhub-kube-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcbartram%2Fhearthhub-kube-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcbartram%2Fhearthhub-kube-api/lists"}