Deploying Gotify

Introduction

Gotify is a simple, self-hosted push notification server that enables you to send real-time notifications to your devices. Built for developers and sysadmins who want complete control over their notification infrastructure, Gotify provides a lightweight alternative to proprietary push services.

Written in Go, Gotify uses WebSockets for instant message delivery and includes a sleek web interface for managing applications and viewing notifications. The platform supports multiple clients including Android, web browsers, and CLI tools.

Key highlights of Gotify:

• Self-Hosted: Complete control over your notification data
• Real-Time Delivery: WebSocket-based instant notifications
• Simple REST API: Easy integration with any application
• Multi-Application: Organize notifications by application
• Priority Levels: Set notification urgency from low to critical
• Web Interface: Manage applications and view messages
• Android App: Native Android client for mobile notifications
• Plugin System: Extend functionality with plugins
• Lightweight: Minimal resource usage, runs on low-power devices
• 100% Open Source: Licensed under MIT

This guide walks through deploying Gotify on Klutch.sh using Docker, configuring applications, and integrating notifications into your services.

Why Deploy Gotify on Klutch.sh

Deploying Gotify on Klutch.sh provides several advantages for push notifications:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Gotify without complex orchestration. Push to GitHub and your notification server deploys automatically.

Persistent Storage: Attach persistent volumes for your database and configuration. Notification history survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for secure WebSocket connections.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on notification volume.

Custom Domains: Assign a custom domain for your notification server.

Always-On Availability: Your notification server remains accessible 24/7 for real-time message delivery.

Prerequisites

Before deploying Gotify on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Gotify configuration
• Basic familiarity with Docker and containerization concepts
• (Optional) An Android device for mobile notifications

Understanding Gotify Architecture

Gotify is designed for simplicity:

Go Backend: Written in Go for excellent performance and minimal resource usage.

SQLite Database: Stores users, applications, and message history.

WebSocket Server: Real-time message delivery to connected clients.

REST API: HTTP endpoints for sending messages and managing the server.

Web UI: React-based interface for administration and viewing messages.

Preparing Your Repository

To deploy Gotify on Klutch.sh, create a GitHub repository containing your Dockerfile.

Repository Structure

gotify-deploy/
├── Dockerfile
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM gotify/server:latest

# Create data directory
RUN mkdir -p /app/data

# Expose the web interface port
EXPOSE 80

# The base image includes the default entrypoint

Advanced Dockerfile with Configuration

For more control:

FROM gotify/server:latest

# Set environment variables
ENV GOTIFY_SERVER_PORT=80
ENV GOTIFY_SERVER_KEEPALIVEPERIODSECONDS=0
ENV GOTIFY_SERVER_SSL_ENABLED=false
ENV GOTIFY_DATABASE_DIALECT=sqlite3
ENV GOTIFY_DATABASE_CONNECTION=data/gotify.db
ENV GOTIFY_DEFAULTUSER_NAME=${GOTIFY_ADMIN_USER:-admin}
ENV GOTIFY_DEFAULTUSER_PASS=${GOTIFY_ADMIN_PASS:-admin}
ENV GOTIFY_PASSSTRENGTH=10
ENV GOTIFY_UPLOADEDIMAGESDIR=data/images
ENV GOTIFY_PLUGINSDIR=data/plugins

# Create data directory
RUN mkdir -p /app/data /app/data/images /app/data/plugins

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:80/health || exit 1

# Expose the web interface port
EXPOSE 80

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
GOTIFY_SERVER_PORT	No	80	Port to listen on
GOTIFY_SERVER_KEEPALIVEPERIODSECONDS	No	0	WebSocket keep-alive (0 = disabled)
GOTIFY_DATABASE_DIALECT	No	sqlite3	Database type (sqlite3 or mysql)
GOTIFY_DATABASE_CONNECTION	No	data/gotify.db	Database connection string
GOTIFY_DEFAULTUSER_NAME	No	admin	Default admin username
GOTIFY_DEFAULTUSER_PASS	No	admin	Default admin password
GOTIFY_PASSSTRENGTH	No	10	Password hashing strength
GOTIFY_UPLOADEDIMAGESDIR	No	data/images	Directory for uploaded images
GOTIFY_PLUGINSDIR	No	data/plugins	Directory for plugins

Deploying Gotify on Klutch.sh

Once your repository is prepared, follow these steps to deploy Gotify:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile .dockerignore README.md
git commit -m "Initial Gotify deployment configuration"
git remote add origin https://github.com/yourusername/gotify-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “gotify” or “notifications”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Gotify Dockerfile.

Configure HTTP Traffic

Gotify serves its web interface and API over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 80

Set Environment Variables

In the environment variables section, add:

Variable	Value
GOTIFY_DEFAULTUSER_NAME	Your admin username
GOTIFY_DEFAULTUSER_PASS	A strong admin password

Attach Persistent Volumes

Persistent storage is essential for Gotify. Add the following volume:

Mount Path	Recommended Size	Purpose
/app/data	5 GB	Database, images, and plugins

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Gotify container
• Provision an HTTPS certificate

Access Gotify

Once deployment completes, access your Gotify instance at https://your-app-name.klutch.sh. Log in with the admin credentials you configured.

Initial Configuration

Changing the Default Password

If you didn’t set environment variables, change the default password immediately:

1. Log in with admin / admin
2. Click your username in the top right
3. Select Edit User
4. Set a strong password

Creating Applications

Each service that sends notifications needs its own application:

1. Navigate to Apps in the web interface
2. Click Create Application
3. Enter a name and description
4. Note the generated Token - this is used to send messages
5. Optionally set a custom image for the application

Creating Clients

Clients receive notifications:

1. Navigate to Clients in the web interface
2. Click Create Client
3. Enter a name for the client
4. Note the generated Token - this is used to receive messages

Sending Notifications

Using cURL

Send a notification via API:

curl "https://your-app-name.klutch.sh/message?token=YOUR_APP_TOKEN" \
  -F "title=Hello World" \
  -F "message=This is a test notification" \
  -F "priority=5"

Using Python

import requests

url = "https://your-app-name.klutch.sh/message"
headers = {"X-Gotify-Key": "YOUR_APP_TOKEN"}
data = {
    "title": "Hello World",
    "message": "This is a test notification",
    "priority": 5
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Using JavaScript

fetch("https://your-app-name.klutch.sh/message", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Gotify-Key": "YOUR_APP_TOKEN"
  },
  body: JSON.stringify({
    title: "Hello World",
    message: "This is a test notification",
    priority: 5
  })
});

Priority Levels

Priority	Description	Android Behavior
0	Min	No notification
1-3	Low	Silent notification
4-7	Normal	Sound and vibration
8-10	High	Sound, vibration, screen wake

Receiving Notifications

Web Interface

View notifications in the Gotify web interface:

1. Navigate to your Gotify URL
2. Messages appear in real-time via WebSocket
3. Click on messages to expand details
4. Delete messages individually or in bulk

Android App

Install the Gotify Android app:

1. Download from GitHub Releases or F-Droid
2. Add your server URL
3. Create a client token in the web interface
4. Enter the client token in the app
5. Receive push notifications on your phone

WebSocket Connection

For custom clients, connect via WebSocket:

const ws = new WebSocket("wss://your-app-name.klutch.sh/stream?token=CLIENT_TOKEN");

ws.onmessage = function(event) {
  const message = JSON.parse(event.data);
  console.log("New notification:", message.title, message.message);
};

Integration Examples

Uptime Kuma

Integrate with Uptime Kuma for monitoring alerts:

1. In Uptime Kuma, go to Settings > Notifications
2. Add a new notification type: Gotify
3. Enter your Gotify URL and app token
4. Test the notification

Home Assistant

Add Gotify notifications to Home Assistant:

notify:
  - name: gotify
    platform: rest
    resource: https://your-app-name.klutch.sh/message
    method: POST_JSON
    headers:
      X-Gotify-Key: YOUR_APP_TOKEN
    data:
      priority: 5
    title_param_name: title
    message_param_name: message

Server Monitoring Scripts

Send alerts from shell scripts:

#!/bin/bash
# Send notification when disk space is low
THRESHOLD=90
USAGE=$(df / | tail -1 | awk '{print $5}' | sed 's/%//')

if [ "$USAGE" -gt "$THRESHOLD" ]; then
  curl "https://your-app-name.klutch.sh/message?token=YOUR_APP_TOKEN" \
    -F "title=Disk Space Alert" \
    -F "message=Disk usage is at ${USAGE}%" \
    -F "priority=8"
fi

Security Considerations

Token Security

• Keep Tokens Secret: Treat application tokens like passwords
• Separate Tokens: Use different apps for different services
• Rotate Tokens: Delete and recreate apps if tokens are compromised

Access Control

• Strong Passwords: Use strong admin passwords
• HTTPS Only: Always use HTTPS (automatic on Klutch.sh)
• User Management: Create separate users for different purposes

Network Security

• Client Tokens: Don’t expose client tokens publicly
• API Tokens: Use environment variables for tokens in scripts
• Audit Applications: Regularly review active applications

Troubleshooting Common Issues

Notifications Not Arriving

Symptoms: Messages sent but not received.

Solutions:

• Verify the application token is correct
• Check WebSocket connection in browser dev tools
• Ensure HTTPS is working properly
• Verify the Android app is connected

WebSocket Connection Failed

Symptoms: Real-time updates don’t work.

Solutions:

• Check browser WebSocket support
• Verify HTTPS certificate is valid
• Try reconnecting the client
• Check for proxy interference

Android App Not Connecting

Symptoms: Cannot log in from mobile app.

Solutions:

• Verify the server URL includes https://
• Check the client token is valid
• Ensure the server is accessible from mobile network
• Try reinstalling the app

Additional Resources

• Official Gotify Website
• Gotify Documentation
• Gotify Server GitHub
• Gotify Android App
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Gotify on Klutch.sh gives you a powerful, self-hosted push notification system with real-time delivery. The combination of Gotify’s simplicity and Klutch.sh’s deployment ease means you can have instant notifications without relying on third-party services.

With support for multiple applications, priority levels, and easy integration via REST API, Gotify provides everything you need for server monitoring, home automation, or any scenario requiring push notifications. Whether you’re alerting on system events or integrating with your home assistant, Gotify on Klutch.sh delivers reliable, instant notifications you control.