Installing Nexus Core

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

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.

export NEXUS_SIGNING_KEY="a-long-and-unpredictable-secret-key"

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.

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.

Step 3: Build the JAR

mvn clean package -DskipTests

The output JAR is placed at:

target/nexus-core-4.0.jar

Step 4: Run Nexus Core

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:

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.

nohup
systemd

nohup java -jar target/nexus-core-4.0.jar > nexus.log 2>&1 &
echo $! > nexus.pid

Stop with:

kill $(cat nexus.pid)

Create /etc/systemd/system/nexus-core.service:

[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:

sudo systemctl daemon-reload
sudo systemctl enable nexus-core
sudo systemctl start nexus-core
sudo systemctl status nexus-core

Troubleshooting

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.

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.

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.

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.

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)

docker --version
docker compose version

Step 1: Clone the Repository

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:

MONGO_ROOT_USER=nexus
MONGO_ROOT_PASSWORD=your_secure_password
VNC_PASSWORD=your_secure_vnc_password

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

Step 3: Build and Start the Stack

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:

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:

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`

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

Step 5: Access the Web Panel

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

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

# 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:

docker compose down -v

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

Docker Troubleshooting

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.

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.

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.

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.

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

Quickstart

Configuration

Full reference for all connection parameters and the signing key.

Get Started

Core Concepts

Building Addons

Reference

Installing Nexus Core

Option A: Manual Installation (Maven)

Prerequisites

Step 1: Clone the Repository

Step 2: Set the Signing Key

Step 3: Build the JAR

Step 4: Run Nexus Core

Step 5: Configure the Connection

Step 6: Verify the Installation

Running as a Background Service (Linux)

Troubleshooting

Option B: Docker Compose Installation

Prerequisites

Step 1: Clone the Repository

Step 2: Create a `.env` File

Step 3: Build and Start the Stack

Step 4: Connect via VNC for Initial Setup

Step 5: Access the Web Panel

Exposed Ports

Useful Docker Commands

Persistent Data

Docker Troubleshooting

Docker Security Checklist

Next Steps

Quickstart

Configuration

​Option A: Manual Installation (Maven)

​Prerequisites

​Step 1: Clone the Repository

​Step 2: Set the Signing Key

​Step 3: Build the JAR

​Step 4: Run Nexus Core

​Step 5: Configure the Connection

​Step 6: Verify the Installation

​Running as a Background Service (Linux)

​Troubleshooting

​Option B: Docker Compose Installation

​Prerequisites

​Step 1: Clone the Repository

​Step 2: Create a .env File

​Step 3: Build and Start the Stack

​Step 4: Connect via VNC for Initial Setup

​Step 5: Access the Web Panel

​Exposed Ports

​Useful Docker Commands

​Persistent Data

​Docker Troubleshooting

​Docker Security Checklist

​Next Steps

Quickstart

Configuration

Option A: Manual Installation (Maven)

Prerequisites

Step 1: Clone the Repository

Step 2: Set the Signing Key

Step 3: Build the JAR

Step 4: Run Nexus Core

Step 5: Configure the Connection

Step 6: Verify the Installation

Running as a Background Service (Linux)

Troubleshooting

Option B: Docker Compose Installation

Prerequisites

Step 1: Clone the Repository

Step 2: Create a `.env` File

Step 3: Build and Start the Stack

Step 4: Connect via VNC for Initial Setup

Step 5: Access the Web Panel

Exposed Ports

Useful Docker Commands

Persistent Data

Docker Troubleshooting

Docker Security Checklist

Next Steps