{"id":23134906,"url":"https://github.com/4players/fleet-sdk-nodejs","last_synced_at":"2025-04-04T08:22:17.772Z","repository":{"id":247952807,"uuid":"826694231","full_name":"4Players/fleet-sdk-nodejs","owner":"4Players","description":"This is the Node.js SDK designed to interact with the Fleet REST API, enabling developers to manage game servers efficiently. This SDK leverages the robust and scalable solutions offered by ODIN Fleet, making it easier to deploy and manage game servers across a global network.","archived":false,"fork":false,"pushed_at":"2025-03-04T17:54:51.000Z","size":52,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-04T18:37:31.821Z","etag":null,"topics":["cloud","deployment","fleet-client-library","fleet-management","gameserver","hosting","odin"],"latest_commit_sha":null,"homepage":"https://4players.io/products/fleet","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/4Players.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2024-07-10T07:42:27.000Z","updated_at":"2025-03-04T17:54:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"90f758fc-4b35-4bfd-ad15-07f4e4934738","html_url":"https://github.com/4Players/fleet-sdk-nodejs","commit_stats":null,"previous_names":["4players/fleet-sdk-nodejs"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4Players%2Ffleet-sdk-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4Players%2Ffleet-sdk-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4Players%2Ffleet-sdk-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/4Players%2Ffleet-sdk-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/4Players","download_url":"https://codeload.github.com/4Players/fleet-sdk-nodejs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247142789,"owners_count":20890791,"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":["cloud","deployment","fleet-client-library","fleet-management","gameserver","hosting","odin"],"created_at":"2024-12-17T12:13:38.860Z","updated_at":"2025-04-04T08:22:17.761Z","avatar_url":"https://github.com/4Players.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ODIN Fleet SDK for Node.js\n\n## Overview\n\nThis is the Node.js SDK designed to interact with the [ODIN Fleet REST API](https://docs.4players.io/fleet/api/restapi/), enabling developers to manage game servers efficiently. This SDK leverages the robust and scalable solutions offered by [ODIN Fleet](https://odin.4players.io/fleet/), making it easier to deploy and manage game servers across a global network.\nYou can find further technical information on **ODIN Fleet** in our [developer documentation](https://docs.4players.io/fleet/).\n\n## Features\n\n- **Server Management**: Create, configure, deploy, and autoscale game servers.\n- **CI/CD Integration**: Seamlessly integrate into CI/CD pipelines for automated server management.\n- **Cross-Platform Support**: Compatible with various game engines and platforms.\n- **Real-Time Scaling**: Dynamically adjust the number of servers based on demand.\n- **User-Friendly Interface**: Simple API, dashboard, and CLI for easy server management.\n- **Security**: Built-in DDoS protection and GDPR/DSGVO compliance.\n\n## Installation\n\nInstall the SDK using npm:\n\n```bash\nnpm install @4players/fleet-nodejs\n```\n\n## Usage\n\n### Initialization\n\nFirst, import and initialize the `FleetApiClient` with your API key:\n\n```javascript\nconst FleetApiClient = require('@4players/fleet-nodejs');\n\nconst client = new FleetApiClient(\"__YOUR_ACCESS_TOKEN__\");\n```\n\nIn TypeScript, you can import the SDK as follows:\n\n```typescript\nimport { FleetApiClient } from '@4players/fleet-nodejs';\nconst client = new FleetApiClient(\"__YOUR_ACCESS_TOKEN__\");\n```\n\n## Dashboard\n\nUsing our dashboard is an easy way of managing your game servers and applications. It's also a good way to see which\nitems are created by the examples and how they are structured.\n\nYou'll find the dashboard at [https://console.4players.io](https://console.4players.io). All you need is a 4Players account\nwhich you can also create on the dashboard. \n\n## Next Steps\n\nThe following examples demonstrate how to use the FleetApiClient SDK to manage game servers using the Fleet API.\n\n### Example: Deploying a Minecraft Server\n\nDepending on your business model you typically have your own docker image or have server binaries in Steam, but in this case we'll use an existing Minecraft Docker image to deploy a Minecraft server.\n\nAlthough you can create an App via Script, it's easier to understand and to follow if we create the app in the dashboard as\nwe need an API key for the script to work, so let's create an app in the dashboard.\n\nNavigate to the dashboard and create a new app. You can name it whatever you want, but for this example we'll name it `Minecraft`.\nOnce you have created the App, you'll be routed to the apps dashboard where the App-ID is displayed. You'll need this ID for the script.\nClick on the Copy button to copy the App-ID to your clipboard.\n\nLet's start with the initial part of the script:\n\n```typescript\nimport { FleetApiClient } from '@4players/fleet-nodejs';\n\nvar appId = __YOUR_APP_ID__;\n```\n\nNext, click on \"Settings\" on the left sidebar and choose \"API-Keys\" from the list. You'll see your personal\nAccess Token. Click the copy icon again and paste it into the script.\n\n```typescript\nimport { FleetApiClient } from '@4players/fleet-nodejs';\n\n// Setup the client\nvar appId = __YOUR_APP_ID__;\nvar accessToken = \"__YOUR_ACCESS_TOKEN__\";\nvar client = new FleetApiClient(accessToken);\n\n// Select our app so we don't need to provide the app id for every request\nclient.selectAppId(appId);\n```\n\nNow we need to create an image. We'll use the Minecraft image from the Docker Hub. You can find the image [here](https://hub.docker.com/r/itzg/minecraft-server).\n\n```typescript\nconst version = '2024.6.1';\n\n// We need to load the available docker registries to get the id of the default (docker hub) docker registry\nlet dockerRegistry: DockerRegistry = await client.getDockerRegistries().then((registries) =\u003e {\n  return registries.find((registry) =\u003e registry.type === 'default');\n});\n\n// Setup the payload for the binary\nconst payload = {\n  name: 'Minecraft',\n  version: version,\n  type: BinaryType.DockerImage,\n  os: OperatingSystem.Linux,\n  appId: app.id,\n  dockerImage: {\n    imageName: `itzg/minecraft-server:${version}`,\n    registryId: dockerRegistry.id,\n  },\n};\n\n// Create the binary structure within ODIN Fleet - this image will later be deployed\nlet binary = null;\ntry {\n  binary = await client.createBinary(payload);  \n} catch (error) {\n  console.error('Error creating binary:', error);\n  process.exit(0);\n}\n```\n\nNext, we'll need to create a server config. A server config is a blueprint for a server. It defines the image, required resources, persistence, and other settings.\nThis is a bit more complex and it might be helpful to play around with the dashboard to understand the structure of the server config.\n\nAs with most docker images, they are configured via environment variables. Which environment variables are available\nis defined in the Dockerfile. In this case, we'll set the EULA to true, the server name to \"ODIN Fleet\", the MOTD to \"Welcome to our ODIN Fleet Minecraft Server\", the max players to 10, and disable the snooper.\n\nYou'll find more info in these variables [here](https://docker-minecraft-server.readthedocs.io/en/latest/variables/).\n\n```typescript\nlet config = null;\ntry {\n  config = await client.createServerConfig({\n    name: `Minecraft Production ${version}`,\n    binaryId: binary.id,  // We'll use the binary we just created\n      resources: {          // This defines resources, 1 shared CPU and 2 GB of memory are enough\n        limits: {\n          cpu: 1,\n          memory: 2,\n        },\n        reservations: {\n          cpu: 0,\n          memory: 0,\n        },\n      },\n      restartPolicy: {\n        condition: RestartPolicyCondition.Any,\n      },\n      mounts: [\n        {\n          target: '/data',    // This is where the server stores its data and we want to make sure it's backuped\n          readOnly: false,\n        },\n      ],\n      ports: [                // We need to expose the game port and tell the system that it's a TCP port\n        {\n          name: 'gamePort',\n          targetPort: 25565,\n          protocols: [Protocol.Tcp],\n          publishMode: PublishMode.Ingress,\n        },\n      ],\n      env: [                  // These are the environment variables (EULA is required). You can play around with different values\n        {\n          key: 'EULA',\n          type: EnvironmentVariableType.Static,\n          value: 'true',\n        },\n        {\n          key: 'SERVER_NAME',\n          type: EnvironmentVariableType.Static,\n          value: 'ODIN Fleet',\n        },\n        {\n          key: 'MOTD',\n          type: EnvironmentVariableType.Static,\n          value: 'Welcome to our ODIN Fleet Minecraft Server',\n        },\n        {\n          key: 'MAX_PLAYERS',\n          type: EnvironmentVariableType.Static,\n          value: '10',\n        },\n        {\n          key: 'SNOOPER_ENABLED',\n          type: EnvironmentVariableType.Static,\n          value: 'false',\n        },\n      ],\n    });\n} catch (error) {\n  console.error('Error creating server config:', error);\n  process.exit(0);\n}\n```\n\nNow we can deploy the server. We'll deploy 1 server in this example. We'll use the german region to deploy it.\n\n```typescript\n// Find first location in Germany\nconst location = await client.getLocations().then(({data}) =\u003e {\n  return data.find((location) =\u003e location.country === 'de');\n});\n\nif (!location) {\n  throw new Error('Location not found');\n  process.exit(0);\n}\n\nlet deployment = null;\ntry {\n  deployment = await client.createDeployment({\n    name: 'Minecraft Production',\n    serverConfigId: config.id,\n    autoScalerEnabled: false,\n    numInstances: 1,\n    placement: {\n      constraints: {\n        country: location.country,\n        city: location.city,\n      },\n    },\n  });\n} catch (error) {\n  console.error('Error creating deployment:', error);\n  process.exit(0);\n}\n```\n\nThat's it. You should now have a Minecraft server running in the german region. You can now connect to it using the IP address of the server.\n\nMake sure to delete the deployment and the server config if you don't need them anymore. You can also delete the binary if you don't need it anymore.\n\nYou'll find a list of deployed servers in the dashboard under \"Servers\". \n\n## Getting a servers IP and Port\n\nWhen you create a server config you define which ports need to be routed to the internet. In the above server config we created a port definition named \"Game Port\" and defining a TCP port at 25565. Our system will find a free port on the maschine and will route that port to the internal port where the gameserver is listening. \nTo find out which port is used you can get the server details:\n\n```typescript\nconst servers = await client.getServers();\nfor (let server of servers) {\n  // The server.ports map contains all ports that are exposed to the internet named by the port definition name\n  var gamePort = server.ports[\"Game Port\"]?.publishedPort;\n  var ip = server.addr;\n  \n  console.log(`Server ${server.id} is available at ${ip}:${gamePort}`);\n}\n```\n\n## Development\n\nWe are using OpenAPI to document our APIs and use generators to automatically build client code. However, as these generators have their weaknesses, we create a custom wrapper around the generated code to make it more user-friendly. In this case it's the `FleetApiClient`. You can update the internal code by running the following command:\n\n```bash\nnpm run generate-api-from-backend\n```\n\nThis will download the current API specs from the backend and generate the client code. Typically some minor changes or additions are then required to `FleetApiClient`.\n\n## API Documentation\n\nThe full API documentation is available in the OpenAPI specs: [Fleet API Documentation](https://docs.4players.io/fleet/api/).\n\n## Support\n\nFor additional support, get in touch on our [Discord server](https://4np.de/discord). \n\n[Book a meeting](https://www.4players.io/company/contact_us/) or join a live presentation to learn more about ODIN Fleet and how it can help manage your game servers efficiently.\n\n## License\n\nThe NodeJS SDK is MIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4players%2Ffleet-sdk-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F4players%2Ffleet-sdk-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F4players%2Ffleet-sdk-nodejs/lists"}