Push Yourself

Push notifications can come in useful in many situations – from informing you that a backup job has been completed successfully to reminding you of upcoming deadlines. A push notification system usually consists of two parts: a cloud-based service and a client. The service receives and processes push notification requests received through the service's API and then sends them to the client app running on an Android or iOS device. Using any of the popular cloud-based push notification services brings a familiar set of problems. You are relying on a third party for processing your data, you remain at the mercy of a for-profit enterprise, and usually you have to pay for the services rendered.

But if you are willing to host your own notification system, Gotify [1] has got you covered. This open source solution allows you to roll out your own notification service with a minimum of effort and zero cost.

Installing Gotify

Gotify is based on the server/client model, and there are three pieces of the puzzle you need to take care of:

1. Install and configure the Gotify server.
2. Install the Gotify Android app on your device.
3. Use the Gotify command-line interface (CLI) tool or cURL to send push notifications.

The server component of Gotify is written in Go, and the project's website [2] provides Linux binaries for the 386, AMD64, ARM7, and ARM64 architectures. This means that you can run the server on practically any Linux machine, including Raspberry Pi. Distributed as a single self-contained executable, the Gotify server requires no installation. To deploy the server on a Raspberry Pi, use the commands in Listing 1 to grab the latest binary from the releases section, unpack the downloaded archive, make the binary file executable, and then execute the server.

01 wget https://github.com/gotify/server/releases/download/v2.0.6/gotify-linux-arm-7.zip
02 unzip gotify-linux-arm-7.zip
03 chmod +x gotify-linux-arm-7.zip
04 sudo ./gotify-linux-arm-7

By default, the Gotify server runs on port 80 (that's why you need to run it with sudo). If you already have another server running on this port, you need to reconfigure Gotify. To do this, grab the config.yml example file using the command:

wget -O config.ymlhttps://raw.githubusercontent.com/gotify/server/master/config.example.yml

Open the downloaded file, and replace the default port number with the desired one (e.g., 8080). Save the changes and place the file where the Gotify server executable is located. Then start the Gotify server and access its web UI by pointing a browser to the IP address and port of the machine on which Gotify runs. Log in using the default admin/admin username and password.

Using Gotify

Gotify's web UI is pretty bare-bones, so finding your way around it is not particularly difficult. The first thing you might want to do is to remove the default user and add a new one. Switch to the Users section, press the Create User button, specify the desired username and password, and enable the has administration rights option. Press Create, and you are done. You can then delete the default admin user.

The next step is to create an application. A Gotify application is a profile that makes it possible to identify the source of push notifications via a unique token. For example, if you have a backup shell script running on your server, and this script sends a push notification when a backup job is successfully completed, you can create a profile in Gotify for this specific script. To do this, switch to the Apps section, press Create application, then provide a name and a short description. Press Create and note the generated token. Gotify also allows you to replace the default app icon with a custom one. This can be particularly useful if you have multiple apps, as it lets you visually identify each app (Figure 1). For each app, Gotify creates an entry in the left sidebar, so you can easily view notifications for a specific app.

Figure 1: You can set up multiple applications, or profiles, in Gotify.

With the Gotify server up and running, you are ready to send your first notification. There are several ways to do this. The most straightforward one is to use the cURL tool. Since practically all mainstream Linux distributions come with this tool preinstalled, you don't need to install and configure any additional software for sending notifications. More importantly, using cURL makes it easier to integrate push notification functionality into shell scripts.

Pushing a notification with cURL is a matter of running the following command (replace IPADDRESS:PORT with the actual IP address and port of the Gotify server and TOKEN with the token of the app you created on the Gotify server):

curl -X POST "https://IPADDRESS:PORT/message?token=TOKEN" -F "title=This is a title" -F"message=Message goes here"

If everything works, you should see the received notification in the web UI (Figure 2). Of course, checking for new notifications using Gotify's web UI is not particularly practical. In most scenarios, you'd want to receive notifications instantly on your Android device. For that, you need to install the Gotify Android client either from the Google Play Store or F-Droid (just search for Gotify). Launch the Android app, enter the IP address of the Gotify server, provide your username and password, and press the Login button (Figure 3). To prevent Android from killing the app, disable the battery optimization for the Gotify app. With the Gotify app running, you can receive and manage notifications on your Android device (Figure 4).

Figure 2: You can view and manage incoming notifications using Gotify's web UI.

Figure 3: The Gotify Android app connects to the Gotify server.

Figure 4: The Android app lets you view and manage notifications.

cURL is not the only tool that you can use to send notifications. In fact, the Gotify project provides a dedicated CLI tool for the job. Similar to the server component, the CLI utility is distributed as a self-contained binary that requires no installation. Simply grab the latest release of the tool from the project's website [3], make the binary executable, and move it to the usr/bin directory using the command:

mv gotify /usr/bin/gotify

With the Gotify CLI tool, you don't have to specify the required information (IP address, port, and token) every time you send a notification. Instead, run the gotify init command, and the tool will guide you through a simple process of creating a configuration file containing all the necessary information. Once you've done that, sending a notification is as easy as running:

gotify push "Message goes here"

The Gotify CLI tool supports piping, so you can send a command's output as a notification message. The following example fetches weather conditions using the wttr.in service [4] for the specified city and pipes the output to the Gotify tool that pushes the data as a notification.

curl wttr.in/Tokyo?format="%l:+%c+%t+%w+%m" | gotify push

Want to send notifications directly from within the Firefox browser? The aptly named Gotify for Firefox add-on [5] allows you to do just that. Better still, you can use the add-on to send the currently viewed page as a notification.

Since pushing a notification to Gotify is done using a standard HTTP request, you can easily integrate notification functionality into scripts written in your preferred scripting language. The example in Listing 2 demonstrates how to send notifications using PHP. The astute reader will probably notice that this PHP script sends Markdown-formatted notifications. To see the script in action, paste the code in the listing into a text file, replace the default value of the $url variable with the actual IP address and token, and then save the file under the gotify.php name. Make sure that PHP and the php-curl package are installed on your system. You can then send a push notification using the following command as an example:

php gotify.php "Markdown!" "**Yes**, Markdown formatting _is_ supported."

01 <?php
02     $data = [
03     "title"=> $argv[1],
04     "message"=> $argv[2],
05         "extras" => [
06         "client::display" => [
07             "contentType" => "text/markdown"
08         ]
09     ]
10 ];
11
12 $data_string = json_encode($data);
13
14 $url = "http://127.0.0.1:8080/message?token=AQiPyW7ATHGWgZg";
15
16 $headers = [
17     "Content-Type: application/json; charset=utf-8"
18 ];
19
20 $ch = curl_init();
21 curl_setopt($ch, CURLOPT_URL, $url);
22 curl_setopt($ch, CURLOPT_POST, 1);
23 curl_setopt($ch, CURLOPT_HTTPHEADER, $headers );
24 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true );
25 curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);
26
27 $result = curl_exec($ch);
28 $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
29
30 curl_close ($ch);
31
32 switch ($code) {
33 case "200":
34         echo "Message submitted";
35         break;
36     case "400":
37         echo "Bad request";
38         break;
39     case "401":
40         echo "Unauthorized error: invalid token";
41         break;
42     case "403":
43         echo "Forbidden";
44         break;
45     case "404":
46         echo "API URL not found";
47         break;
48     default:
49         echo "Something went wrong or HTTP status code is missing";
50 }
51 ?>

With a little bit of tweaking, you can embed this example PHP code into your own PHP-based web application.

In Conclusion

Gotify is a perfect replacement for existing commercial push notification services. It requires no installation, it has modest requirements, and its web UI makes it easy to administer the server component and manage received notifications. The fact that you can use any tool or scripting language capable of sending HTTP requests to send notifications means that you can add the notification functionality to your scripts and applications with a minimum of effort.