develop.md

Development

Hurray 🥳 🎉, you are interested in writing code for ntfy! That's awesome. 😎

I tried my very best to write up detailed instructions, but if at any point in time you run into issues, don't hesitate to contact me on Discord or Matrix.

ntfy server

The ntfy server source code is available on GitHub. The codebase for the server consists of three components:

• The main server/client is written in Go (so you'll need Go). Its main entrypoint is at main.go, and the meat you're likely interested in is in server.go. Notably, the server uses a SQLite library called go-sqlite3, which requires Cgo and CGO_ENABLED=1 to be set. Otherwise things will not work (see below).
• The documentation is generated by MkDocs and Material for MkDocs, which is written in Python. You'll need Python and MkDocs (via pip) only if you want to build the docs.
• The web app is written in React, using MUI. It uses Create React App to build the production build. If you want to modify the web app, you need nodejs (for npm) and install all the 100,000 dependencies (sigh).

All of these components are built and then baked into one binary.

Navigating the code

Code:

• main.go - Main entrypoint into the CLI, for both server and client
• cmd/ - CLI commands, such as serve or publish
• server/ - The meat of the server logic
• docs/ - The MkDocs documentation, also see mkdocs.yml
• web/ - The React application, also see web/package.json

Build related:

• Makefile - Main entrypoint for all things related to building
• .goreleaser.yml - Describes all build outputs (for GoReleaser)
• go.mod - Go modules dependency file
• mkdocs.yml - Config file for the docs (for MkDocs)
• web/package.json - Build and dependency file for web app (for npm)

The web/ and docs/ folder are the sources for web app and documentation. During the build process, the generated output is copied to server/site (web app and landing page) and server/docs (documentation).

Build requirements

• Go (required for main server)
• gcc (required main server, for SQLite cgo-based bindings)
• Make (required for convenience)
• libsqlite3/libsqlite3-dev (required for main server, for SQLite cgo-based bindings)
• GoReleaser (required for a proper main server build)
• Python (for pip, only to build the docs)
• nodejs (for npm, only to build the web app)

Install dependencies

These steps assume Ubuntu. Steps may vary on different Linux distributions.

First, install Go (see official instructions):

wget https://go.dev/dl/go1.18.linux-amd64.tar.gz
rm -rf /usr/local/go && tar -C /usr/local -xzf go1.18.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin
go version   # verifies that it worked

Install GoReleaser (see official instructions):

go install github.com/goreleaser/goreleaser@latest
goreleaser -v   # verifies that it worked

Install nodejs (see official instructions):

curl -fsSL https://deb.nodesource.com/setup_17.x | sudo -E bash -
sudo apt-get install -y nodejs
npm -v   # verifies that it worked

Then install a few other things required:

sudo apt install \
    build-essential \
    libsqlite3-dev \
    gcc-arm-linux-gnueabi \
    gcc-aarch64-linux-gnu \
    python3-pip \
    upx \
    git

Check out code

Now check out via git from the GitHub repository:

=== "via HTTPS" shell git clone https://github.com/binwiederhier/ntfy.git cd ntfy

=== "via SSH" shell git clone git@github.com:binwiederhier/ntfy.git cd ntfy

Build all the things

Now you can finally build everything. There are tons of make targets, so maybe just review what's there first by typing make:

$ make 
Typical commands (more see below):
  make build                   - Build web app, documentation and server/client (sloowwww)
  make cli-linux-amd64         - Build server/client binary (amd64, no web app or docs)
  make install-linux-amd64     - Install ntfy binary to /usr/bin/ntfy (amd64)
  make web                     - Build the web app
  make docs                    - Build the documentation
  make check                   - Run all tests, vetting/formatting checks and linters
...

If you want to build the ntfy binary including web app and docs for all supported architectures (amd64, armv7, and arm64), you can simply run make build:

$ make build
...
# This builds web app, docs, and the ntfy binary (for amd64, armv7 and arm64). 
# This will be SLOW (5+ minutes on my laptop on the first run). Maybe look at the other make targets?

You'll see all the outputs in the dist/ folder afterwards:

$ find dist 
dist
dist/metadata.json
dist/ntfy_arm64_linux_arm64
dist/ntfy_arm64_linux_arm64/ntfy
dist/ntfy_armv7_linux_arm_7
dist/ntfy_armv7_linux_arm_7/ntfy
dist/ntfy_amd64_linux_amd64
dist/ntfy_amd64_linux_amd64/ntfy
dist/config.yaml
dist/artifacts.json

If you also want to build the Debian/RPM packages and the Docker images for all supported architectures, you can use the make release-snapshot target:

$ make release-snapshot
...
# This will be REALLY SLOW (sometimes 5+ minutes on my laptop)

During development, you may want to be more picky and build only certain things. Here are a few examples.

Build the ntfy binary