Install Gotify with Docker on Debian

Introduction

Gotify is an open-source, self-hosted server for sending and receiving push notifications. It provides a simple REST API so that applications, scripts, and monitoring tools can send notifications to any device running the Gotify Android app or a browser client. This tutorial shows step-by-step how to install Gotify via Docker on a cloud server with Debian 13 and how to send your first notification via the API.

Prerequisites

• 1 server (e.g. with Hetzner)
  • Debian 13
  • Access to the root user or a user with sudo permissions

Example terminology

• Username: holu
• Email: email@example.com
• Server: <203.0.113.1>

Step 1 - Connect via SSH

If you don't have an SSH key yet, create one now on your local machine:

ssh-keygen -t ed25519 -C "email@example.com"

The key is saved in ~/.ssh/id_ed25519.pub. Add the content of this file in the Hetzner Console under "Security" » "Add SSH key" so that you can use it later to connect to your server.

Now create a server in the Hetzner Console. Select Debian 13 as the OS image and the SSH key you just added. After the server is created, you get its IP address.

Connect to the server by opening a terminal and running the following command. Replace 203.0.113.1 with the actual IP address of your server:

ssh root@203.0.113.1 -p 22

Step 2 - Update the system

Once you are connected to the server, make sure that the system is up-to-date by running these commands:

sudo apt update
sudo apt upgrade -y

These commands update the package list and install the latest versions of packages on your server.

Step 3 - Install Docker

Gotify runs inside a Docker container. Install Docker with the following commands as explained in the official documentation:

# Add Docker's official GPG key:
sudo apt update
sudo apt install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

After the installation, check if Docker was installed as expected:

sudo systemctl status docker

If Docker was installed successfully, the output should show that the Docker service is active and running.

Click here to expand an example output

holu@example-server:~$ sudo systemctl status docker
● docker.service - Docker Application Container Engine
     Loaded: loaded (/usr/lib/systemd/system/docker.service; enabled; preset: enabled)
     Active: active (running) since Mon 2026-06-22 09:00:00 UTC; 10s ago
 TriggeredBy: ● docker.socket
       Docs: https://docs.docker.com
   Main PID: 1234 (dockerd)
      Tasks: 10
     Memory: 28.5M (peak: 30.6M)
        CPU: 312ms
     CGroup: /system.slice/docker.service
             └─1234 /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock

If Docker isn't running, you can start it with:

sudo systemctl start docker

Step 4 - Install Gotify

Now that Docker is installed, you can set up Gotify. First, create a directory for Gotify and change into it:

mkdir gotify
cd gotify

Create a file called docker-compose.yml with the following content:

services:
  gotify:
    image: gotify/server
    container_name: gotify
    ports:
      - "8080:80"
    environment:
      - GOTIFY_DEFAULTUSER_PASS=changeme
    volumes:
      - ./gotify-data:/app/data
    restart: always

A few notes about this configuration:

• Port 8080 on the host is mapped to port 80 inside the container, so you can reach the Gotify web interface at http://<203.0.113.1>:8080.
• GOTIFY_DEFAULTUSER_PASS sets the initial password for the default admin user. Change changeme to a strong password before starting the container.
• Gotify data (users, applications, messages) is stored in ./gotify-data on your server so that it is retained even after the container is restarted.

Save the file and start the Gotify container:

docker compose up -d

Check that the container started successfully:

docker ps -a

The container named gotify should appear with the status Up.

Step 5 - Access the Gotify web interface

Open a web browser and navigate to http://<203.0.113.1>:8080. You will see the Gotify login page.

Log in with the username admin and the password you set in GOTIFY_DEFAULTUSER_PASS.

After logging in, you will see the Gotify dashboard. It is still empty — no applications or messages exist yet.

Step 5.1 - Change the admin password

It is a good idea to change the default admin password right after the first login, even if you already set a custom value via the environment variable.

• Click on the user icon in the top right corner.
• Select "Users" from the menu.
• Click on the edit icon next to the admin user.
• Enter a new password and confirm it.
• Click "Update" to save the change.

Step 6 - Create an application and send a test notification

Gotify uses applications as senders of notifications. Each application has a unique token that is used to authenticate API requests. You need to create at least one application before you can send messages.

Step 6.1 - Create an application

• In the Gotify web interface, click on "Apps" in the left sidebar.
• Click "Create App".
• Give the application a name, for example test-app, and optionally add a description.
• Click "Create" to save the application.

After creating the application, Gotify displays a token for it. Copy this token — you will need it in the next step to send a notification.

Step 6.2 - Send a test notification via the API

Gotify exposes a REST API for sending messages. You can use curl to send a test notification from the command line. Replace <your-app-token> with the token you copied in the previous step, and replace 203.0.113.1 with the IP address of your server:

curl -X POST "http://203.0.113.1:8080/message?token=<your-app-token>" \
  -F "title=Hello from Gotify" \
  -F "message=This is a test notification." \
  -F "priority=5"

If the request succeeds, the API returns a JSON object describing the new message:

{
  "id": 1,
  "appid": 1,
  "message": "This is a test notification.",
  "title": "Hello from Gotify",
  "priority": 5,
  "date": "2026-06-22T10:00:00Z"
}

Switch back to the Gotify web interface. The message should now appear in the dashboard under the application you just created.

The priority field is a number between 0 (minimum) and 10 (maximum). Applications such as the Gotify Android app can use this value to decide whether to show a silent notification or a high-priority alert.

Conclusion

You now have a running Gotify instance that you can use to send push notifications via a simple REST API. You can integrate Gotify into your own scripts, monitoring setups, or automation pipelines by sending HTTP POST requests to your Gotify server.

Next steps:

License: MIT