{"id":21508855,"url":"https://github.com/oddlama/minecraft-server","last_synced_at":"2025-04-08T03:13:30.304Z","repository":{"id":37583162,"uuid":"296850990","full_name":"oddlama/minecraft-server","owner":"oddlama","description":"A simple but fully-featured minecraft server installer for linux. Comes with autostart, 3d online map, vane, account multiplexing, update script and more.","archived":false,"fork":false,"pushed_at":"2025-01-03T13:49:19.000Z","size":416,"stargazers_count":69,"open_issues_count":4,"forks_count":14,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-31T16:17:49.691Z","etag":null,"topics":["installer","linux","minecraft","minecraft-plugin","minecraft-server"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/oddlama.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":"2020-09-19T11:14:21.000Z","updated_at":"2025-03-30T12:16:20.000Z","dependencies_parsed_at":"2025-01-03T14:36:35.232Z","dependency_job_id":"55c28996-cde8-4c00-b00d-df0317623e73","html_url":"https://github.com/oddlama/minecraft-server","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/oddlama%2Fminecraft-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddlama%2Fminecraft-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddlama%2Fminecraft-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddlama%2Fminecraft-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oddlama","download_url":"https://codeload.github.com/oddlama/minecraft-server/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247767236,"owners_count":20992548,"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":["installer","linux","minecraft","minecraft-plugin","minecraft-server"],"created_at":"2024-11-23T21:13:09.049Z","updated_at":"2025-04-08T03:13:30.292Z","avatar_url":"https://github.com/oddlama.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg width=\"auto\" height=\"90\" src=\"https://github.com/oddlama/minecraft-server/blob/pages/docs/logo.png\"\u003e\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[![Landing Page](https://img.shields.io/badge/Landing_Page-informational.svg)](https://oddlama.github.io/minecraft-server)\n[![MIT License](https://img.shields.io/badge/license-MIT-informational.svg)](./LICENSE)\n[![Join us on Discord](https://img.shields.io/discord/907277628816388106.svg?label=\u0026logo=discord\u0026logoColor=ffffff\u0026color=7389D8\u0026labelColor=6A7EC2)](https://discord.gg/RueJ6A59x2)\n\n\u003c/div\u003e\n\n# Minecraft Server Installer\n\nThis is a simple but fully-featured minecraft server installer for linux.\nIt should serve as an example of how to properly(TM) deploy a personal minecraft server with the following features:\n\n- 🚀 Server starts automatically when players connect and shuts down when idle\n- ⏱️ Utilizes [PaperMC](https://papermc.io) and [Aikar's JVM flags](https://aikar.co/mcflags.html) for maximum performance\n- 🔒 Sandboxed execution with systemd, no docker\n- 💾 Creates proper incremental world backups after each server stop\n- 🖥️ Background console access via tmux (also remotely via ssh)\n- 🔢 Account multiplexing allows a single account to have two or more player characters\n- 🗺️ Awesome 3D online map using [BlueMap](https://bluemap.bluecolored.de/)\n- 🔋 Single-command scripts to update server and plugins\n- 🐙 Ready for configuration file tracking via git\n- \u003cimg width=\"auto\" height=\"20px\" src=\"https://github.com/oddlama/vane/blob/main/docs/vane.png\"\u003e Includes vanilla enhancements by [vane](https://github.com/oddlama/vane)\n\n## 🛠 Installation\n\nTo begin the automatic installation, simply run the provided bootstrap script.\nAfterwards you can continue [configuring your server](#Server-Configuration),\nor jump straight to the [Usage](#Usage) section if you are happy with the defaults.\n\n```bash\ncurl -sL https://github.com/oddlama/minecraft-server/raw/refs/heads/main/installer/bootstrap | sudo bash\n# Connect to the console (Press Ctrl+b then d to detach again)\nsudo minecraft-attach server\n# Don't forget to foward or expose TCP ports 25565 (server), 25566 (multiplexer 1)\n# and 8100 (online map). The map will be available under http://\u003cyour-ip\u003e:8100\n```\n\nYou may want to [review](https://github.com/oddlama/minecraft-server/blob/main/installer/bootstrap) the script before executing it.\nIn summary, the script will perform the following steps:\n\n- Check whether all required tools are installed\n- Create a new `minecraft` user for the server (if not existing)\n- Update the server jars and download all plugins\n- Install, enable and start the systemd services\n\n## ⚙️ Server configuration\n\nAt this point, your proxy server is already running and the actual\nserver will be started once you connect to it. Now is the time to\nreview or change the server configuration. The main directory of your server\nis `/var/lib/minecraft/deploy`. All files in that directory must be accessible to the `minecraft` user,\nso before changing anything it is a good idea to open a terminal as the\nminecraft user by executing `sudo runuser -u minecraft bash`.\n\nThe following sections are dedicated to things that you might want to configure now.\nAll other settings that were already changed by this script compared to the minecraft default\nare listed in [Default Settings](#Default-Settings).\n\nWhen you are happy with your configuration, continue to the [Usage](#Usage) section.\n\n### 🌱 Seed\n\nBefore your server is started for the first time, you can can specify a seed via `level-seed=`\nin `server.properties`. To find a good seed before generating your world, have a look\nat [Cubiomes Viewer](https://github.com/Cubitect/cubiomes-viewer).\n\n### 📜 Whitelist / Graylist\n\nBy default there is no protection enabled, everyone can join and play.\nYou can enable a classic whitelist with `whitelist on`.\n\nAnother option that vane provides is a feature similar to a graylist.\nThis allows anyone to connect to your server but in a *no touch, only look!* kind of way.\nTo modify anything about the world, a player must either be opped,\nor be assigned to the user group with `perm add player_name user`, or any higher group.\nTo enable the graylist, set the following option:\n\n```yaml\n# server/plugins/vane-admin/config.yml\nworld_protection:\n  enabled: true\n```\n\nAdditionally, if you assign a player to the verified group with `perm add player_name verified`,\nthey may vouch for other users by using `/vouch other_player`. This will lift the other user into the `users` group.\nUseful to give your friends the permission to invite other people they know. It will\nbe stored who vouched for whom.\n\n### 🗒️ Serverlist text \u0026 icon\n\nThe text and icon in your server list now controlled by the proxy instead of your `server.properties`.\nEdit `proxy/plugins/vane-velocity/config.toml` to change the text to your liking. You can also\nset different texts based on whether the server is currently started or not.\n\nTo set a server icon, simply drop a file name `server-icon.png` in your `server/` directory,\nnext to where the `paper.jar` is.\n\n## 🚀 Usage\n\nIn the following you will learn how to use the features of this deploy\nto access the console, update your server among other things.\n\n### 🔑 Accessing the server/proxy console\n\nAccess to your server console is crucial. The services keep both the proxy and server\nconsole in the background at all times, so you can access them from any\nterminal on your server (also remotely via ssh!).\n\n```bash\nsudo minecraft-attach server # Open the server console\nsudo minecraft-attach proxy  # Open the proxy console\n```\n\nOnce you execute one of the commands above, you will be presented\nwith the respective console. If that command fails, make sure the\nsystem services are running! Press \u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003eb\u003c/kbd\u003e followed by \u003ckbd\u003ed\u003c/kbd\u003e\nto leave the console. This will put it in the background again.\n\n### 🗺️ 3D Online map (BlueMap)\n\nThe awesome 3D online map comes fully preconfigured. All you need to\ndo is open `http://\u003cyour-server-address\u003e:8100` in your favourite browser,\nwhen your server is online. Replace your-server-address with the IP or domain name\nyou use to connect in minecraft.\n\nIf you have an external webserver, BlueMap can be configured to be always available.\n\n### 🔢 Account multiplexing\n\nA multiplexer is an additional port for your server. When someone connects\nvia this port, they will be logged into a secondary player character. This also\nworks while being logged in on the main server. Very useful for account sharing or\nto hand out spectator accounts. Just add a new serverlist entry for the multiplexer\nand enjoy having multiple accounts!\n\nTwo accounts is not enough? Adding additional multiplexers is simple:\n\n1. Forward or expose a new port. (e.g. 25567)\n2. Add a new config for the multiplexer in `proxy/plugins/vane-velocity/config.toml`:\n   ```\n   [auth_multiplex.2]\n   port = 25567\n   allowed_uuids = [] # anyone may use this multiplexer\n   ```\n3. (Repeat for each additional multiplexer you want to add)\n\nTo disable this feature altogether, just remove all `auth_multiplex.*` sections from the config.\n\n### 🔄 Updating the server\n\nTo update the server jars and all plugins, we first stop all services,\nrun the updater and then start them again. To do this, execute the\nfollowing commands as root:\n\n```bash\nsystemctl stop minecraft-proxy minecraft-server    # Stop services\ncd /var/lib/minecraft/deploy                       # Change into deploy directory\n./update.sh                                        # Run update script\nsystemctl start minecraft-proxy minecraft-server   # Start services again\n```\n\n### 🔄 Updating the deploy script\n\nGenerally you shouldn't need to update the deploy script.\nThe only time it might be necessary is when one the included plugins changes\nits download location. You will notice when that happens, as `./update.sh` will fail.\nOther updates to this repository will most likely be minor changes.\n\nTo update, execute the following commands as root:\n\n```bash\nsystemctl stop minecraft-proxy minecraft-server    # Stop services\ncd /var/lib/minecraft/deploy                       # Change into deploy directory\ngit pull                                           # Get updates from upstream\n./contrib/install.sh                               # Re-install the service files\nsystemctl start minecraft-proxy minecraft-server   # Start services again\n```\n\n### 🔌 Installing and removing plugins\n\nPlugins are installed and updated by the `update.sh` scripts.\nTo add a new plugin, find a download link that always points to the latest version\nand add an entry at the end of the respective script, similar to those that are already present.\n\nFor example to add worldguard, you add the following at the end of `server/update.sh`:\n```bash\ndownload_file \"https://dev.bukkit.org/projects/worldguard/files/latest\" plugins/worldguard.jar\n```\n\nTo remove plugins, simply delete the jar file and remove the corresponding line in the\nscript. To remove a vane module, remove it from the list in the for loop.\n\n### 🔐 Changing permissions plugin\n\nBy default, this setup uses a very lightweight permission plugin called `vane-permissions`.\nIf you want to use a different permission plugin, be sure remove `vane-permissions` from the\nplugins as shown above and follow [this guide](https://github.com/oddlama/vane/wiki/Installation-Guide#3-give-permissions-to-players)\nin order not to break vane with your new plugin.\n\n### 💾 Restoring backups\n\nYour server will automatically create an incremental backup of all three worlds and the plugin folder everytime the server is stopped.\nYou can view all the backups that have been created until now by executing the following commands as root:\n\n```bash\ncd deploy/server\nrdiff-backup -l backups/world\n```\n\nNow if anything happens on your server and you want to revert to an older version,\nyou can do so by simply executing the following commands as root:\n\n```bash\ncd deploy/server\nrm -rf world  # First delete what you want to restore\nrdiff-backup -r 1B backups/world world # Restore state from the last backup.\n# Repeat analogously for any other folders that you want to restore:\n# You can restore world, world_nether, world_the_end, and plugins\n```\n\nThe `1B` just refers to the last backup, `2B` would be the second last.\nYou can also pick any of the times listed by `rdiff-backup -l` from before (like\n`2022-06-22T20:21:42+02:00`) or pick a relative time like `2D` (2 days ago).\n\nIf you want to reduce the size of your backups, try `rdiff-backup --remove-older-than 6M` to delete\nany backups older than six months. You can also do a lot more specific things with rdiff-backup.\nVisit [their website](http://rdiff-backup.nongnu.org/examples.html) for more information.\n\n### 💾 Changing or disabling backups\n\nTo create backups, the service calls the `server/backup.sh` file automatically each time the server stops.\nFeel free to adjust this script to your liking. To completely disable backups, replace the script's content with:\n\n```bash\n#!/bin/bash\nexit 0\n```\n\n### 🐙 Tracking configuration with git\n\nThis project include a utility script called `contrib/organize_configs.sh`. If you execute it,\nit will sort the keys in all your configuration files alphabetically so they can be tracked by git properly.\nThis is necessary as the server will rewrite the configuration files each time the server is started,\ncausing the entries to shift around unpredictably.\n\nThe `.gitignore` files are already setup so you will not accidentally commit your whole world\nor some cache files. Only configuration files are considered by default.\nTo actually commit your configs, you should fork this project and update your git remote:\n\n```bash\n# Fork on github first, then replace the remote url:\ncd deploy\ngit remote set-url origin git@github.com:youruser/minecraft-server.git\ngit add .\ngit commit -m \"Initial configuration commit\"\ngit push\n```\n\n## 🔧 Default settings\n\nThis project comes with a reasonable default configuration for paper (main server)\nand velocity (proxy server). This ensures that autostarting and account multiplexing\nwork out of the box. Some of these configs depend on your choices in the bootstrap script,\ndenoted below by the *(asks)* prefix. These are the configuration defaults that differ\nby default from a freshly generated configuration:\n\n#### Proxy settings\n\n- Configure the proxy server (online mode, autostart, ...)\n- Enable one account multiplexer (second player character for each account)\n\n#### Spigot settings\n\n- Remove unnecessary aliases from `commands.yml`\n- Tell PaperMC that a proxy is used.\n- Don't have PaperMC restart the server on crash. The system service takes care of that.\n- Prevent annoying infinite sound broadcasts (dragon death, end portal, wither).\n- Change the *moved-too-quickly* threshold to be less aggressive (ensures smoother elytra flight).\n- Allow players to see entities up to 512 blocks away.\n- Lower xp and item merge radius for a more vanilla experience while still reducing lag.\n\n#### PaperMC settings\n\n- (asks) Allow TNT duping and bedrock removal.\n- (asks) Enable Anti-XRAY.\n- (asks) Replenish loot chests after 1-2 realtime days.\n- (asks) Disable hopper item move event.\n\n#### Vanilla settings\n\n- Set difficulty to HARD\n- Increase slots to 6666\n- (asks) Increase view distance to 15 chunks\n- Increase entity broadcast range (allow players to see entities far away)\n- Disable spawn protection (use better setting from vane-admin if you want this)\n- Set online mode to false (this is checked by the proxy)\n- Listen on port 25501 so proxy can connect (**do not** forward this port!)\n\n## ⭕ Uninstalling\n\nIf you want to uninstall this server, simply execute the following commands:\n\n```bash\n# Disable \u0026 stop services\nsystemctl disable --now minecraft-{proxy,server}\n# Remove service files and attach script\nrm /lib/systemd/system/minecraft-{proxy,server}.service /usr/bin/minecraft-attach\n# Remove user and delete files in /var/lib/minecraft\nuserdel -r minecraft\n```\n\n## 🛠️ Useful tools\n\n- [Cubiomes Viewer](https://github.com/Cubitect/cubiomes-viewer) - To find a good world seed\n- [MCASelector](https://github.com/Querz/mcaselector) - To trim e.g. unpopulated chunks\n\n## ❤️ Contributing\n\nDo you want to suggest a feature or extend this deploy?\nPlease feel free to create an issue or pull-request on github!\nAlso if you want to create and maintain a packaged version of this deploy for your favourite distribution's package manager,\nfeel free to reach out on the [Vane Discord Server](https://discord.gg/RueJ6A59x2).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foddlama%2Fminecraft-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foddlama%2Fminecraft-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foddlama%2Fminecraft-server/lists"}