Notifications
Get a message on your phone when a backup fails or an update goes wrong, through ntfy, Gotify, email, Discord, Slack, Telegram or Pushover.
On this page
Most of what LibrePortal does happens while you're asleep: nightly backups, app updates, certificate renewals. When it all works, you never need to know. When something fails, you want to hear about it the same day, not in three weeks when you go looking for a backup that isn't there.
Notifications do that. Tell LibrePortal where to reach you, and it sends a short message whenever a job fails.
What you'll be told about#
Everything LibrePortal does for you runs as a task, the list you see on the Tasks page: installing an app, backing it up, updating it, restoring it. When a task fails, LibrePortal sends a message like this:
homeserver: Backup of nextcloud failed
Backup of nextcloud failed (exit 1) at 05:02. Check the Backups page — the
previous snapshots are unaffected. Full log: WebUI → Tasks → <task id>.
The first line is the title, starting with your server's name, so you can tell servers apart if you have more than one. A failed update also says what it left behind: either the app was put back to its snapshot from before the update, or the snapshot couldn't be taken, so the update stopped before changing anything and the app is still on the version it had.
What to send decides which task results you hear about:
| Choice | Sends |
|---|---|
| Failures only (the default) | A message for every task that fails. |
| All task results | A message for every task that finishes, whether it worked or not. Chatty, but reassuring for a while on a new server. |
| Off | Nothing about tasks. |
There's also a Notify on successful backups setting, off by default. Switch it on to hear when a backup finishes well, without having to switch on All task results for everything else.
It covers every task, including ones you start yourself, like pressing Backup now. Tasks you cancel never send anything.
LibrePortal also checks every 15 minutes for a process that has been running far longer than it should, like a backup that has hung, and tells you about it. That warning is sent even when What to send is Off, as long as a channel is switched on.
Where the messages go#
You can use any of these, one or several at once:
| Channel | What you need |
|---|---|
| ntfy | A topic on an ntfy server: your own ntfy app, or the public ntfy.sh. |
| Gotify | Your Gotify server's address and an application token from it. |
| An address to send to, and LibrePortal's mail settings filled in and switched on. | |
| Discord | A webhook address for the channel. |
| Slack | A webhook address for the channel. |
| Telegram | A bot token from @BotFather, and the chat to post to. |
| Pushover | An application token and your user key. |
The easy way: ntfy on the same server#
ntfy is a small notification server with a phone app, and it's the simplest way to get LibrePortal's alerts on your phone without an account anywhere. Install it from the App Center, and LibrePortal sets itself up to use it:
- Install ntfy. When it starts, LibrePortal makes a private topic for its alerts, with a random name like
lp-and sixteen letters and numbers, and sends a test message to it. - Check the install output. If no other notification channel was on, it says LibrePortal will now send failed updates, backups and installs to this ntfy server. If you already had a channel, it fills in the ntfy settings but leaves ntfy switched off, so you don't suddenly get everything twice.
- Find the topic's name. It's treated like a password, so it isn't printed. Show it on the server with the command below.
- Subscribe on your phone. Install the ntfy app, add your server's ntfy address (from the app's page in LibrePortal) as a server, and subscribe to that topic. The test message is already waiting there.
Advanced Do this from the command line
sudo -u libreportal libreportal secret get system CFG_NOTIFY_NTFY_TOPIC
New to the command line? How to run LibrePortal commands →
Why the topic has a random name
On ntfy, anyone who knows a topic's name can read it. There's no password on top. A random name no one can guess is what keeps your server's failures between you and your phone.
Your phone has to be able to reach the ntfy server to get the messages. At home that's easy. Away from home, either make ntfy reachable through the LibrePortal VPN and leave the VPN on, or make it public.
If ntfy was already set up, or LibrePortal couldn't send the test message, it leaves your settings alone and says so.
Setting up the other channels#
Not in the WebUI yet
The WebUI doesn't have a page for notification settings yet. For now, change them from the command line on the server, as below. libreportal notify on its own lists the commands and how the settings work.
Settings are changed with libreportal config update, several at once, separated by |. For example, to send to a Gotify server:
Advanced Do this from the command line
sudo -u libreportal libreportal config update 'CFG_NOTIFY_GOTIFY=true|CFG_NOTIFY_GOTIFY_URL=https://gotify.example.com|CFG_NOTIFY_GOTIFY_TOKEN=your-app-token'
New to the command line? How to run LibrePortal commands →
Tokens, webhook addresses and ntfy topics are stored away from the settings file, like passwords, and never shown in logs. Your shell does keep a history of the commands you type, though, so clear it afterwards if others use the account.
These are the settings for each channel. Switch a channel on with true, and fill in its details:
| Channel | Settings |
|---|---|
| ntfy | CFG_NOTIFY_NTFY, CFG_NOTIFY_NTFY_URL (starts as https://ntfy.sh), CFG_NOTIFY_NTFY_TOPIC, and CFG_NOTIFY_NTFY_TOKEN for a protected topic |
| Gotify | CFG_NOTIFY_GOTIFY, CFG_NOTIFY_GOTIFY_URL, CFG_NOTIFY_GOTIFY_TOKEN |
CFG_NOTIFY_EMAIL, CFG_NOTIFY_EMAIL_TO |
|
| Discord | CFG_NOTIFY_DISCORD, CFG_NOTIFY_DISCORD_WEBHOOK |
| Slack | CFG_NOTIFY_SLACK, CFG_NOTIFY_SLACK_WEBHOOK |
| Telegram | CFG_NOTIFY_TELEGRAM, CFG_NOTIFY_TELEGRAM_TOKEN, CFG_NOTIFY_TELEGRAM_CHAT_ID |
| Pushover | CFG_NOTIFY_PUSHOVER, CFG_NOTIFY_PUSHOVER_TOKEN, CFG_NOTIFY_PUSHOVER_USER |
What to send is CFG_NOTIFY_EVENTS: failures, all or off.
Email goes out through LibrePortal's own mail settings, the ones in the Mail section of Admin → General. If those are switched off, email notifications are skipped even when they're on.
The public ntfy.sh is public
If you point ntfy at ntfy.sh rather than your own server, anyone who guesses your topic's name can read your messages, and every message carries your server's name. Use a long random topic, or run your own ntfy.
Sending a test#
Once a channel is on, check that it works:
Advanced Do this from the command line
sudo -u libreportal libreportal notify test
New to the command line? How to run LibrePortal commands →
Every channel that's switched on gets LibrePortal test notification, and the command says ok or failed for each. A failure shows the HTTP status the service answered with; most often it's a mistyped token or webhook address.
