# 🔁 Redis Setup

It is optional for simple single-proxy setups, but highly recommended for production networks, multi-proxy networks, and setups that need shared online data.

***

### When Should You Use Redis?

You should enable Redis if your network needs:

* Multiple Velocity proxies
* Global online player counts
* Proxy online player counts
* Server online player counts
* Cross-proxy player presence
* Shared player snapshots
* Friends online status
* Staff synchronization
* Synced manual announcements
* Synced donation broadcasts
* PlaceholderAPI expansion support for backend lobbies

{% hint style="info" %}
If your network only uses one Velocity proxy and does not need shared data, Redis may not be required.
{% endhint %}

***

### Redis Configuration

Redis is configured in:

```
plugins/NexusProxy/nexusproxy.yml
```

Example configuration:

```yaml
storage:
  redis:
    enabled: true
    host: "127.0.0.1"
    port: 6379
    password: ""
    database: 0
    channel_prefix: "nexusproxy"
```

***

### enabled

Controls whether Redis support is enabled.

```yaml
enabled: true
```

Set it to `true` to enable Redis.

Set it to `false` if you do not want to use Redis.

```yaml
enabled: false
```

***

### host

The Redis server host.

Example for a local Redis server:

```yaml
host: "127.0.0.1"
```

Example for an external Redis server:

```yaml
host: "redis.yournetwork.com"
```

***

### port

The Redis server port.

Default Redis port:

```yaml
port: 6379
```

***

### password

The Redis password.

If your Redis server does not use authentication, leave it empty:

```yaml
password: ""
```

If your Redis server requires a password, configure it here:

```yaml
password: "your-password"
```

{% hint style="warning" %}
Never share your Redis password publicly.

Do not post your full `nexusproxy.yml` configuration in public support channels without removing private credentials first.
{% endhint %}

***

### database

The Redis database index used by NexusProxy.

Example:

```yaml
database: 0
```

If you use the same Redis server for multiple projects, you can use a different database index.

Example:

```yaml
database: 1
```

***

### channel\_prefix

The Redis channel prefix is used to separate NexusProxy data from other Redis-based systems.

Default:

```yaml
channel_prefix: "nexusproxy"
```

All NexusProxy proxies in the same network should use the same `channel_prefix`.

{% hint style="warning" %}
If your proxies use different `channel_prefix` values, they will not synchronize correctly.
{% endhint %}

***

### Multi-Proxy Setup

If your network has multiple Velocity proxies, each proxy must use:

* The same Redis host
* The same Redis port
* The same Redis password
* The same Redis database
* The same Redis channel prefix
* A different `cluster.proxy_id`

Correct example:

```yaml
# Proxy 1
cluster:
  proxy_id: "Proxy-1"
  proxy_name: "Proxy 1"

storage:
  redis:
    enabled: true
    host: "127.0.0.1"
    port: 6379
    password: ""
    database: 0
    channel_prefix: "nexusproxy"
```

```yaml
# Proxy 2
cluster:
  proxy_id: "Proxy-2"
  proxy_name: "Proxy 2"

storage:
  redis:
    enabled: true
    host: "127.0.0.1"
    port: 6379
    password: ""
    database: 0
    channel_prefix: "nexusproxy"
```

{% hint style="danger" %}
Do not use the same `cluster.proxy_id` on multiple proxies.

Every proxy must have a unique proxy ID.
{% endhint %}

***

### Correct vs Incorrect Setup

#### Correct

```yaml
# Proxy 1
cluster:
  proxy_id: "Proxy-1"

# Proxy 2
cluster:
  proxy_id: "Proxy-2"
```

Both proxies use different IDs.

#### Incorrect

```yaml
# Proxy 1
cluster:
  proxy_id: "Proxy"

# Proxy 2
cluster:
  proxy_id: "Proxy"
```

Both proxies use the same ID.

This can break:

* Global online counts
* Proxy online counts
* Player presence
* Friends online status
* PlaceholderAPI expansion data
* Cross-proxy synchronization

***

### Features That Use Redis

Redis can be used by several NexusProxy systems.

| Feature                  | Why Redis Is Used                                     |
| ------------------------ | ----------------------------------------------------- |
| Global online count      | Tracks online players across all proxies.             |
| Proxy online count       | Tracks players connected to each proxy.               |
| Server online count      | Tracks players on backend servers.                    |
| Friends                  | Used for online/offline friend status across proxies. |
| Staff systems            | Helps synchronize staff-related data between proxies. |
| Announcer                | Can synchronize manual announcement sends.            |
| Donations                | Can replicate donation broadcasts across proxies.     |
| PlaceholderAPI Expansion | Reads shared online and friends data from Redis.      |

***

### PlaceholderAPI Expansion

If you use the NexusProxy PlaceholderAPI expansion on backend lobby servers, the expansion must use the same Redis settings as NexusProxy.

This includes:

* Host
* Port
* Password
* Database
* Channel prefix

Velocity plugin:

```yaml
storage:
  redis:
    enabled: true
    host: "127.0.0.1"
    port: 6379
    password: ""
    database: 0
    channel_prefix: "nexusproxy"
```

PlaceholderAPI expansion:

```yaml
redis:
  enabled: true
  host: "127.0.0.1"
  port: 6379
  password: ""
  database: 0
  channel_prefix: "nexusproxy"
```

{% hint style="warning" %}
If the PlaceholderAPI expansion uses different Redis settings, placeholders such as global online, proxy online, server online, and friends online may return `0` or incorrect values.
{% endhint %}

***

### Checking Redis Status

After configuring Redis, restart your proxy or reload NexusProxy.

Then run:

```
/nexusproxy storage
```

Aliases:

```
/nproxy storage
/np storage
```

Use this command to confirm whether Redis is connected correctly.

***

### Common Redis Issues

#### Global online count returns 0

Check that:

* Redis is enabled on every proxy.
* Every proxy uses the same Redis settings.
* Every proxy uses the same `channel_prefix`.
* Every proxy has a unique `cluster.proxy_id`.

***

#### PlaceholderAPI expansion returns 0

Check that:

* Redis is enabled in NexusProxy.
* Redis is enabled in the PlaceholderAPI expansion.
* The expansion uses the same Redis settings as NexusProxy.
* The expansion uses the same `channel_prefix`.
* The backend server has the NexusProxy PlaceholderAPI expansion installed correctly.

***

#### Proxies do not synchronize

Check that:

* Both proxies can connect to Redis.
* Redis host and port are correct.
* The password is correct.
* The database index is the same.
* The `channel_prefix` is the same.
* The `proxy_id` is different on every proxy.

***

#### Redis authentication fails

Check that:

* The Redis password is correct.
* The Redis server actually requires a password.
* The password is not accidentally surrounded by extra spaces.
* The proxy can reach the Redis server.

***

### Recommended Setup

For most production networks, use this approach:

```yaml
cluster:
  proxy_id: "Proxy-1"
  proxy_name: "Proxy 1"

storage:
  redis:
    enabled: true
    host: "127.0.0.1"
    port: 6379
    password: ""
    database: 0
    channel_prefix: "nexusproxy"
```

Then, on every additional proxy:

* Keep the same Redis settings.
* Change only `cluster.proxy_id`.
* Optionally change `cluster.proxy_name`.

Example:

```yaml
cluster:
  proxy_id: "Proxy-2"
  proxy_name: "Proxy 2"
```

***

### Final Checklist

Before asking for support, verify:

* Redis is enabled.
* Redis host is correct.
* Redis port is correct.
* Redis password is correct.
* Redis database is correct.
* Redis channel prefix matches on all proxies.
* Each proxy has a unique `cluster.proxy_id`.
* `/nexusproxy storage` shows Redis as connected.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://nexusproxy.nemesismc.net/redis-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.