Installation

Step-by-step guide to installing Maintenance on Paper, BungeeCord, Velocity, or Sponge

This guide will walk you through installing the Maintenance plugin on your Minecraft server.

System requirements

Before installing, ensure your server meets these requirements:

Maintenance requires Java 21 or higher to run. The plugin targets Java 17 but compilation requires JDK 21+.

• Paper: Version 1.20.1 or higher (Spigot also works with limited functionality)
• BungeeCord: Modern versions
• Velocity: Modern versions
• Sponge: Modern versions
• Java: JDK 21 or higher

Download the plugin

1. Visit Hangar

   Go to the Maintenance plugin page on Hangar.

2. Download the latest version

   Click the download button to get the latest stable release. The same JAR file works for all platforms (Paper, BungeeCord, Velocity, Sponge).

3. Verify the download

   Make sure the downloaded file has a .jar extension and is named something like Maintenance-x.x.x.jar.

Installation steps

The installation process varies slightly depending on your server platform.

Paper

1. Stop your server

   If your Paper server is running, stop it gracefully using the stop command.

2. Place the JAR file

   Copy the downloaded Maintenance-x.x.x.jar file into your server’s plugins folder.

3. Start your server

   Start your Paper server. The plugin will generate its configuration files on first launch.

4. Verify installation

   Check your console for a message indicating Maintenance has loaded successfully. You can also run /plugins in-game to see if Maintenance appears in the list.

Paper servers support additional features like custom server icons. Optional soft dependencies include ProtocolLib, ServerListPlus, ProtocolSupport, and LuckPerms.

BungeeCord

1. Stop your proxy

   If your BungeeCord proxy is running, stop it gracefully.

2. Place the JAR file

   Copy the downloaded Maintenance-x.x.x.jar file into your proxy’s plugins folder.

3. Start your proxy

   Start your BungeeCord proxy. The plugin will generate its configuration files on first launch.

4. Verify installation

   Check your console for a message indicating Maintenance has loaded successfully. You can run /glist or check the plugins folder to verify.

On BungeeCord, you can enable maintenance mode per-server or globally across your network. Optional soft dependencies include ServerListPlus and LuckPerms.

Velocity

1. Stop your proxy

   If your Velocity proxy is running, stop it gracefully.

2. Place the JAR file

   Copy the downloaded Maintenance-x.x.x.jar file into your proxy’s plugins folder.

3. Start your proxy

   Start your Velocity proxy. The plugin will generate its configuration files on first launch.

4. Verify installation

   Check your console for a message indicating Maintenance has loaded successfully.

Velocity supports all proxy features including per-server maintenance and Redis synchronization for multi-proxy setups.

Sponge

1. Stop your server

   If your Sponge server is running, stop it gracefully.

2. Place the JAR file

   Copy the downloaded Maintenance-x.x.x.jar file into your server’s mods folder.

3. Start your server

   Start your Sponge server. The plugin will generate its configuration files on first launch.

4. Verify installation

   Check your console for a message indicating Maintenance has loaded successfully.

First-time setup

After installing the plugin, you’ll find new configuration files in your plugin folder:

1. Locate configuration files

   Navigate to the plugin’s data folder:

   • Paper/Spigot/Sponge: plugins/Maintenance/
   • BungeeCord/Velocity: plugins/Maintenance/

   You should see the following files:

   • config.yml - Main configuration file
   • language-en.yml - English language file (other languages available)
   • WhitelistedPlayers.yml - Maintenance whitelist
2. Review the config.yml file

   Open config.yml in a text editor. This file controls all plugin behavior including:

   • Maintenance enabled status
   • MOTD messages (using MiniMessage format)
   • Server icon settings
   • Timer broadcast intervals
   • Kick behavior

   The plugin uses MiniMessage format, not legacy text. Use the Adventure MiniMessage Web UI to preview and create formatted messages.

3. Choose your language

   By default, the plugin uses English. To change the language, edit the language setting in config.yml:

   language: en
   

   Available languages include: en, de, fr, pt, es, ru, zh, it, pl, tr, sv, uk, ja, da, ko, hu, vi

4. Reload the plugin

   After making configuration changes, reload the plugin:

   /maintenance reload
   

   This reloads the config, language file, whitelist, and server icon without restarting your server.

Optional: Custom server icon

To display a custom server icon during maintenance:

1. Set custom-maintenance-icon: true in config.yml
2. Place a maintenance-icon.png file (64x64 pixels) in the plugin’s folder
3. Reload the plugin with /maintenance reload

Next steps

Now that you’ve installed Maintenance, head over to the quickstart guide to learn how to use the basic commands and configure your first maintenance session.