NoxAeApi

Server Installation & Setup

NoxAeApi Plugin Setup Guide

Step-by-step installation instructions, config.yml guide, NxGate licensing, port security, and plugin integrations for Paper, Spigot, Fabric, and Velocity.

Paper / Purpur / Spigot / BukkitFabric ModVelocity Proxy HubJava 17 / 21+

System Requirements

Java Runtime

Java 17 or Java 21+ LTS is required to run the embedded Javalin & WebSocket server.

Minecraft Server Platform

Compatible with PaperMC, Purpur, Spigot, Bukkit (1.18.x - 1.21.x+), Fabric Loader, and Velocity Proxy.

Supported Optional Plugins

To unlock all endpoints: install Vault or ExcellentEconomy (for economy), LuckPerms (permissions), mcMMO or AuraSkills (RPG progression), and PlaceholderAPI.

Step-by-Step Installation

1

Download & Place JAR

Download the official NoxAeApi JAR and place it into your server’s plugins/ folder (or mods/ for Fabric).

2

Start Server to Generate Config

Start your server to let NoxAeApi generate default plugins/NoxAeApi/config.yml and sqlite database files.

3

Edit config.yml & Set License Key

Configure server port (default 4567), authorization key, and paste your NxGate license key.

4

Restart Server & Allow Firewall Port

Restart the server and ensure your hosting firewall allows inbound traffic on the configured port.

Directory Layout
# Bukkit / Spigot / Paper / Purpur
server/
├── plugins/
│   ├── NoxAeApi.jar
│   └── NoxAeApi/
│       ├── config.yml
│       └── logs/
│           └── audit.log
└── server.properties

# Fabric Loader
server/
├── mods/
│   ├── fabric-api.jar
│   ├── NoxAeApi-Fabric.jar
│   └── impactor.jar (optional economy)
└── config/
    └── noxaeapi/
        └── config.json

# Velocity Proxy Hub
proxy/
├── plugins/
│   ├── NoxAeApi-Velocity.jar
│   └── noxaeapi-velocity/
│       └── config.toml
└── velocity.toml

NxGate License Activation

NxGate performs cryptographic offline validation with periodic heartbeat checks.

How to Obtain Your License Key:

  • Log in to your NxGate dashboard customer portal.
  • Copy your NoxAeApi serial key (format: NX-XXXX-XXXX-XXXX).
  • Paste it into license-key: "..." in plugins/NoxAeApi/config.yml.

Full config.yml Reference

Complete configuration schema for server port, API keys, CORS policies, rate limiting, and WebSocket channels:

plugins/NoxAeApi/config.yml
# plugins/NoxAeApi/config.yml
# ── Lisensi NxGate ───────────────────────────────────────────────────────────
# Masukkan license key dari dashboard NxGate. Plugin tidak berjalan tanpa key valid.
license-key: 'MASUKKAN_LICENSE_KEY_DISINI'

# Port HTTP REST API server
port: 4567

# Wajibkan otentikasi header API key ("key: <rahasia>")
useKeyAuth: true

# Normalisasi pesan format Minecraft color codes (§ -> &)
normalizeMessages: true

# ── Authentication ────────────────────────────────────────────────────────────
# 1. Simple single key (default — aktif jika bagian 'keys:' di bawah dikomentari).
# Ganti nilai ini sebelum menyalakan server produksi!
key: 'ganti_dengan_kunci_rahasia_anda_yang_panjang'

# 2. Multi-key RBAC system (opsional — hapus komentar untuk mengaktifkan).
# Ketika bagian 'keys:' ini aktif, 'key' tunggal di atas akan diabaikan.
# keys:
#   admin:
#     value: 'rahasia_admin_penuh'
#     read-only: false
#     allowed-endpoints: [] # Kosong = seluruh endpoint diizinkan
#   dashboard:
#     value: 'rahasia_viewer_dashboard'
#     read-only: true       # Hanya request GET yang diizinkan
#     allowed-endpoints:
#       - '/v1/players'
#       - '/v1/server'
#       - '/v1/economy/*'
#   luckperms-bot:
#     value: 'rahasia_bot_discord'
#     read-only: false
#     allowed-endpoints:
#       - '/v1/luckperms/*'
#       - '/v1/chat/broadcast'

# ── TLS / HTTPS ───────────────────────────────────────────────────────────────
tls:
  enabled: false
  keystore: keystore.jks
  keystorePassword: 'password_keystore'
  sni: false

# ── CORS Origins ──────────────────────────────────────────────────────────────
# Daftar domain yang diizinkan mengakses API via browser ("*" untuk semua origin)
corsOrigins:
  - '*'

# ── Rate Limiting ─────────────────────────────────────────────────────────────
rateLimit:
  enabled: false
  # Maksimum request per menit per IP atau API key
  requestsPerMinute: 120

# ── Security & Audit ──────────────────────────────────────────────────────────
security:
  # IP Whitelist — hanya izinkan IP spesifik (misal server dashboard/web backend)
  ip-whitelist:
    enabled: false
    allowed-ips:
      - "127.0.0.1"
      - "203.0.113.10"

  # Audit log — mencatat setiap request & action ke plugins/NoxAeApi/logs/audit.log
  audit-log:
    enabled: true

# ── Discord Notifications ─────────────────────────────────────────────────────
discord:
  enabled: false
  webhook-url: "https://discord.com/api/webhooks/..."
  server-name: "Survival Production"
  notify-on:
    - unauthorized-access
    - exec-command
    - op-player
    - deop-player
    - whitelist-change
    - ip-blocked

# ── WebSocket Real-Time Events ────────────────────────────────────────────────
# Event game waktu-nyata dialirkan ke klien WebSocket: ws://<host>:<port>/v1/ws/events?key=...
# Events: player_join, player_quit, player_chat, player_death, player_kick
websocket:
  events:
    enabled: true

# ── Misc & Integrations ───────────────────────────────────────────────────────
debug: false
maxLogLines: 500
disable-swagger: false

# Aktifkan jika plugin NoxAuth terpasang di server
noxauth:
  enabled: false

# Blokir endpoint sensitif agar tidak bisa diakses sama sekali
blocked-paths:
# - /v1/server/exec

# ── Proxy Registration (Velocity Network Hub) ─────────────────────────────────
# Aktifkan di server backend (survival, lobby, skyblock) untuk mendaftarkan diri
# ke proxy hub NoxAeApi-Velocity secara otomatis via WebSocket.
proxy-registration:
  enabled: false
  proxy-url: "ws://10.0.0.1:5000/network/register"
  proxy-key: "proxy_secret_change_me"
  node-id: "survival"
  node-label: "Survival Server"
  heartbeat-interval-seconds: 10
  reconnect:
    enabled: true
    initial-delay-seconds: 1
    max-delay-seconds: 30

Network & Reverse Proxy (SSL/TLS)

To secure your REST API with HTTPS/WSS, route traffic through Nginx, Caddy, or Cloudflare Tunnel:

Nginx Configuration

/etc/nginx/sites-available/noxaeapi
# /etc/nginx/sites-available/noxaeapi
server {
    listen 443 ssl http2;
    server_name api.serverminecraft.com;

    ssl_certificate /etc/letsencrypt/live/api.serverminecraft.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.serverminecraft.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:4567;
        proxy_http_version 1.1;

        # WebSocket support headers (untuk /v1/ws/console dan /v1/ws/events)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Timeout buffer untuk WebSocket log streaming
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}

Caddy Configuration

Caddyfile
# Caddyfile — Otomatis HTTPS Let's Encrypt
api.serverminecraft.com {
    reverse_proxy 127.0.0.1:4567
}

Cloudflare Proxy Notes

Ensure WebSocket connections and HTTP Authorization headers are passed through without modification.

Connecting Integrations

Vault & Multi-Currency

Enables /v1/economy/* balance, deposit, transfer, and multi-currency endpoints.

LuckPerms RBAC

Enables /v1/luckperms/* permission checking, group inheritance, and track manipulation.

mcMMO & AuraSkills

Enables /v1/skills/* skill level inspection and leaderboard ranking queries.

PlaceholderAPI

Enables /v1/placeholders/replace dynamic placeholder parsing.

Velocity Proxy Hub Setup

Install NoxAeApi-Velocity.jar in your Velocity proxy plugins folder to enable proxy-wide player aggregation and request forwarding.

WebSocket Node Heartbeats

Backend servers connect to the Velocity hub via WebSocket and register their node IDs automatically.

Verification & Next Steps

Verify that your NoxAeApi REST server is online and responding to authenticated HTTP requests:

Terminal
# 1. Tes Ping Health Check
curl http://localhost:4567/v1/ping -H "key: ganti_dengan_kunci_rahasia_anda_yang_panjang"
# Output: "pong!"

# 2. Cek Informasi Server
curl http://localhost:4567/v1/server -H "key: ganti_dengan_kunci_rahasia_anda_yang_panjang"

# 3. Verifikasi dengan noxae CLI
noxae server ping