Servoy Gold Plugin Sync

Keeps every developer's local Servoy plugin folder automatically in sync with a central "Gold" share – without touching private or unreleased plugins.

---

How it works

K:\SERVOY_GOLD\                        ← central network share (Gold Maintainer manages this)
  plugins\
    servoy-2025.12.1.4123\
      manifest.json                    ← list of every team plugin + SHA-256 hash
      files\                           ← the actual .jar files

Each developer's machine:
  plugins_sync.py  reads the manifest and syncs the local folder
  start-servoy.cmd / start-servoy.sh   calls the sync, then launches Servoy

Managed plugins (listed in the manifest) are installed, updated, or quarantined automatically.
Unmanaged / private plugins are never touched.

---

Repository structure

svy-gold-script/
│
├── tools/
│   ├── plugins_sync.py        ← sync client (all platforms)
│   ├── clean_quarantine.py    ← remove old quarantine folders
│   ├── build_manifest.py      ← manifest generator (Gold Maintainer only)
│   ├── start-servoy.cmd       ← Servoy launcher for Windows
│   └── start-servoy.sh        ← Servoy launcher for macOS / Linux
│
└── docs/
    ├── example.servoy-plugin-sync.json   ← config template
    ├── docs_servoy-plugin-sync.md        ← full architecture reference
    ├── docs_plugins_sync.md              ← plugins_sync.py reference
    ├── docs_clean_quarantine.md          ← clean_quarantine.py reference
    ├── docs_build_manifest.md            ← build_manifest.py reference
    ├── docs_start-servoy-cmd.md          ← start-servoy.cmd reference
    ├── docs_start-servoy-sh.md           ← start-servoy.sh reference
    └── *_de.md                           ← German versions of all docs above

---

Getting Started – Developer

You only need plugins_sync.py and the launcher for your OS.
The Gold Maintainer handles the share and the manifest.

Prerequisites

Tool	Where to get it
Python 3.10+	https://python.org – tick "Add to PATH" on Windows
Access to K:\SERVOY_GOLD\	Ask your admin to map the network share
Servoy installed locally	Your existing installation

---

Step 1 – Get the scripts

Clone this repo (or download the ZIP) to a permanent location on your machine, for example:

Windows:

C:\dev\servoy-gold-sync\

macOS / Linux:

~/dev/servoy-gold-sync/

---

Step 2 – Create your personal config file

Run the interactive setup wizard:

Windows:

python C:\dev\servoy-gold-sync\tools\plugins_sync.py --init-config

macOS / Linux:

python3 ~/dev/servoy-gold-sync/tools/plugins_sync.py --init-config

The wizard walks you through 6 steps: display name, servoy_home, gold_root, servoy_version, mode, and optional private_plugins patterns. It validates each path, auto-detects the Servoy version, and writes the config automatically.

Tip: Re-running --init-config on an existing config pre-fills all current values as defaults – useful to change a single field.

Multiple Servoy installations

If you have more than one Servoy version installed (stable, nightly, legacy, …), create a named profile for each:

python ... plugins_sync.py --init-config --profile stable
python ... plugins_sync.py --init-config --profile nightly

Each profile is stored as %USERPROFILE%\.servoy-sync\<name>.json. When you launch Servoy via start-servoy.cmd and multiple profiles exist, an interactive picker is shown:

  ────────────────────────────────────────────────────────────────
  Which Servoy would you like to start?
  Use ↑↓ arrows, Enter to confirm, Ctrl+C to abort.
  ────────────────────────────────────────────────────────────────
  ▶ stable    2025.12.1.4123       C:\Servoys\2025.12\
    nightly   2026.03.0.0001       C:\Servoys\nightly\
  ────────────────────────────────────────────────────────────────

Private plugins

Plugins not listed in the Gold Share manifest are automatically quarantined on the next sync — unless you mark them as private in your config:

{
  "private_plugins": ["hvo-pdf.jar", "drafts/*"]
}

Patterns use fnmatch syntax: * matches anything, ? matches one character, dir/* matches all files under dir/. Private plugins are never touched by the sync.

---

Step 3 – Create a launcher shortcut

Replace your existing Servoy shortcut with the wrapper script.

Windows – create a Desktop shortcut:

$ws  = New-Object -ComObject WScript.Shell
$lnk = $ws.CreateShortcut("$env:USERPROFILE\Desktop\Servoy.lnk")
$lnk.TargetPath       = "C:\dev\servoy-gold-sync\tools\start-servoy.cmd"
$lnk.WorkingDirectory = "C:\dev\servoy-gold-sync\tools"
$lnk.Save()

macOS / Linux – make the script executable:

chmod +x ~/dev/servoy-gold-sync/tools/start-servoy.sh

Then create an alias or a launcher pointing to start-servoy.sh.

---

That's it

From now on:

1. Open Servoy via start-servoy.cmd (Windows) or start-servoy.sh (macOS/Linux).
2. If you have multiple profiles, pick the one you want with the arrow keys.
3. The sync runs automatically and prints what it did.
4. If the sync fails for any reason (share offline, file locked), you will see a warning. Servoy still starts.

You can also sync or launch directly:

rem Sync only (no Servoy start)
python tools/plugins_sync.py --profile stable

rem Sync + launch (same as the start script)
python tools/plugins_sync.py --launch

---

Getting Started – Gold Maintainer

You manage the share and regenerate the manifest whenever plugins change.

Step 1 – Set up the share structure

On K:\SERVOY_GOLD\ create:

K:\SERVOY_GOLD\
  plugins\
    servoy-2025.12.1.4123\
      files\          ← copy all team plugin .jar files here
      manifest.json   ← generated by build_manifest.py

Step 2 – Copy team plugins into files\

Place every plugin the whole team should have into files\. Subdirectories are supported.

Step 3 – Generate the manifest

python C:\dev\servoy-gold-sync\tools\build_manifest.py ^
    --files-dir   "K:\SERVOY_GOLD\plugins\servoy-2025.12.1.4123\files" ^
    --out         "K:\SERVOY_GOLD\plugins\servoy-2025.12.1.4123\manifest.json" ^
    --servoy-version "2025.12.1.4123"

Step 4 – Communicate changes

Tell the team what changed (Slack/Teams message is fine). Each developer will pick up the changes automatically at their next Servoy start.

Updating plugins later

1. Update / add / remove files in files\.
2. Re-run build_manifest.py to regenerate the manifest.
3. Done – no action needed from developers.

---

Troubleshooting

Problem	Solution
No config profiles found	Run python plugins_sync.py --init-config to create your first profile
Config file not found	Run python plugins_sync.py --init-config
Gold Share root is not accessible	Map K:\ in Windows Explorer; on macOS/Linux mount the share
Python 3 not found	Install Python 3 and add it to PATH
Sync finished with issues (exit code: 2)	Check the log at <servoy_home>\application_server\plugins\gold_plugins_sync.log
File locked / permission error	Close Servoy fully, then run the launcher again
Wrong plugins after update	Check servoy_version in your config matches the current version
Private plugin got quarantined	Add it to private_plugins in your config: ["myplugin.jar"]

Check sync status without running a sync

python tools/plugins_sync.py --status

Shows each managed plugin as OK, MISSING, or OUTDATED – without making any changes. Exit 0 = everything up-to-date, exit 2 = action needed.

Clean up old quarantine folders

Plugins that were removed from the manifest are moved to application_server/plugins__quarantine/YYYY-MM-DD/ – never permanently deleted at sync time. To remove folders older than 30 days:

python tools/clean_quarantine.py

Or preview first:

python tools/clean_quarantine.py --dry-run

See clean_quarantine.py reference for details.

---

Detailed documentation

• Architecture & design decisions
• plugins_sync.py reference
• clean_quarantine.py reference
• build_manifest.py reference
• start-servoy.cmd reference
• start-servoy.sh reference