auth-limbo/docs/installation.md

# Installation

## Prerequisites

| Component | Minimum | Notes |
|-----------|---------|-------|
| Server software | Paper 1.21.11 (or Purpur on the same MC version) | Folia is untested. |
| Java | 21 | Required by Paper 1.21+. |
| AuthMe-ReReloaded | any 5.x or 6.x fork | Verified on the HaHaWTH fork build 49 (`5.6.0-FORK-b49`). Hard dependency. |

## Bare-metal / VPS install

1. Download `AuthLimbo-X.Y.Z.jar` from the
   [Releases page](https://github.com/s8n-ru/auth-limbo/releases/latest).
2. Drop the jar into your server's `plugins/` directory.
3. Restart the server. Do **not** use `/reload` — the listener wiring
   does not survive a hot reload.
4. On first start the plugin will create:
   - `plugins/AuthLimbo/config.yml`
   - The `auth_limbo/` world directory at the server data root.
5. Tail the log and look for:

   ```
   [AuthLimbo] Using AuthMe DB at: /path/to/plugins/AuthMe/authme.db
   [AuthLimbo] Limbo world 'auth_limbo' already loaded.
   [AuthLimbo] Enabled. Listening for AuthMe LoginEvent at MONITOR.
   ```

   If you see "No saved location for ..." on a successful `/login`, that
   user has no row in `authme.db` yet — log out, log back in, and the
   row will be written by AuthMe on quit.

## Docker (`itzg/minecraft-server`)

This is the recommended distribution. Add the plugin via the auto-loader.

```yaml
services:
  mc:
    image: itzg/minecraft-server:java21
    environment:
      EULA: "TRUE"
      TYPE: PAPER
      VERSION: "1.21.11"
      PLUGINS: |
        https://github.com/s8n-ru/auth-limbo/releases/download/v1.0.0/AuthLimbo-1.0.0.jar
      # Pin the version — itzg's auto-loader purges unrecognised jars on restart.
      REMOVE_OLD_MODS: "TRUE"
      REMOVE_OLD_MODS_INCLUDE: "*.jar"
      REMOVE_OLD_MODS_EXCLUDE: "AuthLimbo*.jar,AuthMe*.jar,(other-plugins)*.jar"
    volumes:
      - ./data:/data
    ports:
      - "25565:25565"
```

Notes:
- Replace `v1.0.0` and `1.0.0` with the version you want to pin.
- `REMOVE_OLD_MODS_EXCLUDE` must list every jar you want kept; everything
  else gets wiped on restart.
- AuthMe must also be in `PLUGINS` (or otherwise present in `plugins/`)
  before this plugin loads — Paper enforces the `depend` ordering from
  `plugin.yml`.

## Verifying the install

Run as an op:

```
/authlimbo
```

You should see:

```
AuthLimbo 1.0.0 - sub: reload | tp <player>
```

To confirm the DB read path is working, log out a test account, then run
`/authlimbo tp <name>` — the plugin should report the world and
coordinates it pulled from `authme.db`.

## Updating

1. Stop the server.
2. Replace the old jar with the new one.
3. Start the server.

`config.yml` is preserved across updates. Breaking config changes will
be flagged in `CHANGELOG.md` for the affected version.

## Uninstalling

1. Stop the server.
2. Delete `plugins/AuthLimbo-*.jar` and the `plugins/AuthLimbo/`
   folder.
3. Optionally delete the `auth_limbo/` world directory if you no longer
   want the void world. AuthMe will fall back to whatever
   `Settings.RestrictionsSettings.unrestrictedWorlds` / spawn it was
   using before.