Skip to content
Essentials
The plugins Docs Sign in

Essentials Auto Updater

Open Essentials Auto Updater Last changed November 9, 2026

Essentials Auto Updater keeps the Essentials plugins on a panel up to date with builds straight from Legend Development, by hand or on a schedule. It downloads and installs plugin code itself, backs every plugin up before replacing it, puts the backup back when an update fails, and keeps a history of everything it did. It also checks every other plugin on the panel against Pelican Hub.

It is meant for administrators who have decided to take Essentials builds directly from Legend Development, for example to get updates installed at night or to test beta releases. If you are happy with what Pelican Hub offers, you do not need it.

At a glance

Plugin ID essentials-auto-updater
Current version 1.1.3
Pelican Panel 1.0 (tested on 1.0.0-rc.2)
Needs An update token from the Essentials website; the scheduler (for anything that happens on its own); a queue worker (for updates started from a page); Node.js and Yarn (every update rebuilds the panel's assets); outgoing https to the Essentials website and to Pelican Hub
Works with (optional) Essentials Core (shows the update state of each module on its Essentials page)
Adds Admin area, sidebar group Essentials Auto Updater: Dashboard, Plugin updates, Update history, Settings. A one-line Updating notice at the top of every page while an update installs
Permissions Admin -> Roles, section Essentials Auto Updater: View, Update. Changing anything also needs Pelican's own Create and Update permissions for plugins

What the permissions mean:

  • View: open the four pages and read them.
  • Update: change settings, manage plugins, install and restore. Only together with Pelican's own Create and Update permissions for plugins (from 1.1.3 on; before, Update alone was enough). Create is needed because the website address is a setting here, and Pelican asks Create before it installs a plugin from an address of somebody's choosing. Installing plugin code is as much power as a panel has, so this plugin never gives it to somebody Pelican would not let install a plugin. Root Admins have all of them.

Before you install

What it does on a panel

Read this first. This plugin is not distributed through Pelican Hub, and never will be, because it installs code itself.

  • It skips Pelican Hub's review. Pelican Hub reviews every version of a plugin before a panel can install it. Builds installed through this plugin come straight from the Legend Development update API on the Essentials website, without that review.
  • It connects to the Essentials website with a token. The token is issued for this panel on the website. With every check, the panel sends the token, the channel, its Pelican version, the Essentials plugins it has with their versions, and the ids of Essentials modules it could install. The token is sent only to the https address you configure, stored encrypted with the panel's APP_KEY, never shown again, never logged and never put in the history or a notification.
  • It manages nothing until you say so, plugin by plugin. Every plugin starts as "not managed": it is listed and never touched. You turn Managed by this updater on per plugin.
  • It installs automatically only when you allow it twice: Settings must say check and install, and the plugin's own Install updates on its own must be on. The default is check and say so: it checks, notifies and installs nothing.
  • It backs up before every replacement, whatever the settings say, and puts the backup back if any step fails.
  • It asks before replacing a plugin that came from Pelican Hub. An Essentials plugin installed from Pelican Hub (its plugin.json names Pelican Hub's update feed) is only managed after you tick Replace the version Pelican Hub reviewed. The moment of that confirmation is kept. A plugin you managed before its manifest started naming the Hub waits for the same confirmation.
  • It never installs a new plugin unasked. Modules the panel does not have are only listed under Not installed yet; nothing there is installed unless you press Install.
  • Every other plugin (not an Essentials one) is looked up on Pelican Hub by its id. Only versions the Hub has approved are offered, paid plugins are never fetched, and nothing about the panel is sent to the Hub except the ids it looks up.

Channels

Each Essentials plugin follows a channel. All of them come from the Legend Development update API, which decides who may receive which build.

Channel Takes
Stable finished releases (x.y.z)
Beta finished releases and betas (x.y.z-beta)
Dev finished releases, betas and development builds (x.y.z-dev)

Each channel includes everything above it, so a finished release always replaces the beta or development build before it. Versions are compared as 1.1.0-dev < 1.1.0-beta < 1.1.0 < 1.2.0-dev. Where the website and the panel disagree about which is newer, nothing is installed, so a mistake on the website cannot become a downgrade.

Dev is not for live panels. A development build is whatever the code was at the moment somebody pushed it, not a release anybody decided on. With check and install on a short interval, a new development build is on the panel within minutes. The Dev option is only offered on Legend Development's own development panels (decided by the panel's APP_URL); on every other panel it is not shown, and a dev channel copied in from elsewhere is read as stable. Beta is for test panels too. Use Stable on a live panel.

Checklist

  • You have decided that this panel may receive builds from Legend Development directly, outside Pelican Hub's review.

  • You have an account on the Essentials website, https://essentialsplugins.nl, and this panel has its own page there, so you can issue an update token for it under Automatic updates.

  • The panel does not run the legacy all-in-one plugin "Essentials" (plugin id essentials) beside any essentials-* module. Installing a module switches the all-in-one off, installing the all-in-one can switch modules off, and uninstalling the all-in-one deletes database tables the modules share. Pick one. (This plugin can manage either, but never offers modules on a panel that runs the all-in-one.)

  • If the panel runs Essentials Core 1.1.0 or older, install this plugin before you update Core. See Installing.

  • Pelican Panel 1.0 is installed. Pelican 1.0.0-rc.2 needs PHP 8.4 or 8.5.

  • Node.js and Yarn are installed on the panel server. Every update ends with Pelican rebuilding its frontend assets.

  • The scheduler runs as the web user. This is a cron job that runs Pelican's timed tasks every minute:

    * * * * * php /var/www/pelican/artisan schedule:run >> /dev/null 2>&1
    

    Add it with sudo crontab -e -u www-data. The examples in this document assume Pelican lives in /var/www/pelican and the web server user is www-data (Debian and Ubuntu). On another setup, adapt the path and the user (for example nginx on some systems). Scheduled updates run inside this cron job and replace plugin files and rebuild assets from there, so it must never run as root.

  • The queue worker runs. This is Pelican's background worker, usually the systemd service pelican-queue running php artisan queue:work. Updates, installs and restores you start from a page run there. Check it with systemctl status pelican-queue. Set Restart=always, and add a drop-in with StartLimitIntervalSec=0 under [Unit] so systemd never gives up restarting it. A panel without a worker (QUEUE_CONNECTION=sync) can still update on the schedule.

Installing

Download the plugin from the Essentials website: sign in, open the catalogue, pick Essentials Auto Updater and a version, and download the zip. It is not on Pelican Hub.

  1. From the admin area. Go to Admin -> Plugins -> Import from File and choose the zip. Press Install. Pelican says "Plugin install started in the background". Refresh after a minute until the plugin shows Enabled.

  2. From the Essentials website. Connect your panel on the website with a Pelican application key (made under Admin -> API keys, with read and write on Plugins; it starts with papp_), then use Install on the plugin's page on the website.

  3. Command line (advanced). Unzip so the folder is exactly /var/www/pelican/plugins/essentials-auto-updater, then:

    sudo chown -R www-data:www-data /var/www/pelican/plugins/essentials-auto-updater
    cd /var/www/pelican
    sudo -u www-data php artisan p:plugin:install essentials-auto-updater
    sudo -u www-data php artisan p:plugin:list
    

    The list must say enabled. Unzipping over an existing plugin folder resets it to "not installed", so run the install command again after every unzip.

What the install does:

  • It creates one database table, essentials_auto_updater_history, for the update history.
  • It clears the route, view and Filament caches and tells the queue worker to restart.
  • On its first install, on a panel that has no settings of its own yet, it copies the settings of the updater it replaces: from Essentials Core 1.1 (what to do, how often, the channel, the website address and the encrypted token) or from the all-in-one 3.225 (its channel and automatic update settings in .env). Plugins the old updater kept up to date become managed, except plugins installed from Pelican Hub. This happens once.

After installing, if a page answers 404, reload PHP-FPM (sudo systemctl reload php8.4-fpm, use your PHP version) and restart the worker (sudo systemctl restart pelican-queue). Run every artisan, yarn and file command as the web user, never as root.

First-time setup

  1. On the Essentials website, open this panel's page and issue an update token under Automatic updates. It is shown once and starts with esu_. Copy it, and the website address shown next to it.
  2. On the panel, open Admin, sidebar group Essentials Auto Updater, page Settings.
  3. Under Update API, paste the Website address (https only) and the Update token. Press Test connection. It should say "Connected to the website". Press Save.
  4. Under Automatic updates, choose:
    • What to do: nothing, check and say so (the default) or check and install.
    • How often: from every minute to once a week. The default is once a day. Daily and weekly run at 04:00, because the panel rebuilds its assets during an update and is briefly slow.
    • Default channel: Stable on a live panel.
    • Install only from and Until (optional): an install window in the panel's time zone. check and install then only installs inside it; checking still happens on schedule, and installing by hand always works. 22:00 to 06:00 is one night. Leave both empty to install at any time.
  5. Under Notifications, decide on Notify administrators (every Root Admin gets a panel notification when a check finds something new for a managed plugin, and when a run changes or fails to change the panel) and the Updating notice (a line at the top of every page, the sign-in screen included, while an update installs and for five minutes after). Both are on by default.
  6. Under Backups, set Backups kept per plugin (1 to 10, default 3). Press Save.
  7. Open Plugin updates. Press Manage on each plugin you want this updater to look after:
    • Managed by this updater: on.
    • Channel: the default, or a channel for this plugin only (Essentials plugins only; Pelican Hub has no channels).
    • Install updates on its own: only if the schedule may install it without anybody pressing a button.
    • Replace the version Pelican Hub reviewed: appears for an Essentials plugin installed from Pelican Hub. Tick it only if you accept that its reviewed version is replaced with builds from the update API, on every channel including stable.
  8. Open Dashboard and check Needs attention. It says when the panel is not connected, the scheduler is not running, the panel has no queue worker at all (QUEUE_CONNECTION=sync), another updater is still active or the settings file cannot be read. A worker that has stopped is not reported here.
  9. Give the admin roles that need it View or Update under Admin -> Roles, section Essentials Auto Updater.

The buttons on a row of Plugin updates: Update (a managed plugin with an update waiting), Check, Changelog, Other versions (any version the website lists for that channel, older ones included) and Restore a backup. Check now and Install what is waiting at the top act on every plugin.

Things to watch out for

  • Development builds arrive within minutes. On a development panel set to Dev with check and install, a push to the working branch is installed almost at once. Never use it on a live panel.
  • A plugin from Pelican Hub can end up with two update sources. After you confirm Replace the version Pelican Hub reviewed, this plugin installs builds from the update API, while Pelican's own Update button under Admin -> Plugins may still offer the Hub's releases. Update such a plugin one way only.
  • A backup restores files, not the database. A migration that a failed or newer release ran stays run. Essentials migrations are written to add rather than remove, so older code usually survives a newer schema, but a restore or a downgrade through Other versions never undoes a migration.
  • Nothing is installed on a schedule while an older updater is active. While Essentials Core 1.1 or older, or the all-in-one 3.225 or older, is installed and enabled, this plugin only installs by hand. The Dashboard says so. Update or remove the old plugin by hand.
  • Install this plugin before updating Core past 1.1. Core 1.2 and newer delete Core's old updater settings on install. If that already happened, issue a new token on the website and paste it under Settings.
  • Changing the panel's APP_KEY makes the stored token unreadable. The panel then counts as not connected. Paste the token again (or issue a new one).
  • No queue worker, no updates from a page. With QUEUE_CONNECTION=sync, the pages refuse to start an update, because it would be cut off halfway through replacing a plugin. With a worker that has stopped, a run stays at Queued.
  • The panel is briefly slow during an update while it rebuilds its assets. Pages may look unfinished for a minute; the Updating notice says so.
  • This plugin updates itself last in a run.
  • Saving a role while this plugin is switched off removes its permissions from that role. Pelican only keeps the checkboxes it draws. Give them again after switching it back on.
  • Other versions may say "The website does not list versions yet." That is the website, not your panel.

Things to keep an eye on

  • Dashboard: Needs attention, Last update check and when the next one is, and Update status of the last run.
  • Update history: one row per plugin per change, with the previous and new version, the channel, who started it and the result (updated, installed, restored, failed, put back, failed). Read Details for anything that failed.
  • The scheduler. If the Dashboard says "The scheduler has not run" or "The scheduler last ran ...", nothing happens on its own.
  • The queue worker, with systemctl status pelican-queue, or with Panel health on Essentials Core's page.
  • Disk space for backups in storage/app/private/essentials/auto-updater/backups/. Each managed plugin keeps up to the number you set.
  • The token. If the website stops accepting it ("The website refused the update token"), issue a new one.
  • Errors also go to storage/logs/laravel-YYYY-MM-DD.log (or laravel.log).
  • Your own backups: include storage/app/private/essentials (the settings and the plugin backups) and the database (the history) in the panel's backups. The storage folder must stay writable by the web user.

Updating

  • This plugin can update itself: manage Essentials Auto Updater on its own Plugin updates page like any other plugin. It is always updated last in a run.
  • Or download the new version and import it under Admin -> Plugins the same way you installed it. Settings, backups and history are kept. From 1.1.2 on the plugin switches itself back on after such an update; on 1.1.1 and older, check that it shows Enabled under Admin -> Plugins afterwards and press Enable if not, or nothing will be updated any more.
  • Make a database backup before updating a plugin that keeps data in tables, whichever way you update it.

Removing it

Uninstall the plugin under Admin -> Plugins. That stops everything it does: no more checks, no scheduled installs, no notice. Plugins it installed stay as they are, and from then on you update them by hand or through Pelican. On Essentials Core's page, the Update column disappears.

What stays behind:

  • The history table essentials_auto_updater_history is kept on purpose, so the record of what was done to the panel's plugins does not vanish with the tool that did it.
  • storage/app/private/essentials/auto-updater/: settings.json (the settings, with the token encrypted), last-run.json (the last run), backups/ (the backups) and an imported marker.

To remove the rest by hand, drop the table in the panel's database (for MySQL or MariaDB: DROP TABLE essentials_auto_updater_history;) and delete the folder:

sudo rm -r /var/www/pelican/storage/app/private/essentials/auto-updater

Revoke the update token on the website as well.

Troubleshooting

Problem What to do
"This panel is not connected to the Legend Development update API" Issue a token on the panel's page on the website under Automatic updates and paste it with the website address under Settings. Press Test connection.
Test connection says "The website refused this token" Issue a new token on the website and paste it. Copy the whole token; it starts with esu_.
Test connection says the address did not answer like the Essentials website Copy the Website address exactly as the website shows it next to the token. It must be https.
A plugin row says "needs confirmation" It came from Pelican Hub. Under Manage, tick Replace the version Pelican Hub reviewed if you accept that, or leave it unmanaged.
An update is waiting but nothing installs on its own Check all three: What to do is check and install, the plugin is managed with Install updates on its own on, and the install window (if set) is open. Then check the Dashboard for an older updater still active.
A run stays at Queued No queue worker picked it up. Start it with sudo systemctl start pelican-queue (after sudo systemctl reset-failed pelican-queue if systemd gave up).
"This panel has no queue worker, so an update would have to run inside this request" The panel uses QUEUE_CONNECTION=sync. Set up a queue worker, or leave updates to the scheduled run.
"An update or a restore is already queued or running" Wait for it to finish; the result appears under Update history.
"The panel assets did not rebuild" Everything else was installed. Run cd /var/www/pelican && sudo -u www-data yarn build, as the web user.
"The new files are in place and the panel now calls this plugin ..." The panel could not write the plugin's plugin.json. Make the plugins folder belong to the web user (sudo chown -R www-data:www-data /var/www/pelican/plugins) and switch the plugin on under Admin -> Plugins.
"The backup could not be written" or "The download could not be written" storage/app must be writable by the web user and have free space.
A download is refused (checksum, wrong plugin, wrong version, not a zip, unsafe path) Nothing was replaced. Check again later; if it keeps happening, report it to Legend Development.
"The update settings could not be read" The settings file is damaged. Fix or delete storage/app/private/essentials/auto-updater/settings.json and set the settings again.
The Dev channel is not offered Expected: it is only offered on Legend Development's development panels.
A plugin says "nothing is offered for it on this channel" The website does not publish that plugin on that channel.

Essentials is a community project by Legend Development. Not affiliated with or endorsed by the Pelican team.

Put Essentials on your home screen

Your browser can install it now. It opens in a window of its own, without the address bar, like any other app.