server

README

Gotify Server

• Motivation
• Features
• Installation
• Configuration
• Push Message Examples
• Setup Dev Environment
• Building
• Tests
• Versioning
• License

Motivation

We wanted a simple server for sending and receiving messages (in real time per web socket). For this, not many open source projects existed and most of the existing ones were abandoned. Also, a requirement was that it can be self-hosted. We know there are many free and commercial push services out there.

Features

• send messages via REST-API
• receive messages via web socket
• manage users, clients and applications
• API Docs (also available at /docs)
• Web-UI -> ./ui
• CLI for sending messages -> gotify/cli
• Android-App -> gotify/android

Google Play and the Google Play logo are trademarks of Google LLC.

Installation

Docker

The docker image is available on docker hub at gotify/server.

$ docker run -p 80:80 -v /etc/gotify/data:/app/data gotify/server

Also there is a specific docker image for arm-7 processors (raspberry pi), named gotify/server-arm7.

$ docker run -p 80:80 -v /etc/gotify/data:/app/data gotify/server-arm7

/app/data contains the database file (if sqlite is used), images for applications and cert-files (if lets encrypt is enabled).

Binary

Visit the releases page and download the zip for your OS.

Configuration

File

When strings contain reserved characters then they need to be escaped. List of reserved characters and how to escape them.

server:
  port: 80 # the port for the http server
  ssl:
    enabled: false # if https should be enabled
    redirecttohttps: true # redirect to https if site is accessed by http
    port: 443 # the https port
    certfile: # the cert file (leave empty when using letsencrypt)
    certkey: # the cert key (leave empty when using letsencrypt)
    letsencrypt:
      enabled: false # if the certificate should be requested from letsencrypt
      accepttos: false # if you accept the tos from letsencrypt
      cache: data/certs # the directory of the cache from letsencrypt
      hosts: # the hosts for which letsencrypt should request certificates
      - mydomain.tld
      - myotherdomain.tld
  responseheaders: # response headers are added to every response (default: none)
    Access-Control-Allow-Origin: "*"
    Access-Control-Allow-Methods: "GET,POST"
  stream:
    allowedorigins: # allowed origins for websocket connections (same origin is always allowed)
      - ".+.example.com"
      - "otherdomain.com"
database: # for database see (configure database section)
  dialect: sqlite3
  connection: data/gotify.db
defaultuser: # on database creation, gotify creates an admin user
  name: admin # the username of the default user
  pass: admin # the password of the default user
passstrength: 10 # the bcrypt password strength (higher = better but also slower)
uploadedimagesdir: data/images # the directory for storing uploaded images

Environment

Escaped characters in list or map environment settings (GOTIFY_SERVER_RESPONSEHEADERS and GOTIFY_SERVER_SSL_LETSENCRYPT_HOSTS) need to be escaped as well. List of reserved characters and how to escape them.

GOTIFY_SERVER_PORT=80
GOTIFY_SERVER_SSL_ENABLED=false
GOTIFY_SERVER_SSL_REDIRECTTOHTTPS=true
GOTIFY_SERVER_SSL_PORT=443
GOTIFY_SERVER_SSL_CERTFILE=
GOTIFY_SERVER_SSL_CERTKEY=
GOTIFY_SERVER_SSL_LETSENCRYPT_ENABLED=false
GOTIFY_SERVER_SSL_LETSENCRYPT_ACCEPTTOS=false
GOTIFY_SERVER_SSL_LETSENCRYPT_CACHE=certs
# lists are a little weird but do-able (:
GOTIFY_SERVER_SSL_LETSENCRYPT_HOSTS=- mydomain.tld\n- myotherdomain.tld
GOTIFY_SERVER_RESPONSEHEADERS="Access-Control-Allow-Origin: \"*\"\nAccess-Control-Allow-Methods: \"GET,POST\""
GOTIFY_SERVER_STREAM_ALLOWEDORIGINS="- \".+.example.com\"\n- \"otherdomain.com\""
GOTIFY_DATABASE_DIALECT=sqlite3
GOTIFY_DATABASE_CONNECTION=gotify.db
GOTIFY_DEFAULTUSER_NAME=admin
GOTIFY_DEFAULTUSER_PASS=admin
GOTIFY_PASSSTRENGTH=10
GOTIFY_UPLOADEDIMAGESDIR=images

Database

Dialect	Connection
sqlite3	path/to/database.db
mysql	gotify:secret@/gotifydb?charset=utf8&parseTime=True&loc=Local
postgres	host=localhost port=3306 user=gotify dbname=gotify password=secret

When using postgres without SSL then sslmode=disable must be added to the connection string. See #90.

Push Message Examples

You can simply use curl, HTTPie or any other http-client to push messages.

An application-token can be obtained from the apps tab inside the UI or using the REST-API (/application).

$ curl -X POST "https://push.example.de/message?token=<apptoken>" -F "title=my title" -F "message=my message"
$ http -f POST "https://push.example.de/message?token=<apptoken>" title="my title" message="my message"

More examples can be found here

Also you can use gotify/cli to push messages. The CLI stores url and token in a config file.

$ gotify push -t "my title" -p 10 "my message"
$ echo my message | gotify push

Setup Dev Environment

Setup Server

Download go dependencies with golang/dep.

$ dep ensure

Run golang server.

$ go run app.go

Setup UI

Commands must be executed inside the ui directory.

Download dependencies with npm.

$ npm install

Star the UI development server.

$ npm start

Open http://localhost:3000 inside your favorite browser.

The UI requires a Gotify server running on localhost:80 this can be adjusted inside the ui/src/index.tsx.

Building

Build Server

$ go build app.go

Build UI

$ npm run build

Cross-Platform

The project has a CGO reference (because of sqlite3), therefore a GCO cross compiler is needed for compiling for other platforms. See .travis.yml on how we do that.

Tests

The tests can be executed with:

$ make test
# or
$ go test ./...

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License - see the LICENSE file for details