# Introduction A brief introduction to the MineKeep Docs Welcome to the MineKeep documentation page. Here you can find out about the inner workings of MineKeep, and how to design your server around those. Be sure to join the [MineKeep Discord](https://discord.minekeep.net), where you can chat to us directly, hang out and get questions answered. # Hibernation Understanding when your server will run and stop In order to not run out of compute resources, MineKeep hibernates (shuts down) user servers after they've been left for five minutes without any players on. The five minute timer starts immediately when a server is empty, and cancels immediately once someone logs back on. Contrary to what other hosts do, your server will be automatically started if a player tries to join it. For example, if the server "example" is offline and someone attempts to join `example.minekeep.gg`, they will be sent to the lobby as the server begins starting up. Once the server finishes starting up, the player is redirected to the server without requiring any user interaction. ### Whitelisted servers If a server has whitelist enabled, only players which either are on the whitelist or have operator permissions can trigger the server to start up. ### Disabling Hibernation If you want your server to always be online, you can purchase a plan without hibernation. To do this, go to the upgrade tab in your servers panel and disable the hibernation toggle.

All plans purchased with this toggle *disabled* will not go offline automatically. However this is usually not necessary for most servers. # Opening HTTP ports Exposing HTTP services from a running server instance Sometimes one needs to run an HTTP server on their Minecraft server. Perhaps in order to self-host a dynamically generated resource pack (with ItemsAdder for example), or perhaps in order to expose a Dynmap instance to the internet. MineKeep allows user servers to listen on the following ports: * 2053 * 2083 * 2087 * 2096 ### Example If your server's name is "example" and you've configured Dynmap to listen on port 2053, then your map will be available on . The URL will only work whilst your server is online. # External Servers A guide on how to set up external servers on MineKeep, allowing you to advertise your server hosted elsewhere to thousands of new players {% hint style="info" %} The MineKeep session server is also compatible with Minehut. Thus, you can configure your backend to use the MineKeep session server, and point both your MineKeep and Minehut externals to it. This removes the need for having several proxies.\ \ Note, this does not work the other way around! {% endhint %} ## Step 1. Prepare your target server In order to allow players to connect to your server through MineKeep, you'll have to configure your server to use MineKeep's session server, and optionally enable the PROXY protocol (recommended). {% hint style="danger" %} Not enabling the PROXY protocol makes everyone appear to connect from the same IPs. If you IP ban users without enabling the PROXY protocol, you'll effectively be banning everyone from your external server. {% endhint %} The exact configuration changes needed differ depending on what server software you run. Here are some examples for popular server softwares. ### Velocity If you wish to enable the PROXY protocol, set `haproxy-protocol = true` in **velocity.toml**. Then, proceed to add the following command line option to your startup script: {% hint style="info" %} You must add the flags between `java` and `-jar`, otherwise they will not take effect {% endhint %} ```bash -Dmojang.sessionserver=https://sessionserver.minekeep.net/session/minecraft/hasJoined ``` If added correctly, your startup script should look something like this: ```bash java -Dmojang.sessionserver=https://sessionserver.minekeep.net/session/minecraft/hasJoined -jar velocity.jar ``` ### Waterfall If you wish to enable the PROXY protocol, go to **config.yml** and set: ```yaml listeners: - ... proxy_protocol: true ``` Then, proceed to add the following command line option to your startup script: {% hint style="info" %} You must add the flags between `java` and `-jar`, otherwise they will not take effect {% endhint %} ```bash -Dwaterfall.auth.url="" ``` If added correctly, your startup script should look something like this: ```bash java -Dwaterfall.auth.url="" -jar waterfall.jar ``` ### Bungeecord Bungeecord is obsolete, and furthermore is not supported due to there [not being a configurable session server property](https://github.com/SpigotMC/BungeeCord/pull/3201). You can switch to [Waterfall](https://papermc.io/downloads/waterfall) if you still need the plugin ecosystem provided by Bungeecord. Otherwise, switching to [Velocity](https://papermc.io/software/velocity) is the recommended option. ### Paper Standalone {% hint style="warning" %} This only applies if you're Paper without a proxy in front of it. If you have a proxy, and you've already configured your proxy, you can ignore this. {% endhint %} If you wish to enable the PROXY protocol, go to **config/paper-global.yml** and set ```yaml proxies: proxy-protocol: true ``` Then, make sure to set `enforce-secure-profile=false` in **server.properties.** Finally, add the following command line options to your startup script: {% hint style="info" %} You must add the flags between `java` and `-jar`, otherwise they will not take effect {% endhint %} ```bash -Dminecraft.api.auth.host=https://authserver.mojang.com/ -Dminecraft.api.account.host=https://api.mojang.com/ -Dminecraft.api.services.host=https://api.minecraftservices.com/ -Dminecraft.api.profiles.host=https://api.mojang.com/ -Dminecraft.api.session.host=https://sessionserver.minekeep.net ``` If added correctly, your startup script should look something like this: ```bash java -Dminecraft.api.auth.host=https://authserver.mojang.com/ -Dminecraft.api.account.host=https://api.mojang.com/ -Dminecraft.api.services.host=https://api.minecraftservices.com/ -Dminecraft.api.profiles.host=https://api.mojang.com/ -Dminecraft.api.session.host=https://sessionserver.minekeep.net -jar paper.jar ``` ## Step 2. Create an external server Start by creating a server. Open its panel, and click the ***Upgrade*** button.

A screenshot of the top of the server panel

Proceed to click ***Select*** on the external server plan.

After completing checkout, your server console will have been replaced by a configuration panel. Here, you enter the server address and port of your target server. Make sure to enable PROXY protocol if your server is configured to accept that.

### Step 3. Verify server connection Everything is now set up. Now, verify that your external server is set up correctly by connecting to your server. This can be done either by joining `.minekeep.gg` or by running the command `/join `. If you need additional help, feel free to open a ticket on [our Discord](https://discord.minekeep.net). ### Rules and guidelines These may change at any time. It is your responsibility to ensure continuous compliance. * All [standard MineKeep rules](https://minekeep.net/rules.txt) apply * You cannot connect more than one MineKeep server to the same backend * Your cannot direct players to leave MineKeep, or directly join your server address # Medal Boosts Clip your gameplay with Medal to earn free RAM for your server MineKeep has teamed up with [Medal](https://medal.tv/minekeep) on a limited-time quest. Record your best moments on MineKeep with Medal, post a clip, and unlock free extra RAM for one of your servers. No payment, no catch, just clips. {% hint style="info" %} The quest is for **new Medal users** and is **PC only**, while it stays live. The quest doesn't appear in the Medal mobile app. {% endhint %} ## How to earn a boost Head to [medal.tv/minekeep](https://medal.tv/minekeep) for the full walkthrough, or follow the five steps below. ### 1. Install Medal on PC If you don't already use Medal, [download it on PC](https://medal.tv/minekeep). The quest only runs on the desktop app, so a mobile install won't work for this offer. ### 2. Start the MineKeep quest Open **Home** in the Medal app and find the **Quests** sidebar on the right. Click the **MineKeep × Medal** quest, then hit **Start Quest**. ### 3. Clip a moment on MineKeep With the quest started, launch Minecraft and log in to `minekeep.net`. Press **F8** to save the last 15 seconds of gameplay, then post the clip to your profile with **#minekeep** in the description. ### 4. Submit your server name Back on the Medal homepage, reopen the MineKeep quest in the sidebar, enter the **MineKeep server name** you want the reward applied to, and submit. {% hint style="info" %} You can enter your server's short name (for example `example`) or its full address (`example.minekeep.gg` or `example.bedrock.minekeep.gg`). External servers aren't eligible for boosts. {% endhint %} ### 5. Activate it on your panel Return to your server's panel on MineKeep. Once the quest is complete, a **Medal boost available** button appears. Open it and click **Activate** to apply the extra RAM. {% hint style="info" %} Only the **server owner** can activate boosts. The extra RAM applies on your server's **next restart**. {% endhint %} ## How boosts work * Each boost adds **500 MB** of RAM on top of your plan. * A single server can hold up to **5 boosts** at once, for **2.5 GB** of extra RAM in total. * Each boost stays active for **7 days** from when you activate it. * Boosts **stack**. Invite more people to complete the quest on your server to fill all five slots. When a boost reaches the end of its 7 days, the server restarts to release that RAM. You'll get in-game warnings before the restart so nobody is caught off guard, and players are reconnected automatically once it's back. {% hint style="info" %} Want your server to keep the extra capacity permanently? You can upgrade its plan at any time from the **Upgrade** tab on the server panel. {% endhint %} ## Troubleshooting ### I made a clip, but I can't complete the quest You need to **start the quest before you record the clip**. Medal only counts clips captured after you've hit **Start Quest**, so an older clip won't qualify. Start the quest from the Quests sidebar, then go play MineKeep and press **F8** to save a fresh clip. ### I can't see the quest The quest is only available to **new Medal users**, and only in the **PC** app (it doesn't appear on mobile). If you've used Medal before, or you're looking on your phone, the MineKeep quest won't show up. # Public API Query MineKeep network data programmatically MineKeep offers a free, unauthenticated, read-only REST API at `https://api.minekeep.net`. The interactive documentation (Swagger UI) lives at [api.minekeep.net/docs](https://api.minekeep.net/docs), and the raw OpenAPI 3.1 document at [api.minekeep.net/openapi.json](https://api.minekeep.net/openapi.json). # Player Protection Here's how we keep players on MineKeep safe. Protecting players and their privacy is paramount in keeping our platform safe. Here we detail some of the measures we've taken. # IP Masking Preventing servers from seeing your real IP when you connect to them Typically, when connecting to a server, the server console would print out your IP address as you connect to it. For example, let's say the user **md5nake**'s IP is 127.0.0.1. Then the server console would output: ``` [16:14:12 INFO]: UUID of player md5nake is 12ff72a5-13a7-4d42-a41f-999466d64097 [16:14:12 INFO]: md5nake joined the game [16:14:12 INFO]: md5nake[/127.0.0.1:44290] logged in with entity id 77 at ([world]7.5, 111.0, -5.5) ``` As knowing a player's IP address allows for DDoS attacks, as well as knowing one's approximate (city/region-level) location, MineKeep employs a hashing algorithm when forwarding player IPs to user servers. This preserves the identity aspect of an IP (e.g allowing alt detectors and /ban-ip to function), whilst protecting the privacy of the player. Here's an example of a masked/hashed IP: ``` [16:14:12 INFO]: UUID of player md5nake is 12ff72a5-13a7-4d42-a41f-999466d64097 [16:14:12 INFO]: md5nake joined the game [16:14:12 INFO]: md5nake[/123.123.123.123:0] logged in with entity id 77 at ([world]7.5, 111.0, -5.5) ``` In summary: Player IP addresses are not forwarded to user servers. # Resource Pack Whitelist Preventing side-channel IP leakage When a server sends a resource pack request packet to a client, the client will send an HTTP request to whatever URL the server says the resource pack is hosted at. Because those URLs can be attacker-controlled, a server owner would be able to extract the IP address of any client accepting the server's resource pack. MineKeep prevents IP leakage from happening this way by employing a resource pack host whitelist. Resource pack requests can only reference packs hosted on a set list of trusted domains. All other requests will be dropped. Here are the whitelisted domains: * \*.minekeep.dev ([self-hosted packs](/opening-http-ports)) * \*.wasabisys.com (Wasabi) * download.mc-packs.net (mc-packs) * drive.usercontent.google.com (Google Drive) * github.com (GitHub) * raw\.githubusercontent.com (GitHub) * atlas.nexomc.com (Nexo) * atlas.oraxen.com (Oraxen) * nauticalhosting.org (NauticalRanks) * lobfile.com (ItemsAdder) * dropbox.com (Dropbox) * download\*.mediafire.com (MediaFire) If you need to serve a resource pack. Make sure it originates from one of these domains. Also make sure that the URL you provide leads directly to the download, and not a page with a button that says download. Otherwise Minecraft does not recognise it. # Hiding Your Activity This page shows you how to hide your online status on MineKeep # Ignoring Direct Messages # Server Administration Guides on how to manage your MineKeep server # Adding plugins How to add plugins to your MineKeep Server Plugins are a way to extend the functionality of your Paper/Purpur server whilst still allowing any player to connect, regardless of what mods they may have installed. ## Method 1: Using the Plugin Manager (Recommended) The easiest and fastest way to install plugins is directly through our built-in Plugin Manager on the panel. This automatically handles finding, downloading, placing, and removing the plugin files for you. ### Accessing the Plugin Manager 1. Go to the [MineKeep Dashboard](https://minekeep.net/servers) and select the cog icon next to the start button of your server to open the server management page. 2. In the navigation menu, click on the **Plugins** tab. This will open the Plugin Manager.

### Browsing and Installing Plugins When you open the Plugin Manager, you will see two main sections: **Browse** and **Installed**. 1. Ensure you are on the **Browse** section. 2. Use the **filter options** to choose which platform you want to search through: Modrinth, Hangar, or SpigotMC. 3. Type the name of the plugin into the **search bar** to find what you are looking for. 4. Once you have located the correct plugin, click the button to install it directly to your server.

### Managing Installed Plugins If you want to view the plugins you already have or remove one you no longer need, navigate to the **Installed** section of the popup. Here, you will see a list of all your currently installed plugins, complete with their icon and version number. To remove a plugin, simply click the **Uninstall** button next to it.

*Note: After installing or uninstalling plugins, you will need to restart your server to apply the changes!* *** ## Method 2: Manual Installation If a specific plugin isn't available on the Plugin Manager, or if you are uploading a custom or premium plugin, you can still install it manually. ### Step 1: Finding and downloading plugins Before you install a plugin manually, you first need to download the `.jar` file. We recommend the use of either [SpigotMC](https://www.spigotmc.org/resources/), [Hangar](https://hangar.papermc.io/) or [Modrinth](https://modrinth.com/plugins) for downloading plugins. Below are guides on how to download a plugin from each platform: {% tabs %} {% tab title="SpigotMC" %} To download a plugin from [SpigotMC](https://www.spigotmc.org/resources/), you first need to find a plugin you want to install. This can be done in two ways - You can select a plugin from the [resources page](https://www.spigotmc.org/resources/), or you can search for a plugin by name. **Choosing a plugin from the resources page** Selecting a plugin from the resources page is as easy as going onto the resources page and then clicking on the name of the desired plugin. **Searching for a specific plugin** Searching for a specific plugin is slightly more difficult. To do this, first go onto the [resources page](https://www.spigotmc.org/resources/), and then select the search bar in the top right of the screen. It should look something like this:

Once you have this, you can type the name of the plugin you want into the search bar, and after making sure "Search titles only" and "Search resources only" are selected, press the search button. This will then show you a list of all resources with a same or similar name, in which you can select the one that you are looking for. **Downloading the selected plugin** Now that you have selected the plugin you want to download, you should be on the plugin's resource page, which will look something like this:

From this page, you can click the blue button that says "Download Now". In some cases, this button may take you to an external site, in which there may be an additional step required to download the plugin. Some plugins may be a premium resource, which is where you have to pay to download and use the plugin. If this is the case, you may have to create a SpigotMC account and follow the steps to purchase the plugin before downloading it. You should now have a .jar file downloaded to your device, which is the plugin file. You can now continue on to the rest of the tutorial below. {% endtab %} {% tab title="Hangar" %} To download a plugin from [Hangar](https://hangar.papermc.io/), you first need to find a plugin you want to install. This can be done in two ways - You can select a plugin from the [home page](https://hangar.papermc.io/), or you can search for a plugin. **Choosing a plugin from the home page** Selecting a plugin from the home page is as easy as going to the [Hangar Website](https://hangar.papermc.io/) and then clicking on the desired plugin. **Searching for a specific plugin** You can search for a desired plugin on Hangar via the search bar found on the home page. This search bar is pointed out below:

From here, you can enter the name of the plugin you wish to download, and hangar will then display plugins with the same or similar name, which you can then select the correct item. **Downloading the selected plugin** Now that you have selected the plugin you want to download, you should be on the plugin's resource page, which will look something like this:

From this page, you can click the blue button that says "Download". In some cases, this button may take you to an external site, in which there may be an additional step required to download the plugin. You should now have a .jar file downloaded to your device, which is the plugin file. You can now continue on to the rest of the tutorial below. {% endtab %} {% tab title="Modrinth" %} To download a plugin from [Modrinth](https://modrinth.com/plugins), you first need to find a plugin you want to install. This can be done in two ways - You can select a plugin from the [plugins page](https://modrinth.com/plugins), or you can search for a plugin. **Choosing a plugin from the plugins page** Selecting a plugin from the home page is as easy as going to the [Modrinth plugins page](https://modrinth.com/plugins) and then clicking on the desired plugin. **Searching for a specific plugin** You can search for a desired plugin on Modrinth via the search bar found on the plugins page. This search bar is pointed out below:

From here, you can enter the name of the plugin you wish to download, and Modrinth will then display plugins with the same or similar name, which you can then select the correct item. **Downloading the selected plugin** Now that you have selected the plugin you want to download, you should be on the plugin's resource page, which will look something like this:

From this page, you can click the green button that says "Download". Clicking this will display a popup like this one:

From here, you can open the select game version option and choose the version of your server, and when it asks you to select a platform, choose paper. If paper is not an option, you may be given the option to use spigot or bukkit, which may also work. After selecting these options, you will be shown another green button with the text "Download" written on it. Press this to download the plugin's .jar file onto your device. You should now have a .jar file downloaded to your device, which is the plugin file. You can now continue on to the rest of the tutorial below. {% endtab %} {% endtabs %} ### Step 2: Uploading to your server Now that you have the plugin file you want to add to your server, go to the [MineKeep Dashboard](https://minekeep.net/servers) and select the cog icon next to the name of your server. This will bring you to the management page for your server. It should look something like this:

From here, you can click on the button that says "Files". This will bring you to the file manager for your server. It should look something like this:

If you do not see the "plugins" folder, you can create one by clicking the Create a folder button highlighted below:

Now that you have a "plugins" folder, select the folder by clicking it, and then click the upload button (the button to the right of the Create a folder button). This will bring up an upload dialog that allows you to either select a file, or drag a file on to it. From here, you can select the main area of the dialog, which will open a file selection window. Use this to navigate to the .jar file you previously downloaded, then select it. This will upload the plugin to your MineKeep server. Once uploaded, restart your server to apply the changes. *** ## Verifying your plugins Regardless of which method you used to install your plugins, you can easily check if they are working properly! Once your server has started, type `/plugins` in-game or in the console. * **Green text:** Congratulations, you have successfully installed the plugin on your MineKeep server! * **Red text:** This most likely means that either the plugin requires another dependent plugin to work, or that it requires initial configuration. To troubleshoot a red plugin, go back to the plugin's download page and check for any mentions of "requirements" or "dependencies" in the description. You can also look for a support link to ask the plugin's developer or community for help. # Adding mods How to add Fabric mods to your MineKeep Server {% hint style="danger" %} MineKeep servers **only** support **Fabric** mods. Please ensure you do not attempt to install Forge or NeoForge mods, as they will not work. {% endhint %} Fabric mods are a way to change the gameplay or add new content to your server. Unlike plugins, mods generally require players to have the same mods installed on their client to connect. **Important:** Most Fabric mods require the **Fabric API** mod to be installed as well. You should treat Fabric API as an essential installation before adding other mods. ## Method 1: Using the Mod Manager (Recommended) The easiest and fastest way to install mods and modpacks is directly through our built-in Mod Manager on the panel. This automatically handles finding, downloading, placing, and removing the mod files for you. ### Accessing the Mod Manager 1. Go to the [MineKeep Dashboard](https://minekeep.net/servers) and select the cog icon next to the start button of your server to open the server management page. 2. In the navigation menu, click on the **Mods** tab. This will open the Mod Manager popup.

### Browsing and Installing Mods When you open the Mod Manager, you will see three main sections: **Browse**, **Installed**, and **Modpacks**. 1. Ensure you are on the **Browse** section. 2. Use the **filter options** to choose which platform you want to search through: Modrinth or CurseForge. 3. Type the name of the mod into the **search bar** to find what you are looking for. 4. Once you have located the correct mod, click the button to install it directly to your server.

### Installing Modpacks If you want to install an entire pre-made collection of mods, you can use the **Modpacks** tab! This works exactly like the Browse tab, but instead of searching for individual mods, it searches through full modpacks hosted on Modrinth and CurseForge. Simply find the modpack you want and click install to apply it to your server.

### Managing Installed Mods & Easy Client Downloads If you want to view the mods you already have or remove one you no longer need, navigate to the **Installed** section. Here, you will see a list of all your currently installed mods, complete with their icon and version number. To remove a mod, simply click the **Uninstall** button next to it. **Downloading Mods for your Client:** Because players need the exact same mods installed on their computer to join your server, we've made this easy! You can click the **Download** button on the Installed page to automatically bundle all your server's mods into a `.zip` file and download them straight to your device.

*Note: After installing or uninstalling mods, you will need to restart your server to apply the changes!* *** ## Method 2: Manual Installation If a specific mod isn't available on the Mod Manager, or if you are uploading a custom mod, you can still install it manually. ### Step 1: Finding and downloading Fabric mods Before you install a mod manually, you first need to find and download the `.jar` file. We recommend the use of either [CurseForge](https://www.curseforge.com/minecraft/search?class=mc-mods) or [Modrinth](https://modrinth.com/mods) for downloading mods. Below are guides on how to download the correct Fabric version from each platform: {% tabs %} {% tab title="CurseForge" %} To download a mod from [CurseForge](https://www.curseforge.com/minecraft/search?class=mc-mods), you first need to find a mod you want to install. **Searching for a specific mod** You can search for a specific mod by using the search bar at the top of the CurseForge website.

Type the name of the mod you want, and press enter. Select the correct mod from the list of results. **Downloading the Fabric version** Once you are on the mod's page, do **not** click the main download button immediately. Instead, click on the **Files** tab. This is crucial to ensure you get the Fabric version and not the Forge version.

From the Files list, you must filter by your **Game Version** (e.g., 1.20.1) and ensure the **Mod Loader** is set to **Fabric**.

Once you find the file that matches your version and says "Fabric", click the three dots icon, and select the "Download file" button from the list of options.

You should now have a .jar file downloaded to your device. You can now continue on to the rest of the tutorial below. {% endtab %} {% tab title="Modrinth" %} To download a mod from [Modrinth](https://modrinth.com/mods), you first need to find a mod you want to install. **Searching for a specific mod** You can search for a desired mod on Modrinth via the search bar found on the mods page.

From here, you can enter the name of the mod you wish to download. To make things easier, you can select "Fabric" under the "Loader" filter on the left side of the page. **Downloading the Fabric version** Now that you have selected the mod you want to download, you should be on the mod's resource page. Click the "Versions" tab or the green "Download" button.

**Crucial Step:** When looking at the list of versions, you must ensure the file is tagged with **Fabric**. Do not download files tagged only with "Forge" or "NeoForge".

After verifying the version is for Fabric, click the download button (usually a small download icon) to save the .jar file onto your device. You can now continue on to the rest of the tutorial below. {% endtab %} {% endtabs %} ### Step 2: Uploading to your server Now that you have the Fabric mod you want to add to your server, go to the [MineKeep Dashboard](https://minekeep.net/servers) and select the cog icon next to the name of your server. This will bring you to the management page for your server. It should look something like this:

From here, you can click on the button that says "Files". This will bring you to the file manager for your server. It should look something like this:

If you do not see the **"mods"** folder, you can create one by clicking the Create a folder button highlighted below (ensure you name it `mods` in all lowercase):

Now that you have a "mods" folder, select the folder by clicking it, and then click the upload button (the button to the right of the Create a folder button). This will bring up an upload dialog that allows you to either select a file, or drag a file on to it. From here, you can select the main area of the dialog, which will open a file selection window. Use this to navigate to the .jar file you previously downloaded, then select it. This will upload the mod to your MineKeep server. *** ## Important Notes on Fabric Mods Regardless of whether you used the Mod Manager or installed them manually, keep these things in mind: 1. **Fabric API:** Almost all Fabric mods require a separate mod called [**Fabric API**](https://modrinth.com/mod/fabric-api) to work. Please ensure this is installed alongside your other mods. 2. **Dependencies:** Check the mod's download page for other requirements. Some mods require libraries like "Cloth Config" or "Architectury". 3. **Restart:** You must restart your server for mods to load. 4. **Client Installation:** Remember, if the mod adds new blocks or items, you must install the exact same mod version on your own Minecraft client to join the server.