uuNotify¶

uuNotify is a script that can be used to regularly check for updates of software, which you have installed on your Uberspace.

It requires a gotify server, which will send notifications to your client (e.g. a smartphone), if updates are available. The script will not install the updates automatically.

Note

For this guide you should be familiar with the basic concepts of

Node.js and its package manager npm
The concepts mentioned in the Gotify Guide

Furthermore, you need a GitHub account to create a personal access token. The token is only used for fetching the latest release information from GitHub. No scopes required.

Note

Wherever mentioned, replace v0.0.0 with the latest version tag.

License¶

All relevant legal information is mentioned in uuNotify’s LICENSE.

Prerequisites¶

Node.js version¶

We’re using Node.js version 14.

[isabell@stardust ~]$ uberspace tools version use node 14
Selected Node.js version 14
The new configuration is adapted immediately. Minor updates will be applied automatically.
[isabell@stardust ~]$

Gotify Server¶

You have installed and configured your Gotify server, as described in the respective guide.

Limitations¶

Since uuNotify uses the GitHub API, only software available on GitHub is checked for updates. It is planned to support other release feeds in a future version of uuNotify (see uuNotify GitHub issues).

Installation¶

Clone the GitHub repository, checkout the latest version and run the setup script.

[isabell@stardust ~]$ UUN_VERSION=v0.0.0
[isabell@stardust ~]$ git clone https://github.com/franok/uu-notify
[isabell@stardust ~]$ cd uu-notify/
[isabell@stardust uu-notify]$ git checkout $UUN_VERSION
[isabell@stardust uu-notify]$ git branch
* (HEAD detached at <latest version>)
  main
[isabell@stardust uu-notify]$ ./setup.sh
--- uuNotify setup ---
Existing files in config/ will not be overwritten.

Running 'npm clean-install' ...
[...]
Done.

Copy configuration files...
Creating config.json from config.json.template ...
Done.
Creating software-deps.mjs from software-deps.mjs.example ...
Done.

--- COMPLETED uuNotify setup ---
[isabell@stardust uu-notify]$

Configuration¶

Gotify application¶

Create a Gotify application. Log in to your Gotify server’s WebUI, click the Apps-tab in the menu bar and create an application. An app token is generated automatically. You’ll need it in the next step.

Configure uuNotify¶

In the uuNotify directory, navigate into the config/ folder:

[isabell@stardust uu-notify]$ cd config/
[isabell@stardust config]$

Edit the file config.json.

Add your Gotify server url and the app token from the previous step. Example:

{
  "gotify": {
      "url": "https://isabell.uber.space/gotify",
      "token": "AbccRsTUvwXX5yQ"
  },
  [...]
}

Note

The gotify server URL must end without trailing forward slash /

Good example: https://isabell.uber.space/gotify

Bad example: https://isabell.uber.space/gotify/

Now add your personal GitHub access token. This token does not require any scopes. Example:

{
  [...]
  "github": {
      "personalAccessToken": "ghp_oJoo9cootieKieyahzei7eifieHiyoh6"
  }
}

Add your software dependencies¶

Edit the file software-deps.mjs and add a new object into the array for every software you wish to receive update notifications for. Example:

export const software = [
  {
      name: "uu-notify",
      feedUrl: "https://github.com/franok/uu-notify/releases.atom",
      github: {
          org: "franok",
          repo: "uu-notify"
      }
  },
  {
      name: "other-software-name",
      feedUrl: "https://github.com/org/repo/releases.atom",
      github: {
          org: "org-name",
          repo: "repo-name"
      }
  }
];

If you wish to add further software later, just update this file. With the next (scheduled) execution, uuNotify will also check for updates for the newly added entries.

Client side¶

To receive the uuNotify update notifications, you need to have a Gotify client in place. You can use Gotify’s built-in web-ui, or the Android app (available via F-Droid, GooglePlay or direct APK download). There is no native iOS App, but iPhone users could use the web-ui and get browser notifications.

Finishing installation¶

Initialize uuNotify by running the script manually:

[isabell@stardust ~]$ cd uu-notify/
[isabell@stardust uu-notify]$ node index.mjs
Script finished.
[isabell@stardust uu-notify]$

You should receive initial notifications for all your registered software.

After that, register uuNotify in your crontab.

[isabell@stardust ~]$ crontab -e

Copy and paste the following lines into your crontab, by appending them to the end of the existing entries:

#MAILTO=""
0 18 * * SUN /usr/bin/node /home/isabell/uu-notify/index.mjs

This crontab configuration will run uuNotify every Sunday at 18:00. If there are any software updates, you’ll receive a notification.

If you want uuNotify to check for updates more often, you can adjust the time and frequency to your needs. I suggest you to double check your cron schedule expression with crontab guru.

Check your crontab configuration:

[isabell@stardust ~]$ crontab -l
#MAILTO=""
0 18 * * SUN /usr/bin/node /home/isabell/uu-notify/index.mjs

Optional¶

Add an icon to your Gotify app¶

The Gotify app you created will show up in your Gotify client when notifications are received. You can customize it with an app icon, replacing the default “Go Gopher” mascot icon.

Create a client token in the Gotify WebUI (Client-tab).

Retrieve your app id. Adjust the placeholders in the following curl command and run it from your local computer:

[user@localhost ~]$ curl --header "X-Gotify-Key:<gotify-client-token>" https://<gotify-url>/application
[{"id":42,"token":"********","name":"uuNotify","description":"uuNotify","internal":false,"image":"static/defaultapp.png"}]
[user@localhost ~]$

Using the app id (in this case 42) run the next command:

[user@localhost ~]$ curl --header "X-Gotify-Key:<gotify-client-token>"  -k -X POST -F 'file=@/home/<localuser>/path/to/image/uu-notify-icon.png'  https://<gotify-url>/application/42/image
{"id":42,"token":"********","name":"uuNotify","description":"uuNotify","internal":false,"image":"image/RTHDR0253KDdQyw_FUBOEDom4.png"}
[user@localhost ~]$

The app should now have a custom icon.

For further details, see the Gotify API.

Updates¶

Note

Add uuNotify itself as software dependency in your config/software-deps.mjs file to get notified about new versions.

For details check the GitHub release page.

You can update uuNotify to the latest version as follows:

[isabell@stardust ~]$ UUN_VERSION=v0.0.0
[isabell@stardust ~]$ cd uu-notify/
[isabell@stardust uu-notify]$ cp -rp config/ backup-config/
[isabell@stardust uu-notify]$ git fetch
[...]
[isabell@stardust uu-notify]$ git checkout $UUN_VERSION
[isabell@stardust uu-notify]$ git branch
* (HEAD detached at <latest version>)
  main
[isabell@stardust uu-notify]$ ./setup.sh
--- uuNotify setup ---
Existing files in config/ will not be overwritten.
Running 'npm clean-install' ...
[...]
Done.

Copy configuration files...
config.json already exists. Skipping...
software-deps.mjs already exists. Skipping...

--- COMPLETED uuNotify setup ---
[isabell@stardust uu-notify]$

Double check your configuration (config/config.json and config/software-deps.mjs). If everything looks okay, remove the backup folder:

[isabell@stardust uu-notify]$ rm -rf backup-config/
[isabell@stardust uu-notify]$

Troubleshooting¶

If you encounter any issues, e.g. during the installation or update process, you might want to check for the project’s GitHub issues that have a workaround label for a quick solution. If you don’t find any useful information there, you can report a bug.

Tested with uuNotify 1.1.2, Uberspace 7.11.3.0

Written by: franok <https://franok.de>