minecraft-server/docs/ITZG-CUSTOM-JAR-PERSISTENCE.md

itzg/minecraft-server — Custom Plugin Jar Persistence

Date: 2026-05-07 Context: ChatChat-1.0.0-SNAPSHOT-racked-1.jar was dropped manually into /data/plugins/ and disappeared after the next container restart.

---

1. Why the ChatChat jar disappeared

itzg's entrypoint runs this sequence on every start (when REMOVE_OLD_MODS=TRUE):

1. Wipe — every file in /data/plugins/ matching REMOVE_OLD_MODS_INCLUDE and not matching REMOVE_OLD_MODS_EXCLUDE is deleted.
2. Download — every URL in PLUGINS and every Modrinth project in MODRINTH_PROJECTS is fetched into /data/plugins/.
3. Copy — anything listed in COPY_PLUGINS_SRC (or container paths inside PLUGINS) is rsynced in.

Our current compose has:

REMOVE_OLD_MODS: "true"
REMOVE_OLD_MODS_INCLUDE: "*.jar"
REMOVE_OLD_MODS_EXCLUDE: "AuthLimbo*.jar"

So step 1 deletes every *.jar except AuthLimbo*.jar. The hand-placed ChatChat jar was not in any download list and not in the exclude glob, so it was nuked and never re-downloaded. AuthLimbo survives only because we explicitly excluded it.

This is documented behaviour, not a bug — itzg's design assumes plugins are declarative, sourced from URLs/Modrinth/COPY_PLUGINS_SRC, never hand-dropped.

2. Three mechanisms to make custom jars persist

#	Mechanism	How
A	REMOVE_OLD_MODS_EXCLUDE glob	Add ChatChat*.jar to the exclude list. Quick but fragile — depends on filename and only protects already-present files; doesn't handle re-deploy on a fresh volume.
B	COPY_PLUGINS_SRC bind-mount	Mount a host dir of custom jars read-only at e.g. /plugins-custom, set COPY_PLUGINS_SRC=/plugins-custom. Entrypoint copies them in after the wipe. Survives wipes, version-controllable, declarative.
C	PLUGINS URL → Forgejo Release	Upload the jar as a Forgejo Release asset, add the download URL to the existing PLUGINS list. Same flow as EssentialsX/spark already use.

Note: PLUGINS also accepts container paths directly (e.g. PLUGINS=/plugins-custom/ChatChat.jar), so mechanism B can collapse into the existing PLUGINS env if preferred.

3. Recommended path for racked.ru — Mechanism B

COPY_PLUGINS_SRC is the cleanest fit:

• Custom jars live in the repo (or /opt/docker/minecraft-custom-plugins/), so they're under version control / backup.
• No external host dependency (Forgejo could be down — bind mount can't be).
• Build artefacts from staging/chatchat/ drop straight into the mounted dir.

docker-compose.yml diff

       MODRINTH_LOADER: paper
       SPIGET_RESOURCES: ""
       REMOVE_OLD_MODS: "true"
       REMOVE_OLD_MODS_INCLUDE: "*.jar"
-      REMOVE_OLD_MODS_EXCLUDE: "AuthLimbo*.jar"
+      REMOVE_OLD_MODS_EXCLUDE: "AuthLimbo*.jar,ChatChat*.jar"
+      COPY_PLUGINS_SRC: "/plugins-custom"
     volumes:
       - /opt/docker/minecraft:/data
+      - /opt/docker/minecraft-custom-plugins:/plugins-custom:ro

Then on the host:

sudo mkdir -p /opt/docker/minecraft-custom-plugins
sudo cp staging/chatchat/ChatChat-1.0.0-SNAPSHOT-racked-1.jar \
        /opt/docker/minecraft-custom-plugins/
sudo cp /opt/docker/minecraft/plugins/AuthLimbo-*.jar \
        /opt/docker/minecraft-custom-plugins/   # optional: source-of-truth
sudo chown -R 1000:1000 /opt/docker/minecraft-custom-plugins
docker compose up -d --force-recreate mc

The EXCLUDE line still lists ChatChat*.jar so that if the bind mount ever vanishes, an existing copy in /data/plugins/ isn't wiped — belt and braces.

4. Bonus — Forgejo Release upload procedure (mechanism C)

If you'd rather host the jar at git.s8n.ru (e.g. for cobblestone or a friend's box without the bind mount):

# 1. Tag and push
cd staging/chatchat
git tag -a chatchat-racked-1 -m "ChatChat racked build 1"
git push origin chatchat-racked-1

# 2. Create release + upload asset (uses Forgejo PAT from ~/.config/veilor-forgejo)
TOKEN=$(cat ~/.config/veilor-forgejo/pat)
curl -X POST \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/json" \
  https://git.s8n.ru/api/v1/repos/s8n/minecraft-server/releases \
  -d '{"tag_name":"chatchat-racked-1","name":"ChatChat racked-1","draft":false}'

RELEASE_ID=$(curl -s -H "Authorization: token $TOKEN" \
  https://git.s8n.ru/api/v1/repos/s8n/minecraft-server/releases/tags/chatchat-racked-1 \
  | jq -r .id)

curl -X POST \
  -H "Authorization: token $TOKEN" \
  -H "Content-Type: application/java-archive" \
  --data-binary @ChatChat-1.0.0-SNAPSHOT-racked-1.jar \
  "https://git.s8n.ru/api/v1/repos/s8n/minecraft-server/releases/$RELEASE_ID/assets?name=ChatChat-1.0.0-SNAPSHOT-racked-1.jar"

Then add to compose:

PLUGINS: |
  ...existing...
  https://git.s8n.ru/s8n/minecraft-server/releases/download/chatchat-racked-1/ChatChat-1.0.0-SNAPSHOT-racked-1.jar  

References

• itzg docs: https://docker-minecraft-server.readthedocs.io/en/latest/mods-and-plugins/
• Source: https://github.com/itzg/docker-minecraft-server/blob/master/docs/mods-and-plugins/index.md
• Issue #310 (COPY_PLUGINS_SRC behaviour): https://github.com/itzg/docker-minecraft-server/issues/310