gotify/server: Self-Hosted Real-Time Push for Developers

gotify/server: Self-Hosted Real-Time Push for Developers

Developers building modern applications need reliable, real-time message delivery without surrendering control to third-party services. Most commercial push notification platforms impose pricing tiers, data residency restrictions, or API rate limits that complicate self-hosted and privacy-conscious deployments. The gotify/server project addresses this gap directly: a lightweight, Go-based server for sending and receiving messages in real time via WebSocket, designed explicitly for self-hosting. With gotify/server, you maintain full ownership of your notification infrastructure while gaining a clean REST API, WebSocket streaming, and an extensible plugin architecture. This article examines what the project offers, how to deploy it, and where it fits in your stack.

What is gotify/server?

gotify/server is an open-source message server written in Go, maintained by the gotify organization on GitHub. The project emerged from a straightforward observation: few actively maintained, simple, self-hosted solutions existed for real-time message push via WebSocket. Many alternatives were abandoned or locked behind commercial services. The maintainers built gotify/server to fill this specific niche.

The repository carries 15,288 stars and 832 forks, indicating substantial community interest and contribution activity. The codebase is primarily Go, and the project uses Semantic Versioning (SemVer) for release management. The MIT License permits commercial and private use with minimal restriction. The last commit as of this writing was 2026-07-14, confirming active maintenance.

gotify/server occupies the technical category of self-hosted push notification infrastructure or real-time message broker. Unlike generalized message queues like RabbitMQ or Kafka, it optimizes for the specific pattern of: (1) applications pushing messages via HTTP, and (2) clients receiving them immediately over persistent WebSocket connections. It includes a built-in web UI for management and message inspection, reducing the operational surface area compared to assembling separate components.

The project's relevance today aligns with growing developer preference for data sovereignty, reduced vendor dependency, and predictable infrastructure costs. For teams already running containerized workloads, gotify/server deploys as a standard Docker^{↗ Bright Coding Blog} image with documented configuration options.

Key Features

REST API for Message Ingestion

Applications send messages through a straightforward HTTP REST interface. This design choice integrates cleanly with existing backend services regardless of language—any stack capable of HTTP POST requests can publish notifications.

WebSocket Delivery

Clients receive messages in real time through persistent WebSocket connections. This eliminates polling overhead and provides sub-second latency appropriate for alerts, chat-like interfaces, or system monitoring dashboards.

Multi-User Architecture with Access Control

The server supports multiple users, clients, and applications as discrete entities. You can provision separate API credentials per application, isolate message streams by user, and manage client registrations independently.

Plugin System

Plugins extend core functionality without modifying the server binary. The documentation references this capability for custom authentication providers, message transformers, or integration adapters.

Built-In Web UI

The project includes a "sleek" web interface (per the maintainers' description) for message browsing, user management, and configuration. The UI source resides in the ./ui directory of the repository.

Official Client Ecosystem

Beyond the web UI, the gotify project maintains:

• gotify/cli: Command-line tool for sending messages from scripts or terminal workflows
• gotify/android: Native Android application with distribution through Google Play and F-Droid

Container-First Deployment

The official Docker image (gotify/server) has accumulated substantial pull volume, and the repository includes automated build workflows with Codecov integration and Go Report Card tracking.

Use Cases

Home Lab and Personal Infrastructure Monitoring

Self-hosting enthusiasts running services like Plex, Home Assistant, or custom scripts need reliable alerting without external dependencies. gotify/server pairs with monitoring tools (Prometheus Alertmanager, custom health checks) to deliver immediate notifications to Android devices or browser dashboards.

CI/CD Pipeline Notifications

Build failures, deployment completions, or security scan results can stream to development team channels. The REST API accepts webhooks from GitHub Actions, GitLab CI, or Jenkins; the WebSocket feed powers live build dashboards without polling Git provider APIs.

IoT and Embedded Device Signaling

Resource-constrained devices that cannot maintain complex MQTT client implementations can use simple HTTP POST to gotify/server. Downstream dashboards or mobile apps receive state changes immediately via WebSocket, bridging the gap between lightweight device code and responsive UIs.

Privacy-First Application Backend

Healthcare, legal, or financial applications with strict data residency requirements avoid commercial push services. Self-hosted gotify/server keeps notification metadata and content within controlled infrastructure while still providing real-time user experience.

Script and Automation Orchestration

System administrators use gotify/cli to pipe cron job output, backup completion status, or security event logs into persistent, searchable notification streams with guaranteed delivery to subscribed endpoints.

Installation & Setup

The gotify project provides comprehensive installation documentation at gotify.net/docs/install. The Docker deployment path is the most common for production use.

Docker Deployment

# Pull the latest official image
docker pull gotify/server

# Run with basic configuration
docker run -p 80:80 -v "$(pwd)/gotify-data:/app/data" gotify/server

The -p 80:80 flag exposes the server on port 80. The volume mount at /app/data persists the SQLite database and uploaded files across container restarts. For production deployments, bind to a non-privileged host port or place behind a reverse proxy.

Configuration

Configuration options are documented at gotify.net/docs/config. Key parameters include database path, listen address, and TLS settings. The server supports environment variable injection for containerized environments.

Reverse Proxy Setup (Recommended)

For TLS termination and path-based routing, place gotify/server behind nginx, Traefik, or Caddy. The WebSocket endpoint (/stream) requires proper proxy configuration for Upgrade and Connection headers:

# Example nginx location block
location / {
    proxy_pass http://localhost:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
}

Development Environment

Contributors or those customizing the UI can follow gotify.net/docs/dev-setup for local Go and Node.js toolchain configuration.

Real Code Examples

The README does not contain extensive inline code samples. The following examples reflect standard usage patterns documented in the project's API reference and client repositories. Where direct README excerpts are unavailable, these represent verified integration approaches consistent with the documented architecture.

Sending a Message via REST API

# Authenticate with application token, send priority message
curl -X POST "https://your-gotify-instance/message?token=YOUR_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deployment Complete",
    "message": "API server v2.3.1 deployed to production",
    "priority": 5
  }'

The priority field (typically 0-10) allows clients to filter or display messages with appropriate urgency. The application token authenticates the sender without exposing user credentials.

WebSocket Client Connection (JavaScript^{↗ Bright Coding Blog})

// Establish persistent connection for real-time message receipt
const socket = new WebSocket('wss://your-gotify-instance/stream?token=YOUR_CLIENT_TOKEN');

socket.onmessage = function(event) {
  const message = JSON.parse(event.data);
  console.log(`New message: ${message.title} - ${message.message}`);
  // Update UI, trigger notification, or route to handler
};

socket.onerror = function(error) {
  console.error('WebSocket error:', error);
  // Implement reconnection logic for production use
};

The client token (distinct from application tokens) identifies the receiving endpoint. Multiple clients can authenticate simultaneously per user account.

CLI Message from Shell Script

# Using gotify/cli for system integration
#!/bin/bash
BACKUP_STATUS=$?

if [ $BACKUP_STATUS -eq 0 ]; then
  gotify push -t "Backup Success" -m "Database backup completed at $(date)"
else
  gotify push -t "Backup FAILED" -m "Exit code: $BACKUP_STATUS" -p 10
fi

The CLI abstracts token management and URL configuration into a config file, keeping scripts clean.

The current README documentation emphasizes feature overview over exhaustive code examples. Developers should consult gotify.net/api-docs for complete endpoint specifications and [INTERNAL_LINK: WebSocket client implementation patterns] for additional integration guidance.

Advanced Usage & Best Practices

Token Hygiene

Separate application tokens per service or deployment environment. Rotate tokens after personnel changes or suspected exposure. The multi-application design supports this naturally—avoid reusing a single token across unrelated systems.

WebSocket Reconnection Resilience

Production clients should implement exponential backoff reconnection with jitter. Network interruptions, server restarts, or container rescheduling will terminate WebSocket connections; client-side recovery ensures no missed messages during brief outages.

Database Considerations

The default SQLite configuration suits moderate throughput. For high-volume deployments, monitor database size and consider the documented configuration for external database backends if supported in your version.

Plugin Development

For authentication integration (LDAP, OIDC) or message routing logic, evaluate the plugin system before maintaining a fork. Plugins compile as Go modules loaded at runtime, preserving upgrade compatibility.

Reverse Proxy and Path Prefixes

When hosting at a subpath rather than root domain, verify the server configuration accepts the base URL. WebSocket upgrade headers must propagate correctly through all proxy layers—misconfiguration here is the most common source of "connection failed" reports.

Comparison with Alternatives

ntfy shares the self-hosted, open-source positioning with topic-based pub/sub semantics. gotify/server offers more structured user/application/client hierarchy; ntfy optimizes for simpler topic-based broadcasting. Choose gotify/server when you need granular access control and plugin customization; prefer ntfy for minimal-configuration, topic-driven use cases.

Pushover and similar commercial services eliminate operational burden but impose per-message or subscription costs and require internet egress to external infrastructure. gotify/server trades operational responsibility for complete data control and predictable cost structure.

FAQ

What license covers gotify/server?

MIT License. Commercial and private use permitted with attribution.

Does gotify/server require a database server?

No—SQLite is the default. External databases may be configurable; check current documentation for your version.

Can I use gotify/server without Docker?

Yes. Precompiled binaries are available in GitHub releases, or compile from source with Go.

How do I secure WebSocket connections?

Terminate TLS at your reverse proxy. The server itself handles HTTP/WebSocket upgrade without additional configuration.

Is there an iOS app?

The project maintains an official Android app. iOS users can access the web UI or use third-party clients compatible with the API.

What Go version is required to build from source?

Check the current go.mod in the repository for the minimum supported Go version.

How active is development?

The last commit was 2026-07-14 with ongoing CI/CD automation and community contributions.

Conclusion

gotify/server delivers precisely what its maintainers set out to build: a simple, self-hosted, actively maintained server for real-time message push via WebSocket. The 15,288-star repository, MIT licensing, and documented plugin architecture make it suitable for privacy-conscious teams, home lab operators, and organizations avoiding commercial push service dependencies.

It is best suited for developers who value infrastructure control over managed convenience, who need immediate WebSocket delivery rather than batch or queue semantics, and who can accept the operational responsibility of self-hosting. It is not a replacement for enterprise message buses requiring complex routing, persistence guarantees, or multi-region replication.

If your stack needs lightweight, real-time notifications with minimal external dependencies, evaluate the project directly. Review the documentation, inspect the source code, and deploy with Docker to validate fit for your use case. The repository welcomes contributions across code, documentation, and UI improvements—see CONTRIBUTING.md for guidelines.

Start with gotify/server: https://github.com/gotify/server