Essentials (all-in-one)
Essentials is the older all-in-one plugin by Legend Development for Pelican Panel. In one plugin it restyles the panel and adds announcements, a page arranger, server tools, game settings pages, monitoring with alerts, a shop, a support desk and an HTTP API. Every part has its own on and off switch and its own permission. Switching the styling off leaves the panel exactly as Pelican draws it.
Pick one: this plugin or the modules. Never run Essentials (all-in-one) on the same panel as any
essentials-*module (Essentials Core, Shop, Support, API, Appearance, Monitoring and the others). Every part of this plugin now has a module that provides it, and the two do not mix:
- Installing a module switches this plugin off, or at least every part of it that the module provides.
- Installing this plugin on a panel that already has modules can switch module parts off. The modules read some of this plugin's settings from
.env, and older versions of this plugin wrote their first-install defaults there.- Uninstalling this plugin through Pelican deletes the database tables the modules share: every package, order, invoice, payment, ticket and API key. Pelican's own confirmation does not mention this.
The one
essentials-*plugin meant to run beside it is the Essentials Auto Updater, which only installs and updates plugins. If you run this plugin today and want the modules instead, read Moving to the modules before you install anything.
At a glance
| Plugin ID | essentials (the folder must be plugins/essentials, in lowercase) |
| Current version | See the Essentials website, essentialsplugins.nl, for the current stable version |
| Pelican Panel | 1.0 (declares ^1.0.0-beta35, tested on 1.0.0-rc.2) |
| Needs | Node.js and Yarn (frontend build), the scheduler, the queue worker. Outside accounts only for the parts you use: Stripe, Mollie or PayPal for the shop, Modora for tickets in Discord, a Discord webhook for alerts, an S3 bucket or CDN for files |
| Works with (optional) | Essentials Auto Updater (updates from the Essentials website), Modora (Discord) |
| Adds | Admin area: sidebar groups Essentials (settings, tools and overviews) and Essentials CMS (shop and tickets), and a block on the dashboard. Client area: account menu entries such as My services, Billing, Help and Appearance. Inside a server: game settings pages. Public: a shop page, status pages and an API under /api/essentials/v1/ |
| Permissions | Admin -> Roles, section Essentials (older versions call it Legend Theme): View, Update, Arrange, and a pair per area |
What it includes
A short overview. The linked guides describe the separate modules that now do the same job; use them for background on a feature, and the pages in your own panel for the exact options of this plugin.
| Area | What it does here | Module that does the same |
|---|---|---|
| The look | Thirteen styles (or None - no theme), accent and surface colours, layouts, icons, backgrounds, custom CSS, the login screen, your own sidebar links, the sidebar footer, timed looks and per-person styles | Essentials Appearance |
| Announcements | Scheduled, dismissible bars across the top of the panel | Essentials Announcements |
| Page arranger | Drag the blocks on a page into the order you want, per person, with a starting arrangement set by administrators | Essentials Arranger |
| Server tools | Duplicating servers, starred servers and the Favourites page, the Go to menu, the floating console button, servers tied to a role | Essentials Server Tools |
| Game tools | Pages inside a server for Minecraft (server.properties, modpacks, a Modrinth browser, players), Palworld, ARK, Terraria, Valheim and more, player lists for games that answer Valve's query, and egg artwork |
Essentials Game Manager |
| Running the panel | The dashboard block with every machine, System status, Backups (servers by how long since their last backup), Schedules, Capacity, Activity, the watchdog (Alerts) and public status pages | Essentials Monitoring |
| Shop | Packages, a basket, invoices, Stripe, Mollie and PayPal, renewals and suspension, credit, upgrades, extras, coupons, VAT with the reverse charge, a waiting list and a public shop page | Essentials Shop |
| Support desk | Tickets in the panel, beside the server they are about, or answered in Discord through Modora | Essentials Support |
| API and files | An HTTP API with keys you grant, narrow and revoke, and keeping uploads in a bucket or on a CDN (Storage and CDN) | Essentials API |
| Languages | Answers each person in their account's language and fills in Pelican's own pages where its translation stops | Essentials Core |
Before you install
-
No
essentials-*module is on the panel. Check withls /var/www/pelican/plugins: onlyessentials-auto-updatermay be there. If modules are there, do not install this plugin (see the warning at the top). -
You have a backup of the database,
.envand thestoragefolder. This plugin can create tables and writes its settings into.env. -
Pelican Panel 1.0 is installed. Pelican 1.0.0-rc.2 needs PHP 8.4 or 8.5.
-
The web user can write
/var/www/pelican/.envand thestoragefolder, because this plugin saves its settings and files there. -
Node.js and Yarn are on the panel server. The plugin's styles are compiled into the panel's own frontend build. On Debian or Ubuntu:
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs && sudo npm install -g yarn -
The scheduler (a cron job that runs Pelican's timed tasks every minute) is set up for the web user. Add it with
sudo crontab -e -u www-data:* * * * * php /var/www/pelican/artisan schedule:run >> /dev/null 2>&1The examples in this guide assume Pelican is in
/var/www/pelicanand the web server user iswww-data(Debian/Ubuntu). On another setup, adapt the path and the user (for examplenginxon some systems). -
The queue worker (Pelican's background worker, usually the systemd service
pelican-queue) is running:systemctl status pelican-queue. Give itRestart=always, and a drop-in withStartLimitIntervalSec=0under[Unit], so systemd never gives up restarting it. Watchdog checks, server builds after a payment, renewals, artwork downloads, modpack installs and mail all run there.
Installing
Download the plugin from the Essentials website, essentialsplugins.nl: sign in, open the catalogue, pick Essentials 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.
From the admin area (recommended for beginners)
- Go to Admin -> Plugins -> Import from File and choose the zip. (Pelican also has Import from URL.)
- Essentials appears in the list. Press Install.
- Pelican says "Plugin install started in the background". The panel runs
yarn build, which takes a minute or two. Refresh until the plugin shows Enabled.
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. Only do this on a panel without modules.
From Pelican Hub
If you use Pelican Hub, Essentials is published there as essentials. Install it from its page on hub.pelican.dev, or import the archive the Hub offers under Admin -> Plugins.
Command line (advanced)
cd /var/www/pelican
sudo unzip essentials.zip -d plugins/ # must give plugins/essentials
sudo chown -R www-data:www-data plugins/essentials
sudo -u www-data php artisan p:plugin:install essentials
sudo -u www-data php artisan p:plugin:list
The list must say enabled. The folder must be essentials in lowercase: a folder with capitals is listed but never loads on Linux. Unzipping over an existing plugin folder resets it to "not installed", so always run the install command again after unzipping.
What the install does
- On a panel that has never had this plugin (no
LEGEND_THEME_lines in.envand noessentials-*folder underplugins/, the Essentials Auto Updater's included), it starts quietly: Telling somebody (alerts), Answering customers (tickets), Selling what you run (the shop) and Reachable from outside (API, public status pages, files on a bucket or CDN) are switched off. Everything else arrives on. A panel that already had the plugin keeps its switches. - It creates the shop, support desk and API tables only for the parts that are switched on. Switching one on later creates its tables then.
- It clears Pelican's caches, asks the queue worker to restart, and switches itself on at the end.
After installing
- If a 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 (cache files,public/build) cause errors and failed updates later.
First-time setup
Where the settings live. Settings are stored in the panel's .env file as LEGEND_THEME_... lines, which the plugin reads through its config/essentials.php. Lists and files (announcements, links, saved styles, arrangements, status pages and similar) are kept in storage/app/private/legend-theme/, and uploaded pictures in storage/app/public/theme/. You change all of it on the plugin's pages in the admin area (sidebar group Essentials), or in one modal under Admin -> Plugins -> Essentials -> Settings. You do not need to edit .env by hand; if you do, run sudo -u www-data php artisan optimize:clear afterwards.
- Open Admin, sidebar group Essentials, page Modules (on a new panel the row carries a Set it up badge). The page asks What is this panel for?: Mostly how it looks, Running servers, for me or a team, Selling hosting to customers, or I will pick them myself. Click one. Every switch stays yours afterwards.
- On the same page, use Turn on and Turn off for the seven groups (The look of the panel, On a server, Running the panel, Telling somebody, Answering customers, Selling what you run, Reachable from outside) or for single parts. A part that is on but waiting for something says so, for example "On, and showing nothing: name the eggs it applies to first."
- Set the look on Look (style, colour, shape, brand, background, icons), Pages and Advanced (custom CSS, per-area overrides). Style set to None - no theme leaves Pelican's own look.
- Give your admin roles access: Admin -> Roles -> a role, section Essentials. View and Update cover everything; each area also has a pair, for example
Notices(open and change the announcements) andView Notices(open only). Arrange covers the page arranger. Root Admins have everything already. - For game pages, name the eggs on Minecraft and Other games. A game page only appears on servers whose egg is ticked.
- For alerts, open Alerts, fill in Channels (Discord, In the panel, Email or A bot of your own) and press Send a test. Where messages go at the top of the page then shows what each channel last did.
- For the shop, open sidebar group Essentials CMS -> Shop settings and enter the keys of your payment providers (Stripe, Mollie, PayPal) from their dashboards. Then create packages under Packages. See the shop guide for background.
- For tickets, open Essentials CMS -> Tickets, press Where these are answered and choose In the panel, or In Discord, through Modora with an integration key from your Modora server (scopes
tickets.create,tickets.read,tickets.close,messages.read,messages.write). - For the API, open API to grant keys. The page has the full reference, a Markdown copy and an OpenAPI file.
- When you are happy, open Essentials settings and press Export settings to keep a copy.
Things to watch out for
- Never beside the modules. See the warning at the top. This is the most common way to lose data with this plugin.
- Uninstalling deletes shop, ticket and API data without warning. Pelican's Uninstall drops every package, order, invoice, payment, ticket and API key, so every key this plugin issued stops working. The servers the shop created stay. Read Removing it first.
- Every install or update switches the plugin on again, even if you disabled it. On a panel where it should stay disabled, do not reinstall or update it.
- The folder name must be
essentials. Capitals, or a folder still carrying an old name, stops it loading (see Troubleshooting). - Switching a part off keeps what it wrote. Settings, orders and saved arrangements stay and return when you switch it back on. Servers by role is the exception that keeps acting: people keep the servers and SFTP access it granted. To take that away, use Take it all back on Server access (or on the Modules page once the part is off).
- Doors to the outside are off until you open them. The API, public status pages and the public shop page are reachable without signing in once they are switched on.
- Secrets are in
.env. Payment provider keys, the Modora key and similar credentials are kept there. Export settings leaves them out, so after restoring from an export you enter them again. Keep.envin your backups, but never share it. - The watchdog needs the queue worker. Without one nothing is sent and nothing says so. Send a test does not use the queue, so it works even when the checks do not.
- Custom CSS loads last and wins over everything else the plugin sets.
- Run commands as the web user, never as root.
Things to keep an eye on
- The dashboard block (admin dashboard): installed version, what the Essentials Auto Updater reports, and every machine with what it is using. It warns "No queue worker answered" when the worker is missing, and "The panel's scheduler has not run for N minutes" when the cron is not running. Renewals and watchdog checks wait on the scheduler.
- The Modules page: notes such as "Its tables are not there yet", "parts need something that is switched off" and "parts are on and showing nothing yet".
- Parts switching on their own. Every change to the switches is logged as
Essentials: parts switched, with what went off or on, what did it and who. Look for it in the log when a part disappears unexpectedly. - Tickets through Modora. A ticket Modora refused shows as not passed on yet, with Pass it on again. Nothing typed is lost, but check for these now and then.
- Payments. Check Payments and Invoices under Essentials CMS after setting up a provider, so you know payments arrive.
- API keys. Revoke keys on API that are no longer used.
- Logs. Errors go to
storage/logs/laravel-YYYY-MM-DD.log(orlaravel.log). Pelican's log viewer reads the whole file, so very large logs (around 100 MB) make it fail. - The queue worker and the scheduler.
systemctl status pelican-queue, and that the cron line is still there (sudo crontab -l -u www-data).
Updating
This plugin checks for and installs no updates by itself. Updates reach it in two ways:
- Through Pelican. A panel that installed it from Pelican Hub sees Update under Admin -> Plugins when the Hub has a newer release. You can also download a newer zip from the Essentials website and import it the same way as the first install.
- Through the Essentials Auto Updater. Stable, beta and dev builds from the Essentials website. When it is installed, the dashboard block and Essentials settings -> Updates show what it reports for this plugin.
Make a database backup before updating; the shop, tickets and API keys live in tables. Settings in .env and storage/app/private/legend-theme/ are kept. An update clears the caches and switches the plugin back on by itself.
Coming from 3.225 or earlier. Those versions fetched their own releases. Install a current version once (from the Hub, or through the Essentials Auto Updater). Install the Auto Updater first if you want it to carry over your channel and automatic-update choice (LEGEND_THEME_CHANNEL, LEGEND_THEME_AUTO_UPDATE*). The new version blanks a saved LEGEND_THEME_DEV_TOKEN and stops reading LEGEND_THEME_CHANNEL, LEGEND_THEME_AUTO_UPDATE*, LEGEND_THEME_BETA_URL and LEGEND_THEME_DEV_URL; those lines can be removed from .env afterwards. Revoke that GitHub token on GitHub as well.
Coming from an earlier name. The plugin was called legend-development-theme (up to 2.46) and pelican-essentials (up to 2.53). Pelican sees each name as a different plugin, so Update cannot carry you across. Make a database backup, then once: Admin -> Plugins -> the old entry -> Uninstall, and install essentials as above. Your settings and permissions survive, because they are not tied to the plugin's name.
Moving to the modules
Every part of this plugin now has a module (see What it includes). What carries over:
- Data in the database. The shop, support desk and API modules took over this plugin's tables by name, so orders, invoices, payments, tickets and API keys are read where they already are.
- Settings. The modules start from the old
LEGEND_THEME_settings in.envfor anything you have not yet saved in the module, and several of them read the files instorage/app/private/legend-theme/(announcements, links, custom CSS, alert channels, status pages, ticket attachments and more). Leave both in place. - Switches. The modules read
LEGEND_THEME_FEATURES_OFFuntil they have saved switches of their own, so a part you had switched off here starts off in the module too. - Permissions. The modules copy what your roles were granted in this plugin's section, once, into their own sections. Check the roles afterwards.
The steps:
-
Make a full database backup and keep it somewhere off the panel. MySQL or MariaDB:
mysqldump -u <DB_USERNAME> -p <DB_DATABASE> > ~/panel-before-modules.sql(the names are in.env). SQLite (Pelican's default): copy/var/www/pelican/database/database.sqlite. Also copy.envandstorage/app/private. On Essentials settings, press Export the records and Export settings for an extra copy. -
Install the modules you need, following each module's guide. Installing them switches this plugin off, or every part they take over.
-
Check that everything works: orders, invoices and tickets are there, API keys still answer, the look and announcements are right, and your roles have the module permissions they need.
-
Keep this plugin disabled. Under Admin -> Plugins it should show Disabled; press Disable if it does not. Do not update or reinstall it, because that switches it back on.
-
Do not press Uninstall on this plugin. Pelican's uninstall drops the shared tables. When you want it gone, remove its folder by hand:
sudo rm -rf /var/www/pelican/plugins/essentials cd /var/www/pelican sudo -u www-data php artisan optimize:clear sudo -u www-data yarn build sudo systemctl reload php8.4-fpm sudo systemctl restart pelican-queueyarn buildremoves this plugin's styles from the panel's frontend build, which Pelican's own uninstall would also do. Leave theLEGEND_THEME_lines in.envand thestorage/app/private/legend-theme/folder alone: the modules read them.
Recent versions of this plugin skip a table during uninstall when the module that took it over (essentials-shop, essentials-support or essentials-api) has a folder under plugins/. Older versions drop all of them, and once those module folders are gone nothing protects the tables. Do not rely on this check.
Removing it
Only for a panel that will run neither this plugin nor the modules. If you are moving to the modules, follow Moving to the modules instead.
Before you start: make a database backup, and on Essentials settings press Export the records (every package, order, invoice, payment and ticket as one file; API keys cannot be restored from a file, only issued again; the button only shows when there are records) and Export settings. If you used Servers by role, press Take it all back on Server access first, or those people keep the servers.
Admin -> Plugins -> Essentials -> Uninstall:
- Drops these tables (except any whose module folder is present, see above):
essentials_packages,essentials_orders,essentials_order_addons,essentials_addons,essentials_invoices,essentials_invoice_orders,essentials_payments,essentials_credit,essentials_upgrades,essentials_coupons,essentials_customers,essentials_waitlist,essentials_tickets,essentials_ticket_messages,essentials_api_keys,essentials_api_writes,essentials_connections. Pelican's own confirmation does not mention this. - Clears the caches and rebuilds the panel's frontend.
- Does not touch the servers the shop created; they are Pelican's.
Left behind, to remove by hand if you want a clean panel:
- The
LEGEND_THEME_...lines in/var/www/pelican/.env. storage/app/private/legend-theme/(lists, files, ticket attachments, uploaded languages) andstorage/app/public/theme/(uploaded pictures).- The plugin folder
plugins/essentials, if Pelican did not delete it. - Egg artwork you set: it is stored as Pelican's own egg icons and stays on the eggs.
- Pelican account keys named "Discord (Essentials)", made when somebody tied a Discord account to their panel account. They keep working after the uninstall; each person can revoke theirs in their profile, where Pelican lists their API keys.
Then run sudo -u www-data php artisan optimize:clear.
Troubleshooting
| Problem | What to do |
|---|---|
| Install says enabled, but no pages appear | Check the folder is plugins/essentials in lowercase, then run sudo -u www-data php artisan p:plugin:list; it must say enabled. Run the install command again after any unzip. |
The panel does not load after updating from pelican-essentials or legend-development-theme |
The folder still has the old name. Rename it: cd /var/www/pelican/plugins && sudo mv pelican-essentials essentials, then cd /var/www/pelican && sudo -u www-data php artisan optimize:clear. |
| Styling or buttons missing after install | Rebuild the frontend: cd /var/www/pelican && sudo -u www-data yarn build. |
| After an update the style is back to Ember and the accent to orange | The panel is holding an old cached config. Run sudo -u www-data php artisan optimize:clear; your settings are still in .env. |
| Shop, tickets, alerts or API are missing on a new panel | They start switched off. Turn them on under Essentials -> Modules. |
| A shop address still answers after switching the shop off, or 404s after switching it on | Run sudo -u www-data php artisan optimize:clear to drop the cached routes. |
| Dashboard says "No queue worker answered" | Start or restart it: sudo systemctl restart pelican-queue. If systemd gave up: sudo systemctl reset-failed pelican-queue && sudo systemctl start pelican-queue. Set Restart=always. |
| Dashboard says the scheduler has not run | Add the cron line from Before you install for www-data. |
| Alerts are never sent | Check the queue worker, then use Send a test on Alerts to check the channel itself. |
| A part of this plugin vanished after installing a module | Expected: the module now provides it. Do not run both; see Moving to the modules. |
| Module pages vanished after installing this plugin | The modules read LEGEND_THEME_FEATURES_OFF until they have saved switches of their own. Disable this plugin, switch the parts on again in the modules and save. |
| The plugin switched itself back on | Every install or update does that. Disable it again under Admin -> Plugins, and do not reinstall it. |
| Log says "Legend Theme could not be switched on" | The web user cannot write plugins/essentials/plugin.json. Run sudo chown -R www-data:www-data /var/www/pelican/plugins/essentials, then Enable it under Admin -> Plugins. |
A list or file does not save, and the panel says to check that storage/app belongs to the user the panel runs as |
Give the folder back to the web user: sudo chown -R www-data:www-data /var/www/pelican/storage. |
Essentials is a community project by Legend Development. Not affiliated with or endorsed by the Pelican team.