Gotify on AWS User Guide

Overview

This image runs Gotify, the open source, self-hosted push notification server - send messages from any script, server or application over a simple REST API and receive them in real time in the web app, the official Android client, or any websocket consumer. A privacy-respecting alternative to hosted push services, deployable in your own VPC.

The Gotify server is a single Go binary that serves both the REST API and the bundled web app. It runs behind nginx as a reverse proxy. PostgreSQL is the datastore; the server listens on 127.0.0.1:8080 and is reached through nginx on port 80 (and 443 once you add TLS). The server and the database bind to the loopback interface only.

On the first boot of every deployed instance, a one-shot service recreates an empty database (which also yields a fresh per-instance session signing key), rotates the PostgreSQL password, and seeds a single administrator account with a per-instance password. Open registration is disabled. The login is written to /root/gotify-credentials.txt with mode 0600.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users and senders will reach Gotify on
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Gotify. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.small or larger - Gotify is lightweight. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users use. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes under a minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Gotify Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.small \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=gotify-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve the Administrator Login

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

The first boot service runs before the SSH daemon becomes ready, so the credentials file is always in place when you log in for the first time.

ssh <login-user>@<public-ip>
sudo cat /root/gotify-credentials.txt

You will see a plain text file containing the Gotify URL, the administrator username (admin) and the password. From the same SSH session you can confirm the deployment is healthy - the version endpoint is open:

curl -fsS http://127.0.0.1/version

{"version":"2.9.1","commit":"...","buildDate":"..."}

A JSON response with a version confirms the full stack - nginx, the Gotify server and PostgreSQL - is serving.

Step 4: First Sign-in

Open a web browser and navigate to http://<public-ip>/. Gotify presents its sign-in page. Enter the username admin and the password from /root/gotify-credentials.txt, then select Login.

The Gotify sign-in, served on first boot with a per-instance administrator login.

Step 5: Create an Application and Push a Message

In Gotify, every sender is an application with its own token. Open APPS, select Create Application, give it a name, and copy its token. Then push a message with a single HTTP call - from a script, a cron job, a monitoring tool, anything:

curl -X POST "http://<public-ip>/message?token=<app-token>" \
  -F "title=Backup complete" \
  -F "message=Database dump 4.2 GB written to S3" \
  -F "priority=5"

The message appears instantly in the web app and in any connected client.

Gotify applications - each with its own token for pushing messages over the REST API.

Step 6: Read Messages in Real Time

The Messages view streams notifications as they arrive, grouped by application, with priority indicators so the important alerts stand out. Higher priority messages are highlighted; you can delete individual messages or clear them all.

The Gotify message stream - notifications grouped by application with priority indicators.

Install the official Gotify Android client, point it at http://<public-ip>/ (or your HTTPS domain) and sign in with a client token from CLIENTS to receive push notifications on your phone. Any websocket consumer can subscribe to /stream for real-time delivery.

Step 7: Manage Users and Clients

Open USERS (as the administrator) to add users - open registration is disabled by default, so accounts are created here. Open CLIENTS to create client tokens for the mobile and desktop apps. Open PLUGINS to extend Gotify with compiled plugins.

Step 8: Enable HTTPS with Let's Encrypt

For any production deployment serve Gotify over HTTPS so logins and tokens cannot be intercepted. The image ships with nginx, which certbot can configure automatically.

The following assumes you have a DNS record pointing your fully qualified domain name at the instance's public IP address.

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d push.your-domain.example \
  --non-interactive --agree-tos -m you@your-domain.example \
  --redirect

certbot also configures the websocket upgrade headers needed for the real-time stream.

Step 9: Backups and Maintenance

Gotify keeps all of its state - users, applications, clients and messages - in PostgreSQL, and uploaded application images under /var/lib/gotify. Back both up regularly:

sudo -u postgres pg_dump gotify > <backup-dir>/gotify-db-$(date +%F).sql
sudo tar czf <backup-dir>/gotify-data-$(date +%F).tgz -C /var/lib/gotify images plugins

Ship the archives to an Amazon S3 bucket or another object store. Because the database and the data directory are each on their own EBS volume, you can also take coordinated EBS snapshots. To upgrade Gotify, replace /opt/gotify/gotify with a newer release and restart - database migrations run automatically on start. See https://gotify.net/docs/.

Step 10: Scaling and Operations

• Move PostgreSQL to Amazon RDS for PostgreSQL and update the database section of /etc/gotify/config.yml
• Put the web tier behind an Application Load Balancer (with websocket support) if you need high availability
• Integrate Gotify with monitoring (Grafana, Prometheus Alertmanager), CI/CD and backup jobs by pushing to application tokens

Each of these is documented in the official Gotify documentation at https://gotify.net/docs/.

Support

cloudimg provides 24/7/365 expert technical support for this image. Guaranteed response within 24 hours, one hour average for critical issues. Contact support@cloudimg.co.uk.

For general Gotify questions consult the documentation at https://gotify.net/docs/. Gotify is a trademark of its respective owner; use here is nominative and does not imply affiliation or endorsement.