These docs have been generated using AI. Expect inaccuracies until we remove this banner.
Packages: Distribution Made Easy
Packages are mini-installer plugins that bundle Troy Client with your plugins. When users install a Package, they get everything they need in one step—no manual Troy Client installation required.
Plugins vs Packages:
Plugins are for updates. Packages are for distribution.
- Use Plugins to serve updates to users who already have Troy Client
- Use Packages to distribute your plugins to new users
Packages always fetch the latest version of bundled plugins at install time. You don't need to rebuild Packages when you release plugin updates.
Why Use Packages?
When you distribute plugins directly, users need Troy Client installed first. That means:
- User must find and install Troy Client separately
- User must configure it to connect to your repository
- Only then can they receive updates for your plugins
With Packages:
- User installs your Package (under 10 KB!)
- Package installs Troy Client + your plugins automatically
- Done. Updates flow automatically.
Packages reduce a multi-step process to a single install. And since Packages are tiny—just a few kilobytes—users can upload them to their website even on spotty connections. Unlike a ton of users on shoddy wifi, their WordPress site, which ought to have a stable connection, can easily fetch the larger plugin files. No more failed uploads!
Creating a Package
Create a New Package Post
In your WordPress admin:
- Go to Packages → Add New Package (Troy Server's interface)
- Enter a title for your package (e.g., "My Plugin Suite Installer")
Set the Package Slug
Below, set the package slug (e.g., example-package). This becomes the download identifier.
Add Plugins
In the Plugins meta box:
- Click Add Plugin
- Select plugins from your repository
- Configure each plugin:
- Activate — Activate after installation
- Network — Network-activate on multisite
- Overwrite — Replace existing plugin if present
- Overwrite Troy — Replace even if already managed by Troy
Configure Settings
In the Settings meta box:
| Setting | Description |
|---|---|
| Install Timeout | Maximum seconds for installation (default: 30) |
| Deactivate on Completion | Deactivate Package after install (recommended) |
| Delete on Completion | Delete Package after install |
| Notice Severity | Control installer feedback: detailed, verbose, or silent |
Note:
Recommended settings: Deactivate on completion, but don't delete. Users can delete manually if they want, and WordPress Site Health will remind them. This gives users control while keeping things tidy.
Publish
Click Publish. Your Package is now available at:
https://your-server.com/package/get/zip/example-package
How Packages Work
When a user activates your Package:
-
Troy Client Installation
- The installer checks if Troy Client is already present
- If not, it downloads and installs Troy Client from the official repository
- Troy Client is always installed first—it's a forced dependency
-
Plugin Installation
- For each bundled plugin, the installer fetches the latest version from your repository
- Plugins are installed and optionally activated
- Existing plugins can be overwritten based on your settings
-
Cleanup
- The Package deactivates itself (if configured)
- Users can delete the Package manually
Troy Client is Required:
Troy Client is bundled as a forced dependency because without it, WordPress would fetch plugin information from wordpress.org instead of your repository. This could lead to supply chain attacks or broken updates.
Package vs Plugin Lifecycle
| Aspect | Plugin | Package |
|---|---|---|
| Purpose | Serve updates | Initial distribution |
| Troy Client | Required (user must install) | Bundled automatically |
| Versioning | Each version stored | Always fetches latest |
| Rebuilding | Upload new ZIPs | Only when changing bundle contents |
| User action | Install, receive updates | Install once, then delete Package |
Advanced Settings
Plugin Configuration Options
For each plugin in a Package:
| Option | Default | Description |
|---|---|---|
| Activate | On | Activate the plugin after installation |
| Network | Off | Network-activate on WordPress multisite |
| Overwrite | Off | Replace existing plugin with same slug |
| Overwrite Troy | Off | Replace even if the existing plugin is managed by Troy |
Overwrite Behavior:
If Overwrite is off and the plugin already exists but is inactive, the user will see an error and the plugin won't be activated. Set Overwrite to true for smoother updates.
Notice Severity
Control how much feedback users see during installation:
| Level | Behavior |
|---|---|
| Detailed | Show all installation steps and results |
| Verbose | Show important messages only |
| Silent | Minimal output |
Cross-Repository Plugins
You can include plugins from other Troy repositories in your Package. However:
- A warning will be displayed about the repository mismatch
- If the plugin is imported via an integration, it will be set to Unreleased and ignored
This is by design—Packages should primarily bundle plugins from their own repository to maintain a clean distribution chain.
Distributing Packages
Give users a direct link to your Package:
https://your-server.com/package/get/zip/example-package
Or embed the download on your website:
<a href="https://your-server.com/package/get/zip/example-package"
class="button">
Download Installer
</a>
Installation Instructions for Users
- Download the Package ZIP from your website
- In WordPress, go to Plugins → Add New → Upload Plugin
- Upload the ZIP and click Install Now
- Click Activate
- The installer runs automatically, installing Troy Client and your plugins
- Optionally delete the Package plugin after installation
Updating Packages
Packages automatically fetch the latest version of each bundled plugin at install time. You don't need to rebuild Packages for every plugin update.
Rebuild your Package when:
- Adding or removing plugins from the bundle
- Changing plugin configuration (activate, overwrite, etc.)
- Updating Package metadata (name, description, author)
- A new Troy Server version introduces installer improvements
To rebuild: Open the Package in the editor and click Update. The ZIP is regenerated automatically.
Example Use Cases
Single Plugin Distribution
Bundle your main plugin for easy distribution:
- Plugin: Your awesome plugin
- Activate: Yes
- Overwrite: Yes
Users get Troy Client + your plugin in one install.
Plugin Suite
Bundle multiple related plugins:
- Plugin 1: Core functionality (activate: yes)
- Plugin 2: Premium add-on (activate: yes)
- Plugin 3: Optional tools (activate: no)
Users get everything installed, with optional plugins ready to activate when needed.
Agency Toolkit
Bundle client-site essentials:
- Plugin 1: Your maintenance plugin
- Plugin 2: Security hardening
- Plugin 3: Performance optimization
Deploy to client sites with a single Package install.
Troubleshooting
"Plugin installation failed"
- Check that the bundled plugin exists and has a Tag or Beta version available
- Verify the plugin status is Public or Unlisted
- Ensure the server is accessible from the user's site
"Troy Client installation failed"
- Check connectivity to
repo.deploytroy.org - Verify the user's hosting allows outbound HTTPS connections
- Check PHP timeout settings (increase if needed)
Package not downloading
- Verify the Package status is Public or Unlisted
- Check that the Package has been published (not still in Draft)
- Ensure the package slug is correct in the URL
API Endpoint
GET /package/get/zip/{slug}
Downloads the Package ZIP file. Returns 403 if the Package is not available, 404 if it doesn't exist.
Next Steps
- Add Plugins to your repository first
- Connect GitHub for automatic plugin updates
- Read the API docs for programmatic access
