PaperBackup4Discord - Documentation

Install

1. Drop the jar into plugins/ and start the server once
2. Edit plugins/PaperBackupDiscord/config.yml
3. Set webhookUrl to your Discord webhook
4. Restart or run /backupreload

On first run it waits for the server to be fully up, prints the README if applicable, and if the webhook is blank or the default it disables itself.

Config - plugins/PaperBackupDiscord/config.yml

cycleMinutes: 15
readmeDelaySeconds: 5
firstBackupDelaySeconds: 60

webhookUrl: " https://discord.com/api/webhooks/REPLACE_ME "

splitSizeMB: 23
fallbackSplitSizeMB: 7
keepLastSets: 288
label: "Paper-Prod"

serverRootOverride: ""
workRootOverride: ""

useBundled7zip: true
sevenZipOverride: ""

includeOnly: []
excludeFiles:
- "*.log"
- "*.tmp"
- "*.lock"
- "session.lock"

excludeDirs:
- "backup"
- "logs"
- "cache"
- "crash-reports"
- "plugins/dynmap/tiles"
- "plugins/spark"
- "plugins"

skipLockedFiles: true
verbosity: "advanced"

Key notes

• webhookUrl must be set. If blank or left as REPLACE_ME the plugin disables itself
• includeOnly makes a whitelist. If you set it, only those subpaths are copied
• excludeFiles and excludeDirs are checked during the staging copy
• useBundled7zip uses the 7-Zip shipped in the jar. sevenZipOverride lets you point at a system binary instead
• workRoot defaults to plugins/PaperBackupDiscord/work and holds staging/ and output/
• keepLastSets is how many completed backup sets to keep. A set is [.7z.001..N] or a single [.7z]

What gets backed up

By default it copies the server root except for excluded dirs and file patterns.

To back up only worlds:

includeOnly:
- "world"
- "world_nether"
- "world_the_end"

To back up a single plugin’s data while excluding others:

includeOnly:
- "plugins/economy"

To exclude a plugin that locks files:

excludeDirs:
- "plugins/FoxGate/databases"

How uploads work

• 7-Zip compresses the staged copy to work/output/<label>-<timestamp>.7z.*
• The first part uploads to the webhook with a status line. The rest upload without a message
• If Discord says Request entity too large the plugin retries with fallbackSplitSizeMB

Recombine parts
Windows:

cd plugins\PaperBackupDiscord\work\output"..\..\bin\7za.exe" x " YourLabel-YYYY-MM-DD_HH-mm-ss .7z.001"

Linux/macOS:

cd plugins/PaperBackupDiscord/work/output../../bin/7zz x " YourLabel-YYYY-MM-DD_HH-mm-ss .7z.001"

7-Zip will find [.002], [.003], etc automatically.

Logging

• verbosity: advanced prints staged counts, minute countdown, 7-Zip command, and Discord responses
• minimal prints start, finish, and errors
• off prints only critical errors

On boot:

• Prints README if first run, or verbosity is advanced, or webhook is unset
• If webhook is unset it disables itself after printing the README
• First backup runs after firstBackupDelaySeconds. Then it schedules every cycleMinutes

Troubleshooting

• Plugin disabled at boot
  Set a valid webhookUrl, then /backupreload or restart
  
• Request entity too large
  Lower splitSizeMB or rely on fallbackSplitSizeMB
  
• “Skipping locked file …”
  Normal on Windows for live DBs. Leave skipLockedFiles: true, exclude the path, or use the plugin’s own export if it has one
  
• “No archive parts produced”
  With current build this should not happen. Check verbosity: advanced logs for [7z-cmd], [7z-cwd], and [7z-out]
  
• I only want some folders
  Use includeOnly to whitelist exactly the paths you want

Performance tips

• Put workRoot on the same disk as the server root to keep copy fast
• Exclude heavy plugin caches like dynmap tiles
• Tune cycleMinutes to match your risk tolerance and Discord rate limits

Security notes

• The plugin posts to a single Discord webhook you control
• The webhook URL is sensitive. Treat it like a token
• The plugin does not grant op or elevate permissions
• The only external process run is the bundled 7-Zip

Admin quickstart

1. Set webhookUrl
2. Optionally set includeOnly to just the three worlds
3. Leave useBundled7zip: true unless you want to use a system binary
4. Start server, watch for the README and first backup

Minimal config example (worlds only, 10 sets):

label: "A-Minecraft-Server"
webhookUrl: " https://discord.com/api/webhooks/your_webhook_here "
cycleMinutes: 15
firstBackupDelaySeconds: 60
splitSizeMB: 23
fallbackSplitSizeMB: 7
keepLastSets: 10
includeOnly:
- "world"
- "world_nether"
- "world_the_end"
skipLockedFiles: true
verbosity: "minimal"