> ## Documentation Index
> Fetch the complete documentation index at: https://nexus-core.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installing Nexus Core

> Install Nexus Core v1.5.1 from source with Maven or from a pre-built Docker Compose stack. Covers prerequisites, build steps, VNC setup, and the web panel.

Nexus Core can be installed in two ways: built from source with Maven, or deployed as a full Docker Compose stack that automatically starts Nexus Core, Redis, and MongoDB together. Both approaches are covered below

## Option A: Manual Installation (Maven)

### Prerequisites

| Requirement | Minimum Version   | Notes                                                        |
| ----------- | ----------------- | ------------------------------------------------------------ |
| Java (JDK)  | 17                | Java 21 recommended (matches the compiler target in pom.xml) |
| Maven       | 3.8+              | Used to build the fat JAR                                    |
| Redis       | Any recent stable | Accessible on the network; port 6379 by default              |
| MongoDB     | Any recent stable | Accessible on the network; port 27017 by default             |

## Step 1: Clone the Repository

```bash theme={null}
git clone https://github.com/mustafabinguldev/nexus-cache-orchestrator.git
cd nexus-cache-orchestrator
```

## Step 2: Set the Signing Key

Set the `NEXUS_SIGNING_KEY` environment variable before building or running. This key is used for HMAC-SHA256 signing on **both** incoming and outgoing Redis messages, so every Spigot server in the network must use the same value.

```bash theme={null}
export NEXUS_SIGNING_KEY="a-long-and-unpredictable-secret-key"
```

<Warning>
  Never commit this key to version control. Use a secrets manager, CI/CD environment variable, or a `.env` file excluded from Git. Rotate it immediately if it is ever exposed.
</Warning>

<Note>
  If `NEXUS_SIGNING_KEY` is not set, both inbound signature verification and outbound message signing are disabled. A one-time warning is logged. This is acceptable only for local development.
</Note>

## Step 3: Build the JAR

```bash theme={null}
mvn clean package -DskipTests
```

The output JAR is placed at:

```text theme={null}
target/nexus-core-4.0.jar
```

## Step 4: Run Nexus Core

```bash theme={null}
java -jar target/nexus-core-4.0.jar
```

Starting from v1.5, Nexus Core launches a **Spring Boot web panel** instead of the legacy Swing dashboard. The web panel is accessible at:

```text theme={null}
http://localhost:8080
```

Use the web panel to enter your Redis and MongoDB connection details and initialize the engine.

## Step 5: Configure the Connection

In the web panel, provide the following:

| Field       | Default                     | Notes                                                  |
| ----------- | --------------------------- | ------------------------------------------------------ |
| Redis Host  | `127.0.0.1`                 | Host or IP; port defaults to 6379                      |
| MongoDB URI | `mongodb://localhost:27017` | Full connection string; supports auth and replica sets |
| Server Port | `8080`                      | Port the web panel and health check endpoint listen on |

Since v1.4.0, these values are persisted to a local config file. Subsequent launches load them automatically, so the configuration step only needs to be completed once.

## Step 6: Verify the Installation

After initialization you should see log output confirming:

* Redis connection established
* MongoDB connection established
* AddonRegistry ready
* Security layer active (if `NEXUS_SIGNING_KEY` is set)

If MongoDB becomes unavailable at runtime, Nexus Core performs a controlled shutdown and logs the reason. Resolve the connectivity issue and restart.

## Running as a Background Service (Linux)

To keep Nexus Core running after you close the terminal, use `nohup` or a systemd unit.

<Tabs>
  <Tab title="nohup">
    ```bash theme={null}
    nohup java -jar target/nexus-core-4.0.jar > nexus.log 2>&1 &
    echo $! > nexus.pid
    ```

    Stop with:

    ```bash theme={null}
    kill $(cat nexus.pid)
    ```
  </Tab>

  <Tab title="systemd">
    Create `/etc/systemd/system/nexus-core.service`:

    ```ini theme={null}
    [Unit]
    Description=Nexus Core Cache Orchestrator
    After=network.target

    [Service]
    User=nexus
    WorkingDirectory=/opt/nexus-core
    ExecStart=/usr/bin/java -jar nexus-core-4.0.jar
    Environment="NEXUS_SIGNING_KEY=your-secret-key"
    Restart=on-failure
    RestartSec=5

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

    Enable and start:

    ```bash theme={null}
    sudo systemctl daemon-reload
    sudo systemctl enable nexus-core
    sudo systemctl start nexus-core
    sudo systemctl status nexus-core
    ```
  </Tab>
</Tabs>

## Troubleshooting

<Accordion title="The web panel is not accessible on port 8080">
  Check that no other process is using port 8080 (`lsof -i :8080`). If you need a different port, set `SERVER PORT` to a free port during first-time configuration, or update the persisted config file.
</Accordion>

<Accordion title="Redis or MongoDB connection fails at startup">
  Verify the host, port, and credentials. For MongoDB, ensure the URI is a valid connection string (e.g. `mongodb://user:pass@host:27017/dbname`). For Redis, confirm `redis-server` is running and reachable from the Nexus Core host.
</Accordion>

<Accordion title="Packets are being rejected with a signature error">
  The `NEXUS_SIGNING_KEY` on Nexus Core and the sending Spigot server must be identical. Set the same key on both sides. Also confirm that NTP is running and server clocks are within 5 minutes of each other.
</Accordion>

<Accordion title="Packets are rejected even with the correct key">
  Timestamp drift is the most common cause. Nexus Core rejects packets older than 5 minutes. Run `ntpdate` or enable an NTP service (`timedatectl set-ntp true`) on all hosts.
</Accordion>

## Option B: Docker Compose Installation

The Docker Compose stack builds Nexus Core from source inside a container and starts **Redis**, **MongoDB**, and **Nexus Core** together, with health checks, persistent volumes, and automatic service discovery.

### Prerequisites

| Requirement                     | Notes                                                                   |
| ------------------------------- | ----------------------------------------------------------------------- |
| Docker Desktop or Docker Engine | Any recent stable version                                               |
| Docker Compose (v2)             | Verify with `docker compose version`                                    |
| A VNC client                    | Required for the initial setup wizard (e.g. RealVNC, TigerVNC, Remmina) |

```bash theme={null}
docker --version
docker compose version
```

### Step 1: Clone the Repository

```bash theme={null}
git clone https://github.com/mustafabinguldev/nexus-cache-orchestrator.git
cd nexus-cache-orchestrator
```

### Step 2: Create a `.env` File

Create a `.env` file in the project root to set credentials and the VNC password:

```env theme={null}
MONGO_ROOT_USER=nexus
MONGO_ROOT_PASSWORD=your_secure_password
VNC_PASSWORD=your_secure_vnc_password
```

<Warning>
  Always use strong, unique passwords in production. Never commit the `.env` file to version control — add it to `.gitignore`.
</Warning>

### Step 3: Build and Start the Stack

```bash theme={null}
docker compose up -d --build
```

Docker pulls the base images, builds Nexus Core from source, and starts three containers:

| Container     | Description                                       |
| ------------- | ------------------------------------------------- |
| `nexus-core`  | The Nexus Core orchestrator (ports 8080 and 5900) |
| `nexus-redis` | Redis 7 with AOF persistence (port 6379)          |
| `nexus-mongo` | MongoDB 7 with a root user (port 27017)           |

Nexus Core only starts after both Redis and MongoDB pass their health checks.

Check that all three containers are running:

```bash theme={null}
docker compose ps
```

### Step 4: Connect via VNC for Initial Setup

On first launch, Nexus Core presents an interactive setup wizard over VNC. Connect your VNC client to:

```text theme={null}
localhost:5900
```

Use the `VNC_PASSWORD` you set in the `.env` file. Inside the VNC session, the setup wizard asks for Redis and MongoDB connection details. Use the **Docker service names** as hostnames — not `localhost`:

| Field       | Value                                                                 |
| ----------- | --------------------------------------------------------------------- |
| Redis Host  | `redis`                                                               |
| MongoDB URI | `mongodb://nexus:nexus_pw@mongo:27017/nexus_core_db?authSource=admin` |
| Server Port | `8080`                                                                |

<Note>
  Inside the Docker network, containers reach each other by service name (`redis`, `mongo`). Using `localhost` here will not work.
</Note>

### Step 5: Access the Web Panel

After completing the setup wizard, open your browser and navigate to:

```text theme={null}
http://localhost:8080
```

The Spring Boot web administration dashboard is now available.

## Exposed Ports

| Service       | Port    | Description                         |
| ------------- | ------- | ----------------------------------- |
| Web Dashboard | `8080`  | Nexus Core web administration panel |
| VNC           | `5900`  | Initial setup environment           |
| Redis         | `6379`  | Redis cache (mapped to host)        |
| MongoDB       | `27017` | MongoDB database (mapped to host)   |

## Useful Docker Commands

```bash theme={null}
# View running containers
docker compose ps

# Stream all logs
docker compose logs -f

# Stream only Nexus Core logs
docker compose logs -f nexus-core

# Stop all services (data is preserved)
docker compose down

# Restart the stack
docker compose restart

# Rebuild after a code update
docker compose up -d --build
```

## Persistent Data

Redis and MongoDB store data in named Docker volumes (`redis-data` and `mongo-data`). Stopping the stack with `docker compose down` preserves all data. To wipe all volumes and start fresh:

```bash theme={null}
docker compose down -v
```

<Warning>
  Running `docker compose down -v` permanently deletes all Redis and MongoDB data. Use it only when you intend a full reset.
</Warning>

## Docker Troubleshooting

<Accordion title="Nexus Core container starts but exits immediately">
  Redis or MongoDB may not have passed their health checks in time. Check their status with `docker compose ps` and inspect their logs with `docker compose logs nexus-redis` or `docker compose logs nexus-mongo`. The `depends_on` health checks require both services to respond before Nexus Core starts.
</Accordion>

<Accordion title="Cannot connect to VNC on port 5900">
  Confirm the container is running (`docker compose ps`) and that no firewall rule is blocking port 5900. If you changed the default VNC port, update the `ports` mapping in `docker-compose.yml` to match.
</Accordion>

<Accordion title="MongoDB authentication fails during setup">
  The default credentials from the `.env` file are `MONGO_ROOT_USER` and `MONGO_ROOT_PASSWORD`. If you changed them, use the updated values in the MongoDB URI. Always include `?authSource=admin` at the end of the URI when using root credentials.
</Accordion>

<Accordion title="Web panel not accessible at port 8080">
  Confirm the setup wizard completed successfully inside the VNC session. The web panel only becomes available after Nexus Core has initialized. Also check that no other service on the host is using port 8080.
</Accordion>

## Docker Security Checklist

Before deploying to production:

* Replace all default credentials in `.env` with strong, unique values.
* Restrict external access to ports 6379 and 27017 using a firewall — they should not be publicly reachable unless required.
* Restrict VNC access (port 5900) to trusted IPs or behind a VPN. The VNC session is only needed for initial setup.
* Protect the web dashboard (port 8080) with HTTPS and access controls.
* Never commit `.env` or any credentials to version control.

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Register your first DataAddon and send your first request.
  </Card>

  <Card title="Configuration" icon="gear" href="/configuration">
    Full reference for all connection parameters and the signing key.
  </Card>
</CardGroup>


## Related topics

- [Configuring Nexus Core](/configuration.md)
- [Nexus Core Changelog](/reference/changelog.md)
- [Request Types in Nexus Core](/concepts/request-types.md)
- [System Architecture of Nexus Core](/concepts/architecture.md)
- [Get Started with Nexus Core](/quickstart.md)