Essentials Core
Essentials Core is the shared part of the Essentials plugins for Pelican Panel. It adds one page that lists every Essentials module on the panel, where each one is configured and which of its parts are switched on, and a Panel health check that says whether the panel itself can run them. It also decides which languages people may pick, and holds the connection to the Essentials artwork library.
Every other Essentials module works without Core. Installing it is still recommended: without it there is no module list, no Parts window to switch module parts on and off, no health notes and no shared settings search.
At a glance
| Plugin ID | essentials-core |
| Current version | 1.3.2 |
| Pelican Panel | 1.0 (tested on 1.0.0-rc.2) |
| Needs | The scheduler (for the queue worker check and Pelican's own strings), a queue worker (for the Panel health test job), the frontend build (it ships a stylesheet and a script for the settings search) |
| Works with (optional) | Every Essentials module; Essentials Auto Updater (adds an Update column); Essentials Monitoring (draws the module list on the dashboard) |
| Adds | Admin area, sidebar group Essentials Core: pages Essentials and Languages. A Search settings box above every Essentials settings page |
| Permissions | Admin -> Roles, section Essentials Core: View, Update, Core, View Core, Languages, View Languages |
What the permissions mean:
- View and Update: everything Core shows, and everything it changes.
- View Core / Core: the Essentials page on its own.
- View Languages / Languages: the Languages page on its own.
- Update is also what the Parts window for Core, the Artwork library and the fix buttons under Panel health ask for. Nothing narrower opens those.
Before you install
-
The panel does not run the legacy all-in-one plugin "Essentials" (plugin id
essentials). Never run it on the same panel as anyessentials-*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. -
If this panel runs Essentials Core 1.1.0 or older and gets updates from the Essentials website, install the Essentials Auto Updater first. See Updating.
-
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. Core ships a stylesheet and a script, and Pelican compiles them into the panel's frontend build when the plugin is installed.
-
The scheduler runs. This is a cron job that runs Pelican's timed tasks every minute, for the panel's web user:
* * * * * php /var/www/pelican/artisan schedule:run >> /dev/null 2>&1Add it with
sudo crontab -e -u www-data. The examples in this document assume Pelican lives in/var/www/pelicanand the web server user iswww-data(Debian and Ubuntu). On another setup, adapt the path and the user (for examplenginxon some systems). -
The queue worker runs. This is Pelican's background worker, usually the systemd service
pelican-queuerunningphp artisan queue:work. Check it withsystemctl status pelican-queue. SetRestart=alwayson the service, and add a drop-in withStartLimitIntervalSec=0under[Unit], so systemd never gives up restarting it after repeated crashes.
Installing
Download Core from the Essentials website, https://essentialsplugins.nl: sign in, open the catalogue, pick Essentials Core and a version, and download the zip. x.y.z is stable, x.y.z-beta is a test release and x.y.z-dev is a development build. Use stable on a live panel. Core is also published on Pelican Hub.
Pick one of these routes. The first is the easiest.
-
From the admin area. Go to Admin -> Plugins -> Import from File and choose the zip. Press Install on the plugin. Pelican says "Plugin install started in the background". Refresh after a minute until the plugin shows Enabled. (Pelican also has Import from URL.)
-
From the Essentials website. Connect your panel on the website with a Pelican application key. Make the key on the panel under Admin -> API keys, with read and write on Plugins; it starts with
papp_. Then use Install on Core's page on the website. -
With the Essentials Auto Updater. Its Plugin updates page offers Essentials modules that are not installed yet.
-
Command line (advanced). Unzip so the folder is exactly
/var/www/pelican/plugins/essentials-core, then:sudo chown -R www-data:www-data /var/www/pelican/plugins/essentials-core cd /var/www/pelican sudo -u www-data php artisan p:plugin:install essentials-core sudo -u www-data php artisan p:plugin:listThe list must say enabled. Unzipping over an existing plugin folder resets it to "not installed", so always run the install command again after unzipping.
What the install does:
- It creates no database tables and runs no migrations.
- It clears Pelican's route and view caches and asks the queue worker to restart.
- It writes Pelican's own strings for this panel (see Languages below).
- On a panel that ran the all-in-one, it copies the permissions roles held there to Core's own section, once.
- It removes the settings file of the updater Core carried up to 1.1.0, which held the website address and the encrypted update token.
After every install:
- If a new page answers 404 or an old version still shows, reload PHP-FPM (
sudo systemctl reload php8.4-fpm, use your PHP version) and restart the worker (sudo systemctl restart pelican-queue). - Run artisan, yarn and file commands as the web user (
sudo -u www-data ...), never as root. Files created by root cause errors and failed updates later. - If styling or the search box is missing, run
cd /var/www/pelican && sudo -u www-data yarn build.
First-time setup
-
Open Admin, sidebar group Essentials Core, page Essentials. The Installed table lists every Essentials module on the panel, Core first, with its version and what it Covers. A module that needs attention has a note under its name, for example "Switched off on Admin, Plugins." or "Switched on, but not running. The panel log says why."
-
Read the Panel health section under the table. It checks five things, each on its own line:
- Built assets: every switched-on Essentials plugin that ships stylesheets or scripts is in the panel's build.
- Writable folders: the panel can write to
storage(and itsapp,frameworkandlogs),bootstrap/cache,public/buildwith itsmanifest.json, andplugins. If not, it names the folder, its owner where it can tell, and the user it has to belong to. - Queue worker: whether a worker ran the small test job the scheduler sends every five minutes.
- Failed jobs: how many jobs are in the failed jobs table.
- Log size: the total of
storage/logs, with a warning above 50 MB.
Fix anything shown in orange or red before you go on. The first measurement of the worker can take up to five minutes.
-
Press Parts on a module's row to choose which parts of that module are switched on. A part that is off takes its pages and buttons out of the panel and keeps its settings. Core's own parts are:
- Modules on the dashboard: the list of modules in the dashboard block. Core supplies it and Essentials Monitoring draws it.
- Settings search: the box above every Essentials settings page.
- Pelican's own strings: Pelican's pages in your language where Pelican's own translation stops.
- Panel health: the section on this page, its buttons, and the test job on the queue.
-
Press Settings on a row to go to that module's settings page.
-
Open the Languages page in the same sidebar group:
- Under Offered, tick the languages people may choose. English and the language in Used when nothing else fits are always offered. Each language shows how much of what the panel says is translated.
- Used when nothing else fits is the language for somebody whose own language is not offered.
- Use it for the whole panel: on, such a reader gets all of Pelican in that language as well; off, only what the Essentials plugins say changes.
- Under What each language is called, give a language a different name. Leave it empty to keep the name Pelican gives it.
- Press Save.
-
Optional: to change what a word says on your panel, or to add a language nobody has translated, use Your own translations on the same page. Download a language file gives you one JSON file with every string the installed Essentials plugins use. Change it, then Add a language with that file. Only the lines you changed are stored as yours.
-
Optional: if you use Egg artwork or the shop, press Artwork library at the top of the Essentials page. Leave Address empty for the Essentials library at artwork.essentialsplugins.nl (only https addresses are accepted). The Key is optional and issued by whoever runs the library; with a key, a game the library does not have yet is put in its queue. Press Save. A key belongs to the address it was saved with: saving another address without typing a key drops it (from 1.3.2 on).
-
Give your admin roles Core's permissions under Admin -> Roles, section Essentials Core. Root Admins have everything already.
Things to watch out for
- Core installs no updates. Since 1.2.0 it checks for nothing and installs nothing. A panel that installed Core from Pelican Hub gets the Hub's releases through Pelican under Admin -> Plugins. Builds from the Essentials website come through the separate Essentials Auto Updater, and Core only shows what that plugin reports.
- Use it for the whole panel reaches outside Essentials. It changes the language of Pelican's own pages for readers whose language is not offered, and it is on unless you turn it off. The Languages page cannot be switched off, so this setting can always be found again.
- A language Pelican does not ship can be offered and set as Used when nothing else fits, but it does not appear in a person's own profile language picker. That list is Pelican's.
- Pelican's own strings fill in only what this panel's Pelican lacks; every string Pelican has keeps Pelican's words. Switch the part off under Parts if you want Pelican exactly as it ships.
- The Panel health part puts work on the queue: one small test job every five minutes, or one every fifteen while nobody answers. Switch the part off if you watch the worker another way. Off, there is no section, no button and nothing on the scheduler.
- Restart queue workers only tells running workers to stop after their current job. Their service starts them again. A worker that is not running is not started by this button.
- Forget failed jobs deletes every failed job and its error. This cannot be undone.
- The Parts window is only on Core's page. A part that is off takes its pages with it, so Core is the one place where any module's parts can be switched back on.
- Saving a role while a plugin is switched off removes that plugin's permissions from the role. Pelican only keeps the checkboxes it draws, and a plugin that is off draws none. Give the permissions again after switching the plugin back on.
- Send to the translators opens a filled-in issue on GitHub in your own browser. You send it yourself. The panel sends nothing and holds no credentials for it.
- Uploaded translations are checked. A line with an unknown key, an empty or very long string, or placeholders (like
:name) that do not match the English is left out and named; the rest is added. - The general rules apply: never run the legacy all-in-one beside the modules, and run every command as the web user.
Things to keep an eye on
- Panel health on the Essentials page. It is measured at most once a minute; the queue worker line is read live.
- The notes under each module's name in the Installed table, such as a module that stopped with an error or is waiting for something only an administrator can supply.
- Failed jobs. Find out why they failed before you press Retry failed jobs; a job whose cause is not fixed fails again.
- Log size. Errors go to
storage/logs/laravel-YYYY-MM-DD.log(orlaravel.log). Pelican's log viewer reads a whole file into memory, so a log around 100 MB makes Admin -> Logs fail. Empty or remove old log files on the panel host. With Core installed, the log is written in the server's own time zone, so it lines up with the web server log and the system journal. - The scheduler. If the queue worker line says "The scheduler last ran ...", the cron entry is not running.
- With the Essentials Auto Updater installed, the Update column shows which modules have an update waiting.
- Your own backups: Core's settings live in
storage/app/private/essentials/core/settings.json, and every module keeps its settings understorage/app/private/essentials. Include that folder and the database in the panel's backups. Thestoragefolder must stay writable by the web user.
Updating
- Download the new version and import it the same way. Pelican shows Update on the plugin when an update is known. Or let the Essentials Auto Updater do it. Core switches itself back on after an update through the admin area, and its settings are kept.
- Coming from Core 1.1.0 or older. Those versions installed module updates themselves. That updater is gone: installing a newer Core deletes its settings file (the website address and the encrypted update token) and its record of the last run. The plugins it installed stay as they are. To keep getting builds from the Essentials website, install the Essentials Auto Updater before you update Core, so it can copy those settings. If Core is already updated, issue a new token on the website and paste it into the Auto Updater. You can also revoke the old token on the website.
- Coming from Core 1.0.21 or older. Servers by Role, the star on a server card and the server switcher moved to Essentials Server Tools in 1.0.22. Install Server Tools before or together with the Core update; it takes over the role mappings, favourites and settings Core left in place. Until it is installed, the Essentials page says so.
Removing it
Uninstall Core under Admin -> Plugins. It has no database tables, so nothing is dropped. The other Essentials modules keep working on their own; they lose the module list, the Parts window, the shared search box and the shared artwork library connection.
These files stay behind:
storage/app/private/essentials/core/: Core's settings (settings.json), the artwork library address and encrypted key (artwork.json) and a few markers.role-servers.jsonandaccess-managed.jsonin this folder belong to Essentials Server Tools on panels that came from older Core versions; leave them if Server Tools still needs to take them over.storage/app/private/essentials/languages/: Pelican's own strings and your own translations (incustom). Download your translations first if you want to keep them.storage/app/public/essentials/core/: a copy of the Essentials logo for the sidebar.
To remove them by hand:
sudo rm -r /var/www/pelican/storage/app/private/essentials/core
sudo rm -r /var/www/pelican/storage/app/private/essentials/languages
sudo rm -r /var/www/pelican/storage/app/public/essentials/core
Troubleshooting
| Problem | What to do |
|---|---|
| The Essentials page or Languages page answers 404 after installing | Reload PHP-FPM (sudo systemctl reload php8.4-fpm) and restart the worker (sudo systemctl restart pelican-queue). Check with sudo -u www-data php artisan p:plugin:list that Core is enabled. |
| The pages are not in the sidebar | The role lacks Core's permissions. Give View Core or View Languages (or View) under Admin -> Roles. |
| The Parts, Artwork library or fix buttons are missing | They need Core's Update permission. Retry failed jobs and Forget failed jobs only appear while there are failed jobs. |
| Built assets says the build is missing stylesheets or scripts | Run cd /var/www/pelican && sudo -u www-data yarn build, as the web user and never as root. |
| Writable folders names a folder owned by root | sudo chown -R www-data:www-data on that folder, for example /var/www/pelican/public/build. Then rebuild if it was public/build. |
| Queue worker says no worker has run the test job | Start the worker on the host (sudo systemctl start pelican-queue). If systemd gave up on it: sudo systemctl reset-failed pelican-queue && sudo systemctl start pelican-queue. A worker started before Core was installed cannot run Core's jobs: press Restart queue workers. |
| Queue worker says the scheduler last ran a while ago | The cron entry is missing or runs as the wrong user. Add it with sudo crontab -e -u www-data. |
| Queue worker says "Not measured yet" | Wait up to five minutes after installing or after switching Panel health on. |
| Admin -> Logs runs out of memory | Log size names the largest file. Empty or remove old files in /var/www/pelican/storage/logs. |
| A module row says "Stopped with an error" or "Switched on, but not running" | Read the panel log for the reason, fix it, then switch the module on again under Admin -> Plugins. |
| A module row says "Replaced by Essentials Server Tools" | Essentials Duplicate and Essentials Console are part of Server Tools now. Remove the old module under Admin -> Plugins. |
| The Essentials page says Server access and Favourites moved | Install Essentials Server Tools. Role mappings, favourites and settings are carried over. |
| Saving says "This could not be saved" or "The artwork library could not be saved", with a note about storage permissions | Make storage belong to the web user: sudo chown -R www-data:www-data /var/www/pelican/storage. |
| A language you added does not show in a person's profile picker | Pelican lists only the languages it ships there. Set it as Used when nothing else fits instead. |
| Language settings never saves ("Could not save" or "The selected allowed languages is invalid") | A fault in Core 1.3.0: the form held English and the main language, which have no checkbox. Update to Core 1.3.1 or later. |
Essentials is a community project by Legend Development. Not affiliated with or endorsed by the Pelican team.