## 1. Project Overview & Quickstart (gotify/dev-setup)

# dev-setup

Open-source repository gotify/dev-setup

### Repository Details
- **Repository:** [gotify/dev-setup](https://github.com/gotify/dev-setup)
- **Primary Language:** Code

*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*

## 2. Official Technical Reference & Guides (gotify/website)

## File: README.md

# gotify/website [](https://github.com/gotify/website/actions/workflows/main.yml)

-> https://gotify.net

## Run locally

```bash
$ yarn install
$ yarn dev
```

---

## File: docs/apache.md

# Apache reverse proxy

Here are configuration examples for setting up Apache as a reverse proxy for Gotify.

The following modules are required:

- mod_proxy
- mod_proxy_wstunnel
- mod_proxy_http

## Proxy requests

```apache
<VirtualHost *:80>
    ServerName domain.tld

    Keepalive On

    # The proxy must preserve the host because Gotify verifies the host with the origin
    # for WebSocket connections
    ProxyPreserveHost On

    # Proxy WebSocket requests to /stream
    ProxyPass "/stream" ws://127.0.0.1:GOTIFY_PORT/stream retry=0 timeout=60

    # Proxy all other requests to /
    ProxyPass "/" http://127.0.0.1:GOTIFY_PORT/ retry=0 timeout=5

    ProxyPassReverse / http://127.0.0.1:GOTIFY_PORT/
</VirtualHost>
```

## Proxy requests with sub path

```apache
<VirtualHost *:80>
    ServerName domain.tld
    Keepalive On

    Redirect 301 "/gotify" "/gotify/"

    # The proxy must preserve the host because Gotify verifies the host with the origin
    # for WebSocket connections
    ProxyPreserveHost On

    # Proxy WebSocket requests to /stream
    ProxyPass "/gotify/stream" ws://127.0.0.1:GOTIFY_PORT/stream retry=0 timeout=60

    # Proxy all other requests to /
    ProxyPass "/gotify/" http://127.0.0.1:GOTIFY_PORT/ retry=0 timeout=5
    #                 ^- !!trailing slash is required!!

    ProxyPassReverse /gotify/ http://127.0.0.1:GOTIFY_PORT/
</VirtualHost>
```

## Troubleshooting

With some additional Apache configuration, the `ProxyPass` for the `/stream` endpoint may not work correctly.
The request fails with `400 Bad Request` and Gotify logs the following error.

```
Error #01: websocket: the client is not using the websocket protocol: 'upgrade' token not found in 'Connection' header
```

To fix this issue, add the following rewrite rule to your virtual host config:

```
RewriteEngine  on
RewriteCond %{HTTP:Connection} upgrade [NC]
RewriteCond %{HTTP:Upgrade} websocket [NC]
RewriteRule /gotify/stream(.*) ws://127.0.0.1:GOTIFY_PORT/stream$1 [P,L]
```

---

## File: docs/build.md

# Build Gotify

1. [Setup development environment](dev-setup.md)

1. Build the UI

   ```bash
   $ (cd ui && yarn build)
   ```

1. Build the Go Binary

   It is recommended to build gotify/server via the [gotify/build docker images](https://github.com/gotify/build).
   This ensures that [plugins](plugin.md) will be compatible with the built binary because the same build environment is used.

   Set the LD_FLAGS with meta information like the version or the commit:

   ```bash
   $ export LD_FLAGS="-w -s -X main.Version=$(git describe --tags | cut -c 2-) -X main.BuildDate=$(date "+%F-%T") -X main.Commit=$(git rev-parse --verify HEAD) -X main.Mode=prod";
   ```

   Execute [gotify/server Makefile](https://github.com/gotify/server/blob/master/Makefile) tasks to build gotify/server.

   ```bash
   # builds all supported platforms
   $ make build
   # builds a specific platform
   $ make build-linux-amd64
   $ make build-linux-arm-7
   $ make build-linux-arm64
   $ make build-linux-386
   $ make build-linux-riscv64
   $ make build-windows-amd64
   $ make build-windows-386
   ```

   If you do not want to use the docker images you can build gotify/server like this:

   ```bash
   $ go build -ldflags="$LD_FLAGS" -o gotify-server
   ```

   _The project has a CGO reference (because of sqlite3), therefore a CGO cross compiler is needed when compiling for
   other platforms (the gotify/build docker images already contain the needed cross compilers)._

   ```bash
   $ CGO_ENABLED=1 CC=${CROSS_GCC} CXX=${CROSS_G++} GOOS=${TARGET_GOOS} GOARCH=${TARGET_GOARCH} \
       go build -ldflags="$LD_FLAGS" -o gotify-server
   ```

---

## File: docs/caddy.md

# Caddy 2 reverse proxy

Here are configuration examples for setting up [Caddy](https://caddyserver.com) as a reverse proxy for Gotify.

## As a standalone domain

Here is a sample config file if your Gotify instance runs on port 1245.

```
gotify.example.com {
  # Set the port to the one you are using in Gotify
  # WebSocket support, proxy headers, etc. are enabled by default
  reverse_proxy localhost:1245
}
```

Caddy automatically obtains TLS certificates from Let's Encrypt for your domain. If you want to explicitly disable TLS, prefix your server name with `http://`.

## At a subpath

Here is the equivalent of the sample config above but running at a subpath.

```
example.com {
  route /gotify/* {
    uri strip_prefix /gotify
    # Set the port to the one you are using in Gotify
    reverse_proxy localhost:1245
  }
  redir /gotify /gotify/
}
```

---

## File: docs/dev-server-and-tests.md

# Servers and Tests

## Start development servers

### Backend

The backend embeds the built UI, so build it first.

```bash
$ (cd ui && yarn build)
```

Start the server in development mode.

```bash
$ go run .
```

### UI

Start the UI development server.

_Commands must be executed inside the ui directory._

```bash
$ yarn start
```

Open `http://localhost:5173` inside your favorite browser.

The UI development server proxies API requests to a Gotify server running on
`localhost:80`. Create a `gotify-server.env` in the gotify/server repository
containing `GOTIFY_SERVER_PORT=8080` to change the port.

## Update Swagger spec

The [gotify/server REST-API](/api-docs) is documented via Swagger. The Swagger definition is generated from source code comments
([example comment](https://github.com/gotify/server/blob/09c1516a170dfb47d29644db622655b540b94922/api/application.go#L33)).

After changing such a comment, run the following command to update the Swagger definition.

```bash
$ make update-swagger
```

## Tests

### Execute Backend Tests

#### Run tests

```bash
$ go test ./...
```

#### Run Tests with Coverage

```bash
$ make test-coverage
$ go tool cover -html=coverage.txt # get a HTML coverage report
```

### Execute UI (end2end) Tests

Build the UI because the end2end tests run against the production build.
(This needs to be done after every change in the UI)

```bash
$ (cd ui && yarn build)
```

Now execute the tests with yarn.

```bash
$ (cd ui && yarn test)
```

### Execute Static Checks

The following command checks the formatting, runs linters like golangci-lint and eslint, and verifies that the Swagger spec is up to date.

```bash
$ make check
```

---

## File: docs/dev-setup.md

# Setup Environment

Gotify requires:

- Go 1.25 or newer
- Node 24 or newer
- Yarn 1.9 or newer

## Clone sources

Clone the gotify/server source from git:

```bash
$ git clone https://github.com/gotify/server.git && cd server
```

## Setup Backend

Install the development tools (needed for generating the Swagger spec):

```bash
$ make download-tools
```

## Setup UI

_Commands must be executed inside the ui directory._

Download dependencies with [yarn](https://github.com/yarnpkg/yarn).

```bash
$ yarn
```

---

## File: docs/first-login.md

# First Login

After setting up gotify/server you can log in to the WebUI. On first launch an initial admin account is created. If you have not overridden the defaults in the configuration, use username `admin` and password `admin`.

Once logged in you can create your own user(s) and, if desired, delete the default account (after creating another administrator account). You can also remove any username/password overrides from your configuration, they are only used to create this initial account.

If you keep the default account, be sure to change its password so it is not `admin`!

---

## File: docs/haproxy.md

# HAProxy reverse proxy

Here are configuration examples for setting up HAProxy as a reverse proxy for Gotify.

## Proxy requests

```txt
frontend www
    bind 0.0.0.0:80
    default_backend backend_gotify
    timeout client 60s
    timeout client-fin 30s

backend backend_gotify
    server  backend01       127.0.0.1:GOTIFY_PORT  check
    timeout connect 10s
    timeout server 60s
```

---

## File: docs/index.md

# Intro

This is the documentation of gotify/server. Let's start with some definitions:

A client is a device or program that receives messages and can manage clients, applications and messages. A client cannot send messages.

An application is a device or program that can only send messages.

Users can only manage (view/edit/delete) the clients and applications they created, including messages sent by those applications.

A message has the following attributes: content, title, creation date, application id and priority.