Programster's Blog

Tutorials focusing on Linux, programming, and open-source

Deploying Gotify For Phone Push Notifications

Table Of Contents


This tutorial will show you how to deploy Gotify, an open source notification tool you can run on your server and subscribe to using the Android APP, so that you can receive push notification alerts.

I was interested in this because I wanted a way to easily receive alerts from Uptime Kuma monitoring alert notifications on my phone, so I know immediately if some service goes offline.

I believe there is an app for iOS, but the advice in this blog is targeted towards Android users.


Docker Deploy Script

One could use Docker compose to deploy Gotify, but that seems like overkill. If you create the following BASH script on your server where you wish to install Gotify, then you can just run it, and it will deploy gotify for you and store all the state in a local folder within there.


DIR=$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )
mkdir -p $VOLUME_DIR

docker run \
  -d \
  -p 80:80 \
  --restart=always \
  -v $VOLUME_DIR:/app/data \

Optional - Configure Reverse Proxy

The script above will deploy Gotify using plain HTTP on port 80 (there is no HTTPS protection).

You may wish to configure your reverse proxy (if you have one) for forwarding traffic onto Gotify. Be sure to perform the relevant configurations for websockets.

For those who [manually deployed an Nginx proxy](https://blog.programster. org/debian-9-set-up-nginx-reverse-proxy), you can find my Nginx configuration in the appendix.

For those who want to deploy an Nginx reverse proxy that has an easy-to-use web interface, you may wish to check out my tutorial on how to deploy Nginx proxy manager.

Log In

Once that has deployed Gotify, you can connect to it by going to your server's IP or domain name in your browser on port 80

Then you can connect on:


You should be able to log in for the first time with the following credentials:

  • user: admin
  • password: admin

Change Password

Before you do anything else, I would recommend you immediately change the password by clicking on the profile icon:

Install Phone App

Now that you have your own Gotify server, you can download the Android app so that you can log in on your phone and receive push notifications.

Separate App Notification Channels

I found that the push notifications would not show up on my phone until I went into the app, then clicked the burger menu, and went to settings, before clicking on Separate app notification channels. Now when an app sends a notification, it appears immediately on my phone.

Optional - Remove "Connected" Message

I found it annoying that the Gotify app permanently had a notification bar at the top showing "connected". To get rid of this, one has to go into the Android settings for that particular app's notifications (not a setting within the app itself), and disable the "Gotify foreground notification" by pressing the toggle. Now I still receive Gotify notifications, and an unread notification still shows in the notifications panel, but I don't permanently see the "connected" message.

Testing It Works

Create Gotify Application

To test that our Gotify server is working and our phone will receive push notifications, we first need to create an "application" that will receive notifications, and we will subscribe to. In my case, I set up an application for Uptime Kuma to send notification alerts to.

Click on Apps(1) and then Create Application (2)

Fill in the pop-up modal for details about the application you are creating...

Then click on the eye symbol (1) to reveal the token for the application. This token acts as the "password" for third-party applications such as Uptime Kuma to be able to post messages to this application's notification feed.

Send Curl Request

Now that we have an application and its token, we can create a notification by sending a request to the REST API through curl.


curl "$GOTIFY_SERVER/message?token=$GOTIFY_APP_TOKEN"   \
  -F "title=Title of my message" \
  -F "message=Message body here" \
  -F "priority=10"

Be sure to change the GOTIFY_APP_TOKEN and GOTIFY_SERVER as appropriate to your setup.

If everything went well, you should have received a push notification on your phone alerting you to that notification.

Priority Setting

It is worth noting that the priority=10 is an important setting as it has an impact on behaviour. E.g. users may choose to only show the push notifications on a certain level or higher. E.g. with a level of 0, the notification will appear in the feed, but this won't trigger a push notification alert.


Nginx Reverse Proxy Configuration

If you are running a manually deployed Nginx reverse proxy, then you need to make sure that the
configuration is set up in a way that facilitates the websockets. Below is my configuration that you may wish to tweak (e.g. changing the FQDN and the internal forwarding IP etc.).

server {
    listen 80;
    return 302$request_uri;

server {
    listen 443 ssl;

    ssl on;


    access_log  /var/log/nginx/access.log;

    ssl_certificate      ssl/;
    ssl_certificate_key  ssl/;

    ssl_protocols        TLSv1.2;
    ssl_ciphers RC4:HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    keepalive_timeout    60;
    ssl_session_cache    shared:SSL:10m;
    ssl_session_timeout  10m;

    location / {
        proxy_pass    ;
        proxy_http_version      1.1; # 1.1 instead of 1.0 is required for websockets
        proxy_set_header        Upgrade $http_upgrade;
        proxy_set_header        Connection "upgrade";
        proxy_set_header        Host $http_host;
        proxy_set_header        X-Real-IP $remote_addr;
        proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header        X-Forwarded-Proto https;
        proxy_set_header        X-Nginx-Proxy true;
        proxy_redirect          off;

API Docs

If you are interested in building a custom application around Gotify's REST API, the OpenAPI documentation is available at:


Last updated: 16th October 2023
First published: 14th August 2023