{"id":13658944,"url":"https://github.com/SoftwareGuy/NodeListServer","last_synced_at":"2025-04-24T11:33:08.847Z","repository":{"id":38093577,"uuid":"233792259","full_name":"SoftwareGuy/NodeListServer","owner":"SoftwareGuy","description":"Node List Server is a multi-purpose server list system. NodeJS powered and supports Docker.","archived":false,"fork":false,"pushed_at":"2023-07-19T18:33:50.000Z","size":214,"stargazers_count":92,"open_issues_count":5,"forks_count":33,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-11-10T12:42:59.658Z","etag":null,"topics":["docker","linux","mirror","multiplayer","nodejs","server-list","unity"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/SoftwareGuy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":"FUNDING.yml","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},"funding":{"ko_fi":"coburn","patreon":"Oiran_Studio","custom":["https://www.paypal.com/paypalme/coburn64"]}},"created_at":"2020-01-14T08:23:43.000Z","updated_at":"2024-09-27T02:21:53.000Z","dependencies_parsed_at":"2024-04-09T17:57:32.537Z","dependency_job_id":"cb792a5d-b53b-4c2a-a1d9-4f9376adb72d","html_url":"https://github.com/SoftwareGuy/NodeListServer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftwareGuy%2FNodeListServer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftwareGuy%2FNodeListServer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftwareGuy%2FNodeListServer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SoftwareGuy%2FNodeListServer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SoftwareGuy","download_url":"https://codeload.github.com/SoftwareGuy/NodeListServer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250618793,"owners_count":21460156,"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":["docker","linux","mirror","multiplayer","nodejs","server-list","unity"],"created_at":"2024-08-02T05:01:03.980Z","updated_at":"2025-04-24T11:33:08.556Z","avatar_url":"https://github.com/SoftwareGuy.png","language":"JavaScript","funding_links":["https://ko-fi.com/coburn","https://patreon.com/Oiran_Studio","https://www.paypal.com/paypalme/coburn64","https://paypal.me/coburn64"],"categories":["JavaScript"],"sub_categories":[],"readme":"# NodeListServer Generation 2.1\n\n![MIT Licensed](https://img.shields.io/badge/license-MIT-green.svg)\n[![Ko-Fi](https://img.shields.io/badge/Donate-Ko--Fi-red)](https://ko-fi.com/coburn) \n[![PayPal](https://img.shields.io/badge/Donate-PayPal-blue)](https://paypal.me/coburn64)\n\nNodeLS, short for Node List Server, is a game server directory application that aims to provide a reliable way of registering, deregistering and informing clients of servers available for your game(s).\n\n## Why NodeLS?\n\nWhen developing a game, let's say a First Person Shooter, you might want to have clients host their own servers. These servers might be \nhost-client (\"listen\") or pure dedicated instances. However, here comes the next problem...\n\nHow the heck do you display servers that are available for you to join?\n\nEnter NodeLS. It's a flexible and open source server listing system that works with pretty much any software that can understand JSON. NodeLS also brings you \nassurance that you control the data that is being sent and received, not a third party other than the server provider you deal with.\n\n_**Please consider a donation (see the Ko-Fi button above) if this server software is useful to you.**_\n\n## Support Update\nWhile issue tickets are the preferred way of support, you may also ask for support on the [Oiran Studio Discord](https://discord.gg/kUvJYjrbHE). It may be a faster way of getting support if I'm not busy with other client tasks. Sometimes issue ticket notifications get snowed under a truck load of new email.\n\n## Features\n\n-   **Fast:** We use NodeJS to power this baby.\n-   **OSS Core:** Feel free to tailor it to your needs, it's open source. Find a bug? Fix it, shoot me a PR, let me review and if it looks good, congrats!\n-   **Game Engine Agnostic:** Thanks to the HTTP API, any engine that can do HTTP requests can take advantage of NodeLS.\n-   **WebGL compatible:** No complex magic required. NodeLS uses a simple API to query, add and remove servers. \n-   **Secure:** ACLs (Access Control Lists) can be used as well as key authenication to prevent anyone adding/removing servers from your instances. Servers must provide a key in order to register, and rate limiting clients helps keep traffic floods at bay.\n-   **Configurable:** Hard-coded options are kept to a minimum, allowing greater flexibility.\n\n## Non-Features\n\n-   **Matchmaking:** Outside the realm that this program sits in.\n-   Anything else that it doesn't offer.\n\n## Bug Fixes, New Features, etc\n\n-   **Found a bug?** Please report it via the Issues ticket system. If you ***think that you can fix it*** then give it a shot. I'd really appreciate a pull request!\n-   **Refactors, Improvements, Tweaks:** Improvements and refinements are welcome - open a issue and suggest your modifications or fork this project, improve it, then shoot in a PR.\n-   **Ooh, shiny new feature:** New features are carefully considered. NodeLS tries not to be a bloated end product, but some features are nice to have...\n\n## Setup\n\n### Docker Support\n\n***TODO: Review docker support and update it***\n\nIf you want to have everything handled for you and you're running a linux server, see [the Docker support documentation](DOCKER-SUPPORT.md) file for more info. Please note that this will require some additional setup.\n\n### Requirements\n\n1.  Node 16 or newer (most recent LTS is recommended)\n2.  A server instance, be it Windows or Linux\n3.  Some knowledge about programming, fair amount of patience and Git-fu\n\n**Make sure your installation of Node is functional before continuing!**\n\n## Installation\n\n### Git Clone Method\n1.    Run this in the console of your operating system where you want the code to be placed (for example, `C:\\NodeListServer`).\n```\ngit clone https://github.com/SoftwareGuy/NodeListServer .\n```\n\nNOTE: It is possible to use a GUI such as Git GUI or SourceTree. Use whatever you're familiar with.\n\n2. Continue with configuration step below.\n\n### ZIP Installation Method\n\n1.  Obtain a ZIP archive of this repository via the \"Download as ZIP\" option.\n2.  Extract it somewhere on your system.\n\n**Note: The ZIP Installation Method loses the git metadata, so you will not be able to have easy updates.**\n\n## Configuration\n\n***TODO: Update this***\n\n1. Open `lib/config.js`.\n2. Carefully make any adjustments to the configuration as desired (see [the configuration page](CONFIGURATION.md) for more information).\n3. Save and Exit. Re-upload your modified `config.js` (ie. you edited it via FTP).\n\n## Operating \u0026 Updating\n\n*Note: It's recommended to use a process manager like **PM2** which will allow you start and stop the server elegantly, and restart it in case of crashes, etc.*\n\n### Starting \u0026 Stopping\n\n**First Run:**\n1.  Install the Node modules by issuing `npm install --only=production`. This will read the requirements from packages.json.\n\n**To start the server:**\n\n_Protip: Check to see if the port is open that you want NodeListServer to listen on. **You cannot have more than one list server listening on the same port number.**_\n\n1.  Start the server using `npm start` or `node init`. \n2.  Observe the logs that are printed to the console, if the list server does not say anything then something went wrong. A successful startup is as follows:\n\n```\nNodeListServer Gen2: Mirror List Server reimplemented in NodeJS\nReport bugs and fork me on GitHub: https://github.com/SoftwareGuy/NodeListServer\nListening on HTTP port 8889!\n```\n\n3.  Issue a HTTP POST command like the following to `http://[your-server-ip]:8889/list`. cURL is very useful as a debug tool, so here's a one liner. Replace `NodeListServerDefaultKey` with your changed key if you changed that.\n\n```\ncurl -X POST -d \"serverKey=NodeListServerDefaultKey\" http://127.0.0.1:8889/list\n```\n\nIf all goes well, you should get some JSON as a result. If you don't, or you get `Bad Request` then check what the console says - you dun goofed probably.\n\n**To stop the server:**\n\nSimply CTRL+C the running Node process, or you can use `kill`/`pkill` to kill the node instance. I'd recommend using `ps aux` and `kill \u003cpid\u003e` carefully, because `pkill node` would try to kill all node instances on your box - and that can be really no bueno.\n\n### Updating NodeListServer\n\n1.  Stop NodeListServer if it's running.\n2.  Execute `git pull` from the repository you cloned to your local machine or server instance. \n    -   Note that if you obtained the source via a ZIP archive, then you're not going to be able to just execute `git pull`. Download and extract a new ZIP archive of this repository instead.\n3.  New commits will update your installation of NodeListServer after running `git pull`.\n    -   Rectify any pull merge errors if you have any (and you should know how to do this).\n4.  Start NodeListServer again.\n\n## The API Explained\n\nSection omitted because it needs cleanup. Check back later.\n\n## Using NodeListServer with Unity\n\nWant a easy, ready to go project? Then grab a copy of the  [NodeListServer-Example](https://github.com/SoftwareGuy/NodeListServer-Example) repository.\n\nIn fairness, It's pretty easy to use NodeListServer with Unity. You can use UnityWebRequest or another library (ie. Best HTTP Pro) to fetch the server lists and issue add/remove commands. As long as you can decode JSON it returns for the server list, you should be fine.\n\nImportant: Do **NOT** auto-assume that POST functions will be successful. **Always check the HTTP status code before doing anything with the returned response**. \n\n-   You will get HTTP code 200 with a \"OK\" response from NodeListServer on success. \n-   Anything not HTTP code 200 will be NodeListServer denying your request (you'll most likely get HTTP Code 400, Bad Request or if your IP is blocked, 403 Forbidden).\n-   Make sure you cache the Server UUID you use. You'll need to use that to tell the List Server what to do with your server entry. Without a valid Server UUID, it will refuse to do anything.\n-   I strongly recommend using GUIDs, which are unique and if you're using Mono or .NET, you can just use `System.Guid.newGuid()` to generate a random one.\n\nAs a bonus, here's some generic serializable classes that you can use to translate the JSON into something more usable:\n\n```csharp\n\n[Serializable]\npublic class ServerListResponse\n{\n    // Number of known servers.\n    public int count;\n    // The container for the known servers.\n    public List\u003cServerListEntry\u003e servers;\n    // Ideally used for client-hosted games, tells you how often you should refresh your server information.\n    public int updateFrequency;\n}\n\n[Serializable]\npublic class ServerListEntry\n{\n\t// Random generated UUID\n\tpublic string serverUuid; \n\t// IP address. Beware: Might be IPv6 format, and require you to chop off the leading \"::ffff:\" part. YMMV.\n\tpublic string ip;\n\t// Port of the server.\n\tpublic int serverPort;\n\t// Name of the server.\n\tpublic string serverName;\n\t// Number of players on the server.\n\tpublic int serverPlayers;\n\t// The number of players maximum allowed on the server.\n\tpublic int serverCapacity;\n\t// Extra data.\n\tpublic string extras;\n}\n```\n\nMake sure you POST the correct data when you want to add/remove servers. See API Endpoints for more details on the required POST fields.\n\n## Credits\n\n- vis2k: Mirror Networking and the original List Server\n-\tJesusLuvsYooh: That other blacksmith that's forging NodeLS into shape and always annoying me with questions\n-\tAnthonyE: First actual deployment of NodeLS in production!\n- Mirror Team \u0026 Discord Members\n\n\n***Thank you for choosing Australian Open Source Software.***\n\n\n\n\u003ch1\u003e NodeLS Basic server Instructions:- \u003c/h1\u003e\n \n- First of all make sure you have Nodejs downloaded and Installed\n- Open Folder through VSCode\n- run ``` npm install ``` to install dependencies \n- run ``` node listServer.js ``` to start your NodeLS server  \n\n\u003c/hr\u003e\n\n\u003ch1\u003eAPI Quickstart Instructions:-\u003c/h1\u003e\n\u003ch3\u003e Firing Up NodeLS Using PostMan : \u003c/h3\u003e\n\n1) POST - http://127.0.0.1:8889/add - x-WWW-FORM \u003c/br\u003e\n\u003cpre\u003e\u003ccode class=\"hljs language-shell\"\u003e\n    ip =\u003e ip addres of the node\n    serverKey =\u003e NodeListServerDefaultKey (specified in the Configuration file)\n    serverName =\u003e Lulu\n    serverPort =\u003e 7777 \n    serverPlayers =\u003e 2 (optional)\n    serverCapacity =\u003e 20 (optional)\n\u003c/code\u003e\u003c/pre\u003e\n\n\n*Congratulations! you now have ~ serverUuid || \"uuid\" ~~ of the created server called \"Lulu\"* !!\n\n\u003c/hr\u003e\n\n2) POST - http://127.0.0.1:8889/list - x-WWW-FORM \u003c/br\u003e\n\u003cpre\u003e\u003ccode class=\"hljs language-shell\"\u003e\nserverKey =\u003e NodeListServerDefaultKey (specified in the Configuration file)\n\u003c/code\u003e\u003c/pre\u003e\n\n* Now you have list of created servers as the following...*\n\n\u003cpre\u003e\u003ccode class=\"hljs language-shell\"\u003e\n\"Example callback\" =\u003e {\n    \"count\": 2,\n    \"servers\": [\n        {\n            \"ip\": \"::ffff:127.0.0.1\",\n            \"name\": \"Lulu\",\n            \"port\": 7777,\n            \"players\": 0,\n            \"capacity\": 0,\n            \"extras\": \"\"\n        },\n        {\n            \"ip\": \"::ffff:127.0.0.1\",\n            \"name\": \"Lulus\",\n            \"port\": 7337,\n            \"players\": 2,\n            \"capacity\": 20,\n            \"extras\": \"\"\n        }\n    ],\n    \"updateFrequency\": \"300\"\n}\n\u003c/code\u003e\u003c/pre\u003e\n\n\u003c/hr\u003e\n\n3) POST - http://127.0.0.1:8889/remove - x-WWW-FORM \u003c/br\u003e\n\u003cpre\u003e\u003ccode class=\"hljs language-shell\"\u003e\n\tserverKey =\u003e NodeListServerDefaultKey (specified in the Configuration file)\n\tserverUuid =\u003e de94592c-7672-419b-8fe2-234b48e46607 (the Generated uuid)\n\u003c/code\u003e\u003c/pre\u003e\n\n* Successfully Removed that server !!*\n- Looking forward to continue adding to this Documentation and developing this awesome tool with Github community\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSoftwareGuy%2FNodeListServer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSoftwareGuy%2FNodeListServer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSoftwareGuy%2FNodeListServer/lists"}