How To Auto-Update Your Paper Minecraft Server (Introducing MineAcademy Endpoint)

				
					#!/usr/bin/env bash

# Auto-update Paper on the 26.1.x minor line.
# Never crosses into 26.2 or any other version group.

# set -e         exit immediately if any command fails (safety net)
# set -u         error if we use an unset variable (catches typos)
# set -o pipefail in cmd1 | cmd2, fail if EITHER fails (not just the last)
set -euo pipefail

# === CONFIG ===

# Which version group to track.
VERSION_GROUP="26.1"

# PaperMC requires a User-Agent.
UA="yourname/1.0 (https://yourserver.com)"

# Where the jar lives. start.sh must reference this exact filename.
JAR="/home/minecraft/server/paper.jar"

# Base URL for the Fill API.
API="https://fill.papermc.io/v3/projects/paper"

# === 1. Get all versions inside our pinned group, newest first ===

# curl flags:
#   -f  fail on HTTP errors (404, 500) instead of writing the error page to disk
#   -s  silent (no progress bar)
#   -S  but still show actual errors. -sS = quiet on success, loud on failure
#   -L  follow redirects (PaperMC redirects to a CDN)
#   -H  add a header
#
# jq flags:
#   -r          raw output (no surrounding quotes on strings)
#   --arg g …   pass a shell variable INTO jq as $g, safely
#
# jq query: .versions[$g] // []      = "give me .versions[26.1], or empty array"
#           | .[]                    = expand the array into separate lines
#
# sort -V -r: -V = version-aware sort (so 26.1.10 comes after 26.1.9, not before),
#             -r = reverse, so newest first.
VERSIONS=$(curl -fsSL -H "User-Agent: $UA" "$API" \
    | jq -r --arg g "$VERSION_GROUP" '.versions[$g] // [] | .[]' \
    | sort -V -r)

# === 2. Walk newest → oldest, take the first one with a STABLE build ===

# We loop because the newest version might only have ALPHA builds out so far.
# We want STABLE only.
for V in $VERSIONS; do
    RESP=$(curl -fsSL -H "User-Agent: $UA" "$API/versions/$V/builds")

    # jq query, broken down:
    #   map(select(.channel=="STABLE"))   keep only stable builds
    #   .[0]                              take the first (newest)
    #   .downloads."server:default".url   drill into nested fields
    #     (the quotes are needed because "server:default" has a colon)
    #   // "null"                         if missing, give the string "null"
    URL=$(echo "$RESP"   | jq -r 'map(select(.channel=="STABLE"))|.[0].downloads."server:default".url // "null"')
    SHA=$(echo "$RESP"   | jq -r 'map(select(.channel=="STABLE"))|.[0].downloads."server:default".checksums.sha256 // "null"')
    BUILD=$(echo "$RESP" | jq -r 'map(select(.channel=="STABLE"))|.[0].id // "null"')

    # Found one? Remember the version and stop looping.
    if [ "$URL" != "null" ]; then
        FOUND="$V"
        break
    fi
done

# If we walked everything and found nothing, bail.
# ${FOUND:-} expands to "" if FOUND is unset — needed because of `set -u`.
if [ -z "${FOUND:-}" ]; then
    echo "No stable build in $VERSION_GROUP"
    exit 1
fi

echo "Latest stable: $FOUND build $BUILD"

# === 3. Already on this build? Skip — don't waste bandwidth ===

# sha256sum FILE prints:   <hash>  <filename>
# cut -d' ' -f1 splits on space, takes field 1 → just the hash.
if [ -f "$JAR" ] && [ "$(sha256sum "$JAR" | cut -d' ' -f1)" = "$SHA" ]; then
    echo "Already up to date."
    exit 0
fi

# === 4. Stage the download in a temp file, verify before swapping ===

# mktemp creates a uniquely-named temp file. XXXXXX gets replaced randomly.
# We put it INSIDE the server folder so the final `mv` is on the same
# filesystem — that makes it atomic (the rename either fully happens or
# doesn't, no half-written state).
TMP=$(mktemp /home/minecraft/server/.paper.XXXXXX.jar)

# trap: register a cleanup command that runs when the script exits,
# even if it crashes. Guarantees we don't leave half-downloaded files behind.
trap 'rm -f "$TMP"' EXIT

# Download.
curl -fsSL -H "User-Agent: $UA" -o "$TMP" "$URL"

# Verify checksum. If it doesn't match, the download was corrupted
# or tampered with — abort before we touch the live jar.
if [ "$(sha256sum "$TMP" | cut -d' ' -f1)" != "$SHA" ]; then
    echo "Checksum mismatch — aborting."
    exit 1
fi

# === 5. Swap atomically: stop, replace, start ===

# Paper docs are explicit: do NOT replace a running jar.
# systemctl stop blocks until the world is saved (our minecraft.service
# types "stop" in the console and waits), so the save is already guaranteed.
# We use full path /bin/systemctl because that's exactly what we
# whitelisted in sudoers. sudo matches paths character-for-character.
sudo /bin/systemctl stop minecraft.service

# Keep one rollback in case the new build is broken.
[ -f "$JAR" ] && cp -f "$JAR" "$JAR.bak"

# The atomic swap. After this line, the live jar IS the new build.
mv "$TMP" "$JAR"

# Cancel the cleanup trap — we don't want to delete the now-live jar.
trap - EXIT

sudo /bin/systemctl start minecraft.service

echo "Updated to $FOUND build $BUILD"