Essentials Mobile
Essentials Mobile makes the Pelican panel work better on phones. People can install the panel on their home screen, where it opens like an app with its own icon and name; the pages get a layout that is easier to use with a thumb; and everything that lands in somebody's notification bell can also reach their phone or browser as a push message, even with the panel closed. It is for every panel whose customers or staff use it on a phone. Push messages use a key pair the panel makes itself, so no account with an outside service is needed.
At a glance
| Plugin ID | essentials-mobile |
| Current version | 0.1.2 |
| Pelican Panel | 1.0 (tested on 1.0.0-rc.2) |
| Needs | An https address for the panel (phones only install apps from one). The queue worker, for sending push messages. The panel's frontend build (Node.js and Yarn), because the plugin ships stylesheets and scripts. No scheduler entry. |
| Works with (optional) | Essentials Core, Essentials Appearance (the app takes the panel's style colours) |
| Adds | Admin area, sidebar group Essentials Mobile: page Mobile (the settings, /admin/essentials-mobile). For everybody: Install app and Notifications on this device in the user menu, an install bar at the foot of the page on phones, the phone layout, and an offline page inside the installed app. One table, essentials_mobile_push_subscriptions. |
| Permissions | Role editor section Essentials Mobile: view (open the settings page without changing anything) and update (change the settings) |
Before you install
- The panel on https with a valid certificate, and
APP_URLin/var/www/pelican/.envset to thathttps://address. Phones only install an app from a secure address. The plugin decides whether the panel is secure fromAPP_URL, so a panel served over https withAPP_URLstill onhttp://is treated as insecure. - Outgoing https from the panel server to the push services browsers use: Google (
fcm.googleapis.com), Mozilla (push.services.mozilla.com), Microsoft (notify.windows.com) and Apple (push.apple.com). A firewall that blocks these stops push messages. - For a custom app icon: PHP's GD extension. Without it the shipped Essentials icon is used.
- The queue worker (Pelican's background worker, usually the systemd service
pelican-queue). Installs started from the admin area run there, and push messages are sent from it. Check it withsystemctl status pelican-queue. - Node.js and Yarn on the panel server. Pelican compiles the plugin's stylesheets and scripts into the panel's own frontend build when the plugin is installed. The build must run as the panel's web user.
- Pelican Panel 1.0. Pelican 1.0.0-rc.2 itself needs PHP 8.4 or 8.5.
- Not the legacy all-in-one "Essentials" plugin (plugin id
essentials) on the same panel. The all-in-one never made the panel installable, so there is nothing to take over from it, but it must not run beside anyessentials-*module. See "Things to watch out for". - Essentials Core is optional. With Core installed this module appears in Core's module list on the Essentials page, with its switches in the Parts window and its health notes. Without Core it works on its own. Essentials Appearance is optional too; without it the app uses a dark grey.
Installing
Download the plugin from the Essentials website, https://essentialsplugins.nl: sign in, open the catalogue, pick Essentials Mobile and a version, and download the zip. x.y.z is a stable release, x.y.z-beta a test release and x.y.z-dev a development build. Use stable on a live panel.
Then install it one of these ways. The first is the easiest.
-
From the admin area. Go to Admin -> Plugins -> Import from File and choose the zip. The plugin appears in the list; press Install. 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. You make that key on the panel under Admin -> API keys, with read and write on Plugins; it starts with
papp_. Then press Install on the plugin's page on the website. -
With the Essentials Auto Updater. If that plugin is installed, its Plugin updates page offers Essentials modules that are not installed yet.
-
From the command line (advanced). The examples 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).cd /var/www/pelican sudo unzip essentials-mobile-x.y.z.zip -d plugins/ sudo chown -R www-data:www-data plugins/essentials-mobile sudo -u www-data php artisan p:plugin:install essentials-mobile sudo -u www-data php artisan p:plugin:listThe folder must be exactly
plugins/essentials-mobile. The list must show the plugin as enabled. Unzipping over an existing plugin folder resets it to "not installed" (its status is kept in its ownplugin.json), so always run the install command again after unzipping.
The install runs one migration, which creates the table essentials_mobile_push_subscriptions (one row per device that turned notifications on, up to ten per account: the oldest makes way for a new one). After installing, all three parts are switched on: the app, the phone layout and notifications.
After every install:
- The plugin clears Pelican's route and view caches and asks the queue worker to restart. 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). - If the install bar or the phone layout is missing, rebuild the frontend:
cd /var/www/pelican && sudo -u www-data yarn build. With Essentials Core, the Panel health section on the Essentials page reports missing built assets. - 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
- Give the roles that manage the panel the permissions: Admin -> Roles, open a role, section Essentials Mobile. Tick
viewfor people who may look,updatefor people who may change the settings. Root Admins have both already. Installing the app, the phone layout and notifications need no permission; they are for everybody. - Open the Admin area, sidebar group Essentials Mobile, page Mobile. If the top says "This panel is served over http, not https", set up https first; nobody can install the app until then.
- In the section App on the home screen:
- Leave Offer the panel as an app on.
- Suggest it on phones shows a small bar at the foot of the page on phones that can install the app. Off leaves only Install app in the user menu.
- App name and Name under the icon: empty uses the panel's own name. The home screen has room for about twelve characters.
- Icon: a square PNG, JPEG or WebP of at least 512 by 512 pixels (at most 4 MB). Empty uses the Essentials icon. Phones round the corners or cut it to a circle, so keep what matters in the middle.
- Choose my own colours: off, the app takes the background colour of the panel's style and changes with it. On, set Status bar colour and Splash screen colour yourself.
- Opens as: An app, with the phone's status bar, Full screen, without the status bar or An app with a small address bar.
- Opens on: The server list or The admin area. Only administrators can use the admin area, so choose the server list for an app everybody uses.
- In the section Phone layout, leave Lay the panel out for phones on.
- In the section Notifications on phones, leave Send notifications to phones and browsers on. The line under it says how many devices receive notifications.
- Press Save at the bottom of the page. The page reloads.
Then try it on a phone:
- Open the panel in the phone's browser (Safari on an iPhone or iPad) and sign in.
- Use the install bar, or Install app in the user menu (at the foot of the sidebar on the admin and server panels). Where the browser can install, it offers to. On an iPhone or iPad a step-by-step guide shows Safari's buttons: Share, Add to Home Screen, Add. Inside another app's browser (a link opened from Discord, for example) it says to copy the link and open it in Safari first.
- Open the app from the home screen.
- In the user menu, choose Notifications on this device and press Turn on. Allow notifications when the phone asks.
- The next notification that lands in your bell also arrives on the phone. Tapping it opens the notification's link in the panel.
What each part does
App on the home screen. Every page of every panel, the sign-in page included, carries what phones need to install the panel: a web app manifest, icons in every size, and the tags iOS reads. A closed install bar stays away for a month on that device; once the app is installed it stays away for good. Inside the installed app, a page that cannot load because there is no connection shows a short offline notice in the phone's language. Nothing a person sees is cached, so there is never an old copy of somebody's servers.
Phone layout. Text fields are large enough that Safari no longer zooms in when one gets the focus; buttons, tabs, menu rows and the sidebar toggle are at least finger-sized; tables wider than the phone show an edge where there is more to scroll to; every page has room at the end so floating buttons do not cover the last row; the client area shows the panel's logo and name in the header; and notifications appear below the header instead of over its bell and menu.
Notifications on phones. Everything that lands in somebody's notification bell, from Pelican or any plugin (a ticket reply, an invoice, a failed backup, a finished update), is also sent to every phone and browser that person turned notifications on for. Each person turns it on per device from Notifications on this device in their user menu. Messages are encrypted for each device, sent from the queue worker, and only ever link to pages of this panel.
Things to watch out for
- On an iPhone or iPad, notifications only work in the installed app, on iOS 16.4 or later. In Safari itself the menu entry says to add the panel to the home screen first.
- Changing
APP_KEYresets notifications for everybody. The panel's own push key pair is kept in the settings file with the private half encrypted with the panel'sAPP_KEY. IfAPP_KEYchanges (or a backup is restored onto a panel with a different one), the panel makes a new key pair and forgets every device, and everybody has to turn notifications on again. KeepAPP_KEYwith your backups. - Do not delete the settings file while devices are subscribed. It holds the key pair. Without it the panel makes a new one, and devices that subscribed with the old one stop receiving messages until people turn notifications on again.
- Shared devices. From 0.1.1 on, signing out stops the notifications that were turned on in that sign-in, on that device, so the next person is not sent the previous one's. A device turned on with 0.1.0 is not covered until it is turned off or turned on again once; on such a shared phone or computer, use Notifications on this device -> Turn off before signing out.
- The app part carries the notifications. Switching off Offer the panel as an app also stops push messages, because the app's service worker shows them. Switching off Send notifications to phones and browsers stops every message at once but keeps the devices subscribed, so switching it back on needs nobody to do anything.
- Messages expire after a day. A phone that is off or offline for longer than that does not get the message later. The notification is still in the bell.
- Devices are forgotten when they fail. A device the push service no longer knows is removed at once; one that keeps failing is removed after ten tries. The person then has to turn notifications on again on that device.
- Opening on the admin area. With Opens on set to The admin area, anybody who is not an administrator is refused when they open the app.
- Switching the app off later. Phones that installed the app remove its offline helper on their next visit, and the app then opens as an ordinary page.
- The legacy all-in-one plugin. "Essentials" (plugin id
essentials) is the older plugin that contains what the modules now do separately. Never run it on the same panel as anyessentials-*module: installing a module switches the all-in-one off, installing the all-in-one on a panel with modules can switch modules off, and uninstalling the all-in-one deletes database tables the modules share (shop, tickets, API keys). Pick one: the all-in-one, or the modules.
Things to keep an eye on
- Health notes. With Essentials Core, the module's row on the Essentials page says "The panel is served over http, so phones will not install it as an app." while
APP_URLis not an https address. The Mobile page shows the same warning at the top. - The device count under Notifications on phones on the Mobile page.
- The queue worker. Push messages are sent from it; if it stops, nothing reaches the phones (the bell still works). Recommended:
Restart=alwayson thepelican-queueservice, and a drop-in withStartLimitIntervalSec=0under[Unit](sudo systemctl edit pelican-queue) so systemd never gives up restarting it after repeated crashes. If it has given up,sudo systemctl reset-failed pelican-queue && sudo systemctl start pelican-queuebrings it back. - Logs. Failed deliveries are logged as "Essentials Mobile: a push message could not be delivered: ..." with the reason. 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; Essentials Core warns above 50 MB.
Updating
Download the new version and import it the same way you installed it (Pelican shows Update on the plugin when an update is known), or let the Essentials Auto Updater do it. The module switches itself back on after an update through the admin area. Settings, the key pair and the subscribed devices are kept. Make a database backup before updating, because the module keeps the devices in a table.
Removing it
If people installed the app, switch off Offer the panel as an app on the Mobile page first and leave the plugin installed for a while. Phones that visit in that time drop the app's offline helper.
Then uninstall it under Admin -> Plugins, or from the command line:
cd /var/www/pelican
sudo -u www-data php artisan p:plugin:uninstall essentials-mobile --delete
--delete also removes the plugin's files. Uninstalling drops the table essentials_mobile_push_subscriptions: every device is forgotten, which is fine, because the subscriptions are of no use without this plugin's key pair. Notifications stay in the panel's bell as before.
Files left behind:
storage/app/private/essentials/mobile/:settings.json(including the key pair) and the scaled icons inicons/.storage/app/public/essentials-mobile/: an icon uploaded on the settings page.
Delete them by hand if you do not plan to reinstall:
sudo rm -r /var/www/pelican/storage/app/private/essentials/mobile
sudo rm -r /var/www/pelican/storage/app/public/essentials-mobile
Troubleshooting
| Problem | What to do |
|---|---|
| The Mobile page says the panel is served over http, but it uses https | Set APP_URL in /var/www/pelican/.env to the https:// address, then sudo -u www-data php artisan config:clear. |
| The phone offers no way to install | The panel must be on https. On an iPhone or iPad, open the page in Safari itself, not inside another app, and use Share -> Add to Home Screen. |
| Install app is missing from the user menu | It is hidden inside the installed app. Otherwise check that Offer the panel as an app is on. |
| Notifications on this device says notifications only work in the installed app | That is an iPhone or iPad outside the installed app. Add the panel to the home screen, open it from there and turn them on in its menu. iOS 16.4 or later is needed. |
| "This browser has blocked notifications from the panel" | Allow notifications for the site in the browser's or phone's settings, then press Turn on again. |
| Notifications are turned on but nothing arrives | Check that Send notifications to phones and browsers is on, that the queue worker runs, and that the panel server can reach the push services over https. Look for "a push message could not be delivered" in the log. |
| Notifications stopped for everybody at once | APP_KEY changed or the settings file was lost, so the key pair was made again. Everybody turns notifications on again on their devices. |
| The custom icon does not show | Use a square PNG, JPEG or WebP of at least 512 by 512 pixels, and check that PHP's GD extension is installed. Without GD the Essentials icon is used. |
| Saving shows "Could not save the settings" | The panel cannot write to its storage folder. Make sure storage belongs to the web user (sudo chown -R www-data:www-data /var/www/pelican/storage). The reason is in the log. |
| Install bar or phone layout missing after an install | Run cd /var/www/pelican && sudo -u www-data yarn build. |
| A new page answers 404 after installing or updating | Reload PHP-FPM (sudo systemctl reload php8.4-fpm) and restart the queue worker. |
Essentials is a community project by Legend Development. Not affiliated with or endorsed by the Pelican team.