> For the complete documentation index, see [llms.txt](https://docs.ohalee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ohalee.com/products/modern-bedwars/installation.md).

# Installation

This walks you from a clean network to a running Modern BedWars stack: **Velocity proxy + lobby servers + game servers + standalone service**, backed by **Redis + MariaDB**.

{% hint style="info" %}
Start order is always **service → proxy → lobby → game** — the brain must be online before anything registers with it. Read [architecture.md](/products/modern-bedwars/architecture.md) first.
{% endhint %}

## 1. Requirements

| Component           | Version                  | Where                                                   |
| ------------------- | ------------------------ | ------------------------------------------------------- |
| Java                | **25**                   | Every node (proxy, lobby, game, service host)           |
| Paper               | 1.8 **or** 26.1+         | Lobby + game servers (game plugin is multi-version)     |
| Velocity            | 3.x latest               | Proxy                                                   |
| Redis               | 6.0+                     | Reachable by every node                                 |
| MariaDB / MySQL     | MariaDB 10.6+ or MySQL 8 | Reachable by every node                                 |
| Map-restore backend | pick one                 | Each game server needs **one** — see below              |
| LuckPerms           | latest                   | **Required** on every game server, recommended on lobby |
| PlaceholderAPI      | latest                   | Optional, lobby-side placeholders only                  |

> The `service` host does **not** need a Minecraft server — plain Java + network access to Redis + MariaDB is enough.

### Map-restore backend

Each game server needs exactly **one** way to reset maps between matches:

* **SlimeWorldManager (SWM)** — legacy slime worlds (good on 1.8).
* **Advanced Slime Paper (ASP)** — modern slime worlds with MySQL-shared storage; preferred on 26.1+ if installed.
* **Classic file restorer** (built-in fallback) — copies a template world folder per match. Requires the **VoidGen** plugin so surroundings stay void.

## 2. Infrastructure

### Redis

1. Install Redis on a host reachable by all nodes (default port `6379`).
2. (Recommended) set a password in `redis.conf`: `requirepass yourStrongPassword`.
3. Restart and verify: `redis-cli ping` → `PONG`.

### MariaDB

1. Install MariaDB 10.6+ (or MySQL 8).
2. Create the database and a dedicated user:

   ```sql
   CREATE DATABASE bedwars CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   CREATE USER 'bedwars'@'%' IDENTIFIED BY 'yourStrongPassword';
   GRANT ALL PRIVILEGES ON bedwars.* TO 'bedwars'@'%';
   FLUSH PRIVILEGES;
   ```
3. Apply the shipped schema (`database.sql`):

   ```bash
   mysql -h <host> -u bedwars -p bedwars < database.sql
   ```

   This creates tables for `bedwars_users`, `bedwars_stats`, `bedwars_leaderboard`, `bedwars_multipliers`, `bedwars_presets`, `bedwars_user_cosmetics`, `bedwars_active_cosmetics` and `disguises`.

## 3. Install the service (start it first)

1. Copy `Bedwars-Service.jar` to a host.
2. Next to the jar, create `application.properties` with your Redis and MariaDB connection details (see [configuration.md](/products/modern-bedwars/configuration.md)).
3. Start it: `java -jar Bedwars-Service.jar`.
4. You land in a Spring Shell prompt (`shell:>`). Run `list servers` — an empty table is expected (no game servers yet).

To run it as a Linux service, use a `systemd` unit:

```ini
[Unit]
Description=Modern BedWars Service
After=network-online.target

[Service]
User=bedwars
WorkingDirectory=/opt/bedwars-service
ExecStart=/usr/bin/java -jar Bedwars-Service.jar
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

## 4. Install the proxy plugin

1. Drop `Bedwars-Velocity-1.0.jar` into the Velocity `plugins/` directory.
2. Start the proxy once to generate `plugins/bedwars-proxy/` with `mariadb.json`, `redis.json` and `config.json`.
3. Fill in the DB/Redis credentials, and adjust `config.json` server-name prefixes if you use different names (see [configuration.md](/products/modern-bedwars/configuration.md)).
4. In `velocity.toml`, register every lobby and game server; the names must match the prefixes from `config.json`.
5. Restart the proxy.

## 5. Install the lobby plugin (every lobby server)

1. Drop `Bedwars-Lobby-1.0.jar` into the lobby Paper `plugins/` folder.
2. Start once to generate `plugins/bedwars-lobby/`.
3. Edit `config.yml`: set a unique `server-id` (e.g. `bedwars_lobby_1`) and the DB/Redis credentials.
4. (Optional) install **PlaceholderAPI** for `bedwars_*` placeholders.
5. Restart.

{% hint style="warning" %}
The lobby plugin refuses to enable if the database `password` is empty. Set it.
{% endhint %}

## 6. Install the game plugin (every game server)

1. Install your chosen **map-restore backend** and **LuckPerms** first.
2. Drop `Bedwars-Instance-1.0.jar` into the game Paper `plugins/` folder.
3. Start once to generate `plugins/bedwars/` and its `defaults/` directory.
4. Edit `config.yml`. The `server-id` must match the name you registered in `velocity.toml` **and** start with the proxy's `gamePrefix` (default `bedwars_game_`).
5. Tune `defaults/*.yml` as needed — see [configuration.md](/products/modern-bedwars/configuration.md).
6. Restart. On enable the server registers itself with the service over Redis; verify with `list servers` in the service shell.

## 7. Verify

Connect a Minecraft client to the proxy. You should land in the lobby, see the queue GUI, and be able to start a match.