Pelican Automatic Stock

Your Pelican package stock always matches the capacity actually free on your nodes, so you never oversell and never leave sellable capacity hidden.

What it does

Selling game servers off a fixed package quantity means either overselling past what your nodes can actually hold, or leaving real capacity unsold because nobody remembered to raise the number. Pelican Automatic Stock recalculates package stock itself, every few minutes, straight from the free memory, disk, CPU and ports on the Pelican nodes each package deploys to. The moment a node fills up, the storefront stops selling that package; the moment a client cancels and frees up room, it starts selling again - with no one editing a quantity by hand.

It works with the Pelican module by Blesta.Club and follows each package's own placement: the nodes you picked for it, or the nodes carrying one of its tags.

Key features

• Stock That Keeps Itself Accurate: Package quantities are recalculated on a schedule from the capacity your Pelican nodes actually have free, so nobody has to remember to edit a quantity again.
• Memory, Disk, CPU and Ports: How many more servers a package can fit is worked out from free memory, disk, CPU and free ports together, and whichever runs out first decides the number. Over-allocation and unlimited nodes are honoured exactly as your panel applies them.
• Follows Your Node and Tag Placement: Stock is calculated from the nodes a package really deploys to, whether you picked them by name or by tag, and nodes in maintenance mode are left out.
• Port Ranges and Extra Ports Counted: Each server needs its primary port plus the extra ports and spares the package asks for, and only free ports inside the package's port range are counted.
• Hold Capacity Back in Reserve: Keep a fixed number of slots, or a percentage of the calculated stock, unsold as headroom for migrations, growth and support cases.
• Cap the Advertised Stock: Set a maximum quantity so a large node fleet never advertises an implausible number of slots.
• Choose Which Packages Are Managed: Restrict automatic stocking to the packages you pick, leaving hand-managed or promotional packages exactly as you set them.
• Preview Before You Commit: Dry-run mode computes and reports a run without writing anything, so a new configuration can be checked before it goes live.
• Detailed Last Run Report: The settings screen shows the last run's time, trigger, duration and updated/skipped/failed counts, with a per-package and per-node breakdown.
• Full Request Logging: Every call to your panel is recorded in Blesta's module log, with your API key never written to it.
• Email Alerts When a Run Fails: Get an email whenever a run hits an error such as an unreachable panel or a rotated API key.
• A Panel Outage Never Zeroes Your Stock: If a panel does not answer, every package it serves keeps its existing quantity exactly as it is instead of being written down.
• Demo Servers Never Touch Live Stock: Packages on a Pelican server set to mock mode are calculated from bundled sample data and reported, but never written.
• Update Stock On Demand: A Save And Update Stock button runs the whole calculation immediately, even while automatic updating is switched off.

Enhance your Pelican stock management with Pelican Automatic Stock by Blesta.Club.

Installing Pelican Automatic Stock

Before you start

• Pelican Automatic Stock requires Blesta 6.0 or later.
• If you are on the leased (subscription) licence, the Blesta Club Subscription Manager must be installed and your subscription active. The owned and owned-source licences have no such requirement.
• You need the Pelican module by Blesta.Club already installed, with at least one Pelican server added and the packages you want to stock created on it - this plugin restocks packages that module already provisions, using the same panel connection.

1. Upload the files

Upload the extension folder into your Blesta installation so it lands under your Blesta directory at:

plugins/pelican_automatic_stock/

For example, on a typical install: /var/www/html/blesta/plugins/pelican_automatic_stock/

2. Install it in Blesta

1. Log in to your Blesta admin area with a staff account that has access to Settings > Company > Plugins.
2. Go to Settings > Company > Plugins and click the Available tab.
3. Find Pelican Automatic Stock in the list and click Install.

3. Configure it

1. Click Manage next to Pelican Automatic Stock on the Plugins page.
2. Select your Pelican Module to stock from. A demo mode is available (tick Mock API) if you want to see a report before pointing it at a real panel.
3. Optionally set a Managed Packages list, a stock reserve, a maximum stock cap, dry-run mode, and an email address to notify on failure - all covered in the usage guide.
4. Tick Enabled and save. A cron task is registered automatically and runs every 5 minutes from then on - no separate setup is needed for it.

You're ready to go - see the usage guide for a walkthrough of day-to-day use.

Updating Pelican Automatic Stock

Upgrading works just like installing: upload the new files over the old ones, then run the upgrade from the same page you installed it on.

1. Back up your current extension files first - good practice before any upgrade.
2. Upload the new version over the existing folder, replacing the old files.
3. Log in to your Blesta admin area and go to Settings > Company > Plugins.
4. Find Pelican Automatic Stock and click Update to run the upgrade.

Version-specific notes

• v1.0.0: Initial release - there is nothing to migrate.

Using Pelican Automatic Stock

For your staff

The settings screen (Settings > Company > Plugins > Manage)

Everything lives on one screen, grouped into Stock Source, Stock Limits, Notifications and Testing:

• Enabled: Turns the automatic cron-driven updates on or off. The settings can still be saved, and a manual run performed, while this is unticked.
• Pelican Module: The installed Pelican module to stock from. Choose Disabled to stop stocking altogether.
• Managed Packages: Restrict automatic stocking to the packages you pick here. Leave nothing selected to manage every package on the chosen module.
• Stock Reserve / Reserve Type: Hold back a fixed number of units, or a percentage of the calculated stock, so the advertised quantity always sits a little below what the nodes could technically fit.
• Maximum Stock: Cap the highest quantity a package will ever advertise. Leave it at 0 for no cap.
• Dry Run: Compute and report a run without writing any package quantities, so you can preview the effect of a settings change before it goes live.
• Notify On Failure / Notification Email: When ticked, an email is sent to the address you enter whenever a run reports an error, such as an unreachable panel.
• Mock API: Runs against bundled sample data instead of your real panel - useful for seeing what a run and its report look like before you have live nodes to point at. A run made with this ticked never writes a package quantity.

Click Save to store your settings, or Save And Update Stock to save and immediately run the calculation - this works even while Enabled is unticked, so you can preview a run before switching automatic updates on.

How stock is worked out

For each managed package, the plugin looks at the nodes that package deploys to: the nodes you selected on the package, or every node carrying one of the package's tags. On each of those nodes it works out how many more servers fit, using the package's memory, disk and CPU limits against the node's free figures (with the node's over-allocation applied, and a node set to unlimited treated as unlimited), and the node's free ports against the ports each server needs. Whichever runs out first decides that node's number, and the numbers for all the package's nodes are added together. Your reserve and cap are then applied.

Each server needs one primary port, plus one for every extra port line on the package that applies to its egg, plus the package's spare ports. When the package has a port range, only free ports inside that range count.

Reading the Last Stock Run report

After any run - scheduled or manual - the same screen shows a report below the settings form: the run's time, what triggered it, how long it took, and how many packages were updated, skipped or failed. Each package lists its previous and newly calculated stock and which resource (memory, disk, CPU or ports) decided the number. Each node lists its tags, the Pelican server it belongs to, its capacity, allocated and free figures for memory, disk, CPU and ports, and whether it answered or is in maintenance mode. A run made with Mock API or Dry Run is labelled as such, and a package left unchanged because nothing could be measured is reported as skipped rather than silently zeroed.

Checking what was sent to the panel

Every request the plugin makes to your panel, and the panel's answer, is written to Tools > Logs > Module under the Pelican module, so you can see exactly what a run asked for and got back. Your API key is never written to the log.

Good to know

• Stock is only ever written when it could be measured in full - an unreachable panel, a package whose nodes or tags match nothing on the panel, or every matching node being in maintenance all leave the existing quantity untouched rather than writing it down.
• Every server needs at least one port, so a package with no memory, disk or CPU limits is still stocked by the free ports on its nodes.
• Tags are matched exactly as typed, including upper and lower case, the same way the Pelican module passes them to your panel.
• Stock is worked out from the package's own limits. Resources sold as configurable options (for example a memory slider) are not taken into account, so set the package limits to the largest size a client can order if you want stock to stay on the safe side.
• Ports are an approximate figure: stock counts free ports, but does not check that a server's ports sit together on one IP address, so an order can still occasionally fail for lack of ports.
• On a package placed on selected nodes, CPU does not limit stock and a node that reports no free memory or disk figure is not counted, matching how the Pelican module itself picks a node for those packages.
• Packages on a Pelican server that is in mock mode are always calculated from the bundled sample data and never written, even with Mock API unticked. The report says which servers that applied to.
• Mock API and Dry Run are independent switches - either one on its own is enough to stop a run from writing anything.