> 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/networkeconomy/installation.md).

# Installation

## Requirements

|              |                                                                     |
| ------------ | ------------------------------------------------------------------- |
| **Server**   | Paper / Spigot 1.20.5+ or 1.21.x (`api-version: 1.20`)              |
| **Java**     | 21                                                                  |
| **Database** | MySQL or MariaDB — **required**, shared by every server             |
| **Redis**    | Optional, strongly recommended for networks                         |
| **Vault**    | Optional (`softdepend`) — only needed for third-party Vault plugins |

## Steps

1. Drop the `NetworkEconomy` jar into `plugins/` on **every** server that should share the economy.
2. Start the server once. It will generate `config.yml` and then disable itself if it cannot reach a database — that is expected on the first run.
3. Fill in the `storage` section with your MySQL / MariaDB details, and the `redis` section if you are using Redis.
4. Set a **unique `server-id`** on each server (see below).
5. Start the server again. The schema is created automatically on first successful connection.

```yaml
server-id: "lobby-1"

storage:
  host: "127.0.0.1"
  port: 3306
  database: "networkeconomy"
  username: "root"
  password: "changeme"

redis:
  enabled: true
  host: "127.0.0.1"
  port: 6379
```

{% hint style="danger" %}
`server-id` **must be different on every server of the network.** It identifies the origin server in transaction logs, and it is how a node recognises and ignores its own Redis broadcasts. Two servers sharing an id will ignore each other's balance updates.
{% endhint %}

{% hint style="warning" %}
Point every server at the **same database**. A per-server database defeats the entire purpose — and if two servers use different databases while sharing a Redis channel, they will apply each other's balances on top of unrelated rows.
{% endhint %}

## Database setup

Create an empty database and a user that can create tables in it:

```sql
CREATE DATABASE networkeconomy CHARACTER SET utf8mb4;
CREATE USER 'networkeconomy'@'%' IDENTIFIED BY 'a-strong-password';
GRANT ALL PRIVILEGES ON networkeconomy.* TO 'networkeconomy'@'%';
FLUSH PRIVILEGES;
```

The three tables (`ne_accounts`, `ne_balances`, `ne_transactions`) are created on startup by the bundled `schema.sql`; `{prefix}` is substituted with your configured `table-prefix`. There is nothing to import by hand.

{% hint style="info" %}
Keep the connection pool small — `storage.pool.maximum-pool-size: 10` is plenty. Economy queries are short, and the pool size also determines the plugin's worker-thread count.
{% endhint %}

## Redis setup

Redis is only used for pub/sub cache invalidation — **no balances are stored in it**, so it needs no persistence and losing it never loses money.

```yaml
redis:
  enabled: true
  host: "127.0.0.1"
  port: 6379
  username: ""      # only for ACL users
  password: ""      # empty for no auth
  database: 0
  channel: "networkeconomy:updates"
```

Every server must use the **same `channel`**. If Redis fails to connect at startup the plugin logs a warning and continues in DB-only mode, refreshing caches on a timer instead.

## Vault

If Vault is installed, NetworkEconomy registers itself as the economy provider at the highest priority and logs `Registered NetworkEconomy as the Vault economy provider.` Existing Vault plugins then work unchanged and automatically become network-wide.

{% hint style="warning" %}
Remove any other economy plugin (EssentialsX Economy, CMI economy, …) before installing NetworkEconomy. Two economy providers on one server means Vault plugins may read balances from one and write to the other.
{% endhint %}

## Verifying the setup

* Console shows `NetworkEconomy enabled (server-id: ...).`
* `/balance` returns your starting balance (100 coins by default).
* `/eco give <you> 500` on **server A**, then `/balance` on **server B** — the new value should be visible immediately with Redis enabled.
* `/transactions` shows the `give` you just made, with server A's `server-id` on the entry.

If any of that fails, see [troubleshooting.md](/products/networkeconomy/troubleshooting.md).

## Building from source

Requires JDK 21.

```bash
./gradlew build
# -> build/libs/NetworkEconomy-<version>.jar   (shaded, relocated dependencies)
```