Getting started¶

This page takes you from the AWS Marketplace listing to a signed-in Gotify web UI and your first message. It takes about fifteen minutes.

You need: an AWS account with permission to subscribe to AWS Marketplace products and launch EC2 instances, and, on your workstation, the AWS CLI with the Session Manager plugin.

Open the Gotify Notification Server listing, choose View purchase options, review the terms and subscribe.

2. Launch the instance¶

Choose Launch your software and use these settings:

Instance type: t3.medium.
Storage: an encrypted gp3 root volume of at least 16 GiB.
IAM instance profile: a role with the AWS managed policy AmazonSSMManagedInstanceCore, so you can connect with Session Manager.
Security group: no inbound rules are needed. If you want SSH as well, allow port 22 only from your own administrative network.
Metadata: require IMDSv2.

3. Connect and check first boot¶

In the EC2 console, select the instance, choose Connect, then Session Manager. Switch to the ubuntu user and wait for first boot:

sudo -iu ubuntu
cloud-init status --wait
systemctl is-active sushi-gotify-firstboot.service gotify.service
curl --cacert /etc/gotify/tls/cert.pem https://127.0.0.1:8443/health

Both units should report active, and the health check answers.

4. Run the walkthrough¶

bash /opt/sushi/docs/demo.sh

It runs the image's self-test, checks the listeners and health, confirms that an invalid token is refused, sends a synthetic alert called pilot-disk-check, and checks that it survives a restart. It ends with SUSHI_CUSTOMER_DEMO_PASSED. It does not print the password or any token.

The walkthrough leaves an application called sushi-pilot, a client called sushi-pilot-stream and the test message in Gotify. Delete them in the web UI when you no longer need them.

5. Get the admin password¶

sudo cat /etc/gotify/admin.password

The user name is admin. Keep the password out of tickets, chat and screen recordings.

6. Open the web UI¶

On your workstation, start a port-forwarding session. Replace <instance-id> with your instance ID, and use the instance's region:

aws ssm start-session \
  --target <instance-id> \
  --document-name AWS-StartPortForwardingSession \
  --parameters '{"portNumber":["8443"],"localPortNumber":["8443"]}'

Leave it running and open https://127.0.0.1:8443/ in your browser. Sign in as admin. Then change the password in the web UI.

Certificate warning

The certificate is self-signed, created for this instance for localhost and 127.0.0.1, so your browser does not trust it by default. Check its fingerprint on the instance and compare it with the one your browser shows:

openssl x509 -in /etc/gotify/tls/cert.pem -noout -sha256 -fingerprint

To avoid the warning, copy the certificate (never key.pem) to your workstation and add it to your browser's trust store. A replacement instance has a new certificate.

7. Send your first message¶

In the web UI, create an application, for example my-script, and copy its token.

On the instance, save the token in a header file only you can read:

printf 'X-Gotify-Key: %s\n' '<app-token>' > ~/gotify-app.header
chmod 0600 ~/gotify-app.header

Send a message:

curl --cacert /etc/gotify/tls/cert.pem \
  -H @"$HOME/gotify-app.header" \
  -H 'Content-Type: application/json' \
  -d '{"title":"Hello","message":"First message from my instance","priority":5}' \
  https://127.0.0.1:8443/message

The message appears in the web UI straight away.

Next: Configuration.