{"id":47660355,"url":"https://github.com/jevzo/ogcloud","last_synced_at":"2026-04-02T11:01:12.346Z","repository":{"id":343114206,"uuid":"1169996349","full_name":"Jevzo/ogcloud","owner":"Jevzo","description":"Run Minecraft networks like real cloud infrastructure. OgCloud provisions servers on demand, scales automatically, routes players intelligently, and gives you a full control plane with API, plugins, and dashboard.","archived":false,"fork":false,"pushed_at":"2026-03-24T01:53:34.000Z","size":7805,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-24T19:47:12.933Z","etag":null,"topics":["cloud","kotlin","kubernetes","loadbalancer","minecraft","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jevzo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["Jevzo"]}},"created_at":"2026-03-01T14:50:52.000Z","updated_at":"2026-03-24T00:11:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Jevzo/ogcloud","commit_stats":null,"previous_names":["jevzo/ogcloud"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/Jevzo/ogcloud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jevzo%2Fogcloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jevzo%2Fogcloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jevzo%2Fogcloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jevzo%2Fogcloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jevzo","download_url":"https://codeload.github.com/Jevzo/ogcloud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jevzo%2Fogcloud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31304988,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T09:48:21.550Z","status":"ssl_error","status_checked_at":"2026-04-02T09:48:19.196Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["cloud","kotlin","kubernetes","loadbalancer","minecraft","spring-boot"],"created_at":"2026-04-02T11:00:30.074Z","updated_at":"2026-04-02T11:01:12.340Z","avatar_url":"https://github.com/Jevzo.png","language":"TypeScript","funding_links":["https://github.com/sponsors/Jevzo"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/images/logo.webp\" alt=\"OgCloud Logo\" width=\"220\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e:cloud: Kubernetes-native infrastructure for running Minecraft networks.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e:rocket: Provision servers on demand. :globe_with_meridians: Route players intelligently. :hammer_and_wrench: Manage your whole network from one control plane.\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Kubernetes\" src=\"https://img.shields.io/badge/Kubernetes-Native-326CE5?style=for-the-badge\u0026logo=kubernetes\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"Spring\" src=\"https://img.shields.io/badge/Spring%20%2B%20Kotlin-Control%20Plane-6DB33F?style=for-the-badge\u0026logo=spring\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"Go\" src=\"https://img.shields.io/badge/Go-Load%20Balancer-00ADD8?style=for-the-badge\u0026logo=go\u0026logoColor=white\" /\u003e\n\u003c/p\u003e\n\n---\n\n## :brain: What We Are\n\nOgCloud is a Kubernetes-native control plane for Minecraft networks.\n\nIt gives you one platform for:\n\n- :globe_with_meridians: network ingress and TCP routing\n- :video_game: proxy and backend server lifecycle\n- :chart_with_upwards_trend: autoscaling and maintenance workflows\n- :package: templates and backing services\n- :desktop_computer: dashboard + API operations\n- :electric_plug: plugin-level integration APIs\n\nRepository: https://github.com/Jevzo/ogcloud\n\n## :test_tube: Development Status\n\nOgCloud is still actively in development.\n\nCurrent status: **beta and production-ready** for teams comfortable with Kubernetes operations and iterative releases.\n\nPlanned roadmap: support multiple Minecraft versions in a single cluster through protocol-based routing at the load\nbalancer, with plugin-side translation.\n\n## :bulb: Why OgCloud\n\n- :white_check_mark: Replace hand-maintained server fleets with managed lifecycle automation.\n- :white_check_mark: Scale by group rules and player demand, not guesswork.\n- :white_check_mark: Keep gameplay plugins connected to live cloud state.\n- :white_check_mark: Update API/controller/loadbalancer/dashboard independently.\n- :white_check_mark: Use one platform model from local testing to production clusters.\n\n## :crossed_swords: Why The Alternatives Lose\n\nPractical version: most stacks in this space still fall into one of three buckets:\n- legacy host-first architecture,\n- infrastructure primitives sold as a complete platform,\n- or process orchestration with modern branding on top.\n\nOgCloud wins from a controller + API + load balancer perspective because it is built as a real control-plane stack:\n\n- :white_check_mark: Controller lifecycle behavior for scale, churn, and failure handling (not start/stop scripts).\n- :white_check_mark: Full operational API surface for scriptable, observable network operations.\n- :white_check_mark: Dedicated Minecraft-aware ingress with proxy heartbeat tracking and clean drain behavior.\n- :white_check_mark: Kubernetes-native deployment workflows with Helm and setup automation.\n\nCompetitor reality check:\n\n- **PoloCloud**: promising, but still feels like a moving target and adds platform overhead before operational confidence.\n- **CloudNet**: historically important, but still rooted in node-centric, host-first architecture from an older era.\n- **Shulker**: technically strong, but closer to a substrate than a complete opinionated platform; teams still assemble too much themselves.\n- **SimpleCloud**: calls itself \"simply the best\" but their own positioning admits Kubernetes is \"not possible right now\" and the Docker push stalled out. That is legacy process management with cloud branding.\n\nFor serious Minecraft networks, the gap is clear: OgCloud is built as a modern control plane, while most alternatives are either legacy models or incomplete platform stories.\n\n## :sparkles: Feature List\n\n- :wheel_of_dharma: Kubernetes-native architecture for Minecraft workloads\n- :compass: Dedicated Minecraft-protocol-aware load balancer\n- :robot: Controller-driven autoscaling and server orchestration\n- :computer: Dashboard + REST API for network operations\n- :card_index_dividers: Template storage and distribution flow\n- :mailbox_with_mail: Kafka + Redis + MongoDB integration\n- :electric_plug: Paper and Velocity plugin APIs\n- :bricks: Helm charts split by concern: infra, platform, dashboard\n- :motorway: Planned: multi-version network support (single cluster, protocol-aware routing + plugin translation)\n\n---\n\n## :zap: Quick Install Guide\n\n### :white_check_mark: Prerequisites\n\n- `kubectl` configured for your target cluster\n- `helm`\n- Node.js 18+ (`npm` / `npx`)\n\n### :rocket: Fastest Path (Recommended)\n\nIf you want the easiest setup: this is it.\nSpin up the wizard, answer a few prompts, and you are deploying in minutes.\n\n```bash\nnpx @ogcloud/setup\n```\n\n### :compass: Straight Command Path\n\n```bash\nnpx @ogcloud/setup --generate-config ogwars\nnpx @ogcloud/setup --deploy ogwars\n```\n\n### :toolbox: Common Commands\n\n```bash\nnpx @ogcloud/setup --generate-config \u003cnetwork\u003e\nnpx @ogcloud/setup --deploy \u003cnetwork\u003e\nnpx @ogcloud/setup --deploy \u003cnetwork\u003e --without-backing\nnpx @ogcloud/setup --update \u003cnetwork\u003e \u003cdashboard|api|loadbalancer|controller\u003e \u003ctag\u003e\nnpx @ogcloud/setup --destroy \u003cnetwork\u003e\n```\n\n### :file_cabinet: Generated Local State\n\n- `~/.ogcloud-setup/state.json`\n- `~/.ogcloud-setup/networks/\u003cnetwork\u003e/values.infra.yaml`\n- `~/.ogcloud-setup/networks/\u003cnetwork\u003e/values.platform.yaml`\n- `~/.ogcloud-setup/networks/\u003cnetwork\u003e/values.dashboard.yaml`\n\n---\n\n## :earth_africa: Public Endpoints\n\nA typical OgCloud deployment exposes:\n\n- `mc.yourserver.io` -\u003e Minecraft ingress through OgCloud load balancer\n- `https://api.yourserver.io` -\u003e control-plane API\n- `https://dashboard.yourserver.io` -\u003e admin dashboard\n\n---\n\n## :electric_plug: Plugin APIs\n\nOgCloud exposes APIs for both Paper and Velocity plugins.\n\nUse these artifacts as `compileOnly` or `provided` dependencies in your plugin. The OgCloud Paper or Velocity plugin\nprovides the runtime classes on the server.\n\nGitHub Packages still requires authentication for Gradle and Maven downloads. Configure `gpr.user` and `gpr.key` in\nyour Gradle properties or export `GITHUB_ACTOR` and `GITHUB_TOKEN`.\n\n### Gradle Repository\n\n```kotlin\nrepositories {\n    maven {\n        url = uri(\"https://maven.pkg.github.com/jevzo/ogcloud\")\n        credentials {\n            username = project.findProperty(\"gpr.user\") as String? ?: System.getenv(\"GITHUB_ACTOR\")\n            password = project.findProperty(\"gpr.key\") as String? ?: System.getenv(\"GITHUB_TOKEN\")\n        }\n    }\n}\n```\n\n### Paper Dependency\n\n```kotlin\ndependencies {\n    compileOnly(\"io.ogwars.cloud:ogcloud-paper-plugin:LATEST_VERSION\")\n}\n```\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.ogwars.cloud\u003c/groupId\u003e\n  \u003cartifactId\u003eogcloud-paper-plugin\u003c/artifactId\u003e\n  \u003cversion\u003eLATEST_VERSION\u003c/version\u003e\n  \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n\n### Velocity Dependency\n\n```kotlin\ndependencies {\n    compileOnly(\"io.ogwars.cloud:ogcloud-velocity-plugin:LATEST_VERSION\")\n}\n```\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.ogwars.cloud\u003c/groupId\u003e\n  \u003cartifactId\u003eogcloud-velocity-plugin\u003c/artifactId\u003e\n  \u003cversion\u003eLATEST_VERSION\u003c/version\u003e\n  \u003cscope\u003eprovided\u003c/scope\u003e\n\u003c/dependency\u003e\n```\n\n### Paper Example: Lobby Switcher Using `getPlayerGroup`\n\nThis routes players to a different lobby group depending on their resolved permission group.\n\n```kotlin\nclass LobbyCommand : CommandExecutor {\n    override fun onCommand(sender: CommandSender, command: Command, label: String, args: Array\u003cout String\u003e): Boolean {\n        val player = sender as? Player ?: return true\n        val cloud = OgCloudServerAPI.get()\n\n        val permissionGroup = cloud.getPlayerGroup(player.uniqueId)\n        val targetLobbyGroup = if (permissionGroup?.name.equals(\"staff\", ignoreCase = true)) {\n            \"staff-lobby\"\n        } else {\n            \"lobby\"\n        }\n\n        cloud.transferPlayerToGroup(player.uniqueId, targetLobbyGroup)\n            .thenRun { player.sendMessage(\"Sending you to $targetLobbyGroup...\") }\n            .exceptionally {\n                player.sendMessage(\"Failed to switch lobby.\")\n                null\n            }\n\n        return true\n    }\n}\n```\n\n### Paper Example: Match Flow + Warm Spare Request\n\n```kotlin\nval cloud = OgCloudServerAPI.get()\n\ncloud.setGameState(GameState.INGAME)\n\ncloud.requestServer(\"minigame\").thenAccept { serverInfo -\u003e\n    logger.info(\"Warm spare requested: {} in group {}\", serverInfo.id, serverInfo.group)\n}\n```\n\n### Velocity Example: Route On Join With `getPlayerGroup`\n\n```kotlin\nclass AutoRouteListener {\n    @Subscribe\n    fun onJoin(event: PostLoginEvent) {\n        val player = event.player\n        val cloud = OgCloudProxyAPI.get()\n\n        val playerGroup = cloud.getPlayerGroup(player.uniqueId)\n        val destinationGroup = if (playerGroup?.name.equals(\"vip\", ignoreCase = true)) {\n            \"vip-lobby\"\n        } else {\n            \"lobby\"\n        }\n\n        cloud.transferPlayerToGroup(player.uniqueId, destinationGroup)\n            .exceptionally {\n                logger.error(\"Failed to route {} to {}\", player.username, destinationGroup, it)\n                null\n            }\n    }\n}\n```\n\n---\n\n## :sos: Discord And Help\n\n- Community and support: **[OgCloud | Support and Development](https://discord.gg/pE9gCBm822)**\n- Source and issues: https://github.com/Jevzo/ogcloud\n\n---\n\n## :heart: Sponsoring\n\nIf OgCloud helps your network, sponsoring supports faster development and support capacity.\n\n- [GitHub Sponsors](https://github.com/sponsors/Jevzo)\n\n---\n\n## :hammer_and_wrench: Local Development\n\nFrom repo root:\n\n```powershell\n.\\build.ps1 api\n.\\build.ps1 controller\n.\\build.ps1 dashboard\n```\n\nDocker build + push examples:\n\n```powershell\n.\\build.ps1 docker api -p\n.\\build.ps1 docker controller -p\n.\\build.ps1 docker loadbalancer -p\n.\\build.ps1 docker dashboard -p\n```\n\n---\n\n## :package: Publish `@ogcloud/setup`\n\n```bash\ncd helper/ogcloud-setup-cli\nnpm install\nnpm run build\nnpm version patch\nnpm publish --access public\n```\n\nAfter publish:\n\n```bash\nnpx @ogcloud/setup\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjevzo%2Fogcloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjevzo%2Fogcloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjevzo%2Fogcloud/lists"}