285 lines
11 KiB
Markdown
285 lines
11 KiB
Markdown
# Building
|
|
|
|
!!! info
|
|
These instructions are pretty rough. My apologies for that. Please help improve them my letting me
|
|
know in a [GitHub issue](https://github.com/binwiederhier/ntfy/issues).
|
|
|
|
## ntfy server
|
|
The ntfy server source code is available [on GitHub](https://github.com/binwiederhier/ntfy). The codebase for the
|
|
server consists of three components:
|
|
|
|
* **The main server and API** is written in [Go](https://go.dev/) (so you'll need Go). Its main entrypoint is at
|
|
[main.go](https://github.com/binwiederhier/ntfy/blob/main/main.go), and the meat you're likely interested in is
|
|
in [server.go](https://github.com/binwiederhier/ntfy/blob/main/server/server.go). Notably, the server uses a
|
|
[SQLite](https://sqlite.org) library called [go-sqlite3](https://github.com/mattn/go-sqlite3), which requires
|
|
[Cgo](https://go.dev/blog/cgo) and `CGO_ENABLED=1` to be set. Otherwise things will not work (see below).
|
|
* **The documentation** is generated by [MkDocs](https://www.mkdocs.org/) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/),
|
|
which is written in [Python](https://www.python.org/). You'll need Python and MkDocs (via `pip`) only if you want to
|
|
build the docs.
|
|
* **The web app** is written in [React](https://reactjs.org/), using [MUI](https://mui.com/). It uses [Create React App](https://create-react-app.dev/)
|
|
to build the production build. If you want to modify the web app, you need [nodejs](https://nodejs.org/en/) (for `npm`)
|
|
to 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](https://github.com/binwiederhier/ntfy/blob/main/main.go) - Main entrypoint into the CLI, for both server and client
|
|
* [cmd/](https://github.com/binwiederhier/ntfy/tree/main/cmd) - CLI commands, such as `serve` or `publish`
|
|
* [server/](https://github.com/binwiederhier/ntfy/tree/main/server) - The meat of the server logic
|
|
* [docs/](https://github.com/binwiederhier/ntfy/tree/main/docs) - The [MkDocs](https://www.mkdocs.org/) documentation, also see `mkdocs.yml`
|
|
* [web/](https://github.com/binwiederhier/ntfy/tree/main/web) - The [React](https://reactjs.org/) application, also see `web/package.json`
|
|
|
|
Build related:
|
|
|
|
* [Makefile](https://github.com/binwiederhier/ntfy/blob/main/Makefile) - Main entrypoint for all things related to building
|
|
* [.goreleaser.yml](https://github.com/binwiederhier/ntfy/blob/main/.goreleaser.yml) - Describes all build outputs (for [GoReleaser](https://goreleaser.com/))
|
|
* [go.mod](https://github.com/binwiederhier/ntfy/blob/main/go.mod) - Go modules dependency file
|
|
* [mkdocs.yml](https://github.com/binwiederhier/ntfy/blob/main/mkdocs.yml) - Config file for the docs (for [MkDocs](https://www.mkdocs.org/))
|
|
* [web/package.json](https://github.com/binwiederhier/ntfy/blob/main/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](https://go.dev/) (required for main server)
|
|
* [gcc](https://gcc.gnu.org/) (required main server, for SQLite cgo-based bindings)
|
|
* [Make](https://www.gnu.org/software/make/) (required for convenience)
|
|
* [libsqlite3/libsqlite3-dev](https://www.sqlite.org/) (required for main server, for SQLite cgo-based bindings)
|
|
* [GoReleaser](https://goreleaser.com/) (required for a proper main server build)
|
|
* [Python](https://www.python.org/) (for `pip`, only to build the docs)
|
|
* [nodejs](https://nodejs.org/en/) (for `npm`, only to build the web app)
|
|
|
|
### Install dependencies
|
|
These steps assume Ubuntu. Steps may vary on different Linux distributions.
|
|
|
|
First, install [Go](https://go.dev/) (see [official instructions](https://go.dev/doc/install)):
|
|
``` shell
|
|
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](https://goreleaser.com/) (see [official instructions](https://goreleaser.com/install/)):
|
|
``` shell
|
|
go install github.com/goreleaser/goreleaser@latest
|
|
goreleaser -v # verifies that it worked
|
|
```
|
|
|
|
Install [nodejs](https://nodejs.org/en/) (see [official instructions](https://nodejs.org/en/download/package-manager/)):
|
|
``` shell
|
|
curl -fsSL https://deb.nodesource.com/setup_17.x | sudo -E bash -
|
|
sudo apt-get install -y nodejs
|
|
npm # verifies that it worked
|
|
```
|
|
|
|
Then install a few other things required:
|
|
``` shell
|
|
sudo apt install \
|
|
build-essential \
|
|
libsqlite3-dev \
|
|
gcc-arm-linux-gnueabi \
|
|
gcc-aarch64-linux-gnu \
|
|
python3-pip \
|
|
upx
|
|
```
|
|
|
|
### Check out code
|
|
Now check out via git from the [GitHub repository](https://github.com/binwiederhier/ntfy):
|
|
|
|
=== "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`:
|
|
|
|
``` shell
|
|
$ make
|
|
Typical commands (more see below):
|
|
make build - Build web app, documentation and server/client (sloowwww)
|
|
make server-amd64 - Build server/client binary (amd64, no web app or docs)
|
|
make install-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 amd64),
|
|
you can simply run `make build`:
|
|
|
|
``` shell
|
|
$ make build
|
|
...
|
|
# This builds web app, docs, and the ntfy binary (for amd64, armv7 and arm64).
|
|
# This will be SLOW (1+ minutes on my laptop). Maybe look at the other make targets?
|
|
```
|
|
|
|
You'll see all the outputs in the `dist/` folder afterwards:
|
|
|
|
``` bash
|
|
$ 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:
|
|
|
|
``` shell
|
|
$ 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.
|
|
|
|
### Building ntfy binary
|
|
To build only the `ntfy` binary **without the web app or documentation**, use the `make server-...` targets:
|
|
|
|
``` shell
|
|
Build server & client (not release version):
|
|
make server - Build server & client (all architectures)
|
|
make server-amd64 - Build server & client (amd64 only)
|
|
make server-armv7 - Build server & client (armv7 only)
|
|
make server-arm64 - Build server & client (arm64 only)
|
|
```
|
|
|
|
So if you're on an amd64/x86_64-based machine, you may just want to run `make server-amd64` during testing. On a modern
|
|
system, this shouldn't take longer than 5-10 seconds. I often combine it with `install-amd64` so I can run the binary
|
|
right away:
|
|
|
|
``` shell
|
|
$ make server-amd64 install-amd64
|
|
$ ntfy serve
|
|
```
|
|
|
|
During development of the main app, you can also just use `go run main.go` (as long as you run `make server-deps-static-sites`
|
|
at least once), otherwise you'll see this:
|
|
|
|
``` shell
|
|
# Error because docs/web folder is missing
|
|
$ go run main.go serve
|
|
server/server.go:85:13: pattern docs: no matching files found
|
|
|
|
# Works!
|
|
$ make server-deps-static-sites
|
|
$ go run main.go serve
|
|
2022/03/18 08:43:55 Listening on :2586[http]
|
|
|
|
```
|
|
|
|
### Building the web app
|
|
|
|
### Building the docs
|
|
|
|
```
|
|
pip3 install -r requirements.txt
|
|
mkdocs build
|
|
```
|
|
|
|
```
|
|
mkdocs serve
|
|
INFO - Building documentation...
|
|
INFO - Cleaning site directory
|
|
INFO - Documentation built in 5.53 seconds
|
|
INFO - [16:28:14] Serving on http://127.0.0.1:8000/
|
|
```
|
|
|
|
Then you can navigate to http://127.0.0.1:8000/ and whenever you change a markdown file in your text editor it'll automatically update.
|
|
|
|
|
|
###
|
|
|
|
XXXXXXXXXXXXXXXXXXXXx
|
|
|
|
|
|
### Quick & dirty (amd64 only)
|
|
To quickly build on amd64, you can use `make build-simple`:
|
|
|
|
```
|
|
make build-simple
|
|
```
|
|
|
|
That'll generate a statically linked binary in `dist/ntfy_linux_amd64/ntfy`. This binary will **not include the docs
|
|
or the web app**. To include that
|
|
|
|
For all other platforms (including Docker), and for production or other snapshot builds, you should use the amazingly
|
|
awesome [GoReleaser](https://goreleaser.com/) make targets:
|
|
|
|
```
|
|
Build:
|
|
make build - Build
|
|
make build-snapshot - Build snapshot
|
|
make build-simple - Build (using go build, without goreleaser)
|
|
make clean - Clean build folder
|
|
|
|
Releasing (requires goreleaser):
|
|
make release - Create a release
|
|
make release-snapshot - Create a test release
|
|
```
|
|
|
|
There are currently no platform-specific make targets, so they will build for all platforms (which may take a while).
|
|
|
|
## Android app
|
|
The ntfy Android app source code is available [on GitHub](https://github.com/binwiederhier/ntfy-android).
|
|
The Android app has two flavors:
|
|
|
|
* **Google Play:** The `play` flavor includes Firebase (FCM) and requires a Firebase account
|
|
* **F-Droid:** The `fdroid` flavor does not include Firebase or Google dependencies
|
|
|
|
First check out the repository:
|
|
|
|
```
|
|
git clone git@github.com:binwiederhier/ntfy-android.git # or: https://github.com/binwiederhier/ntfy-android.git
|
|
cd ntfy-android
|
|
```
|
|
|
|
Then either follow the steps for building with or without Firebase.
|
|
|
|
### Building without Firebase (F-Droid flavor)
|
|
Without Firebase, you may want to still change the default `app_base_url` in [strings.xml](https://github.com/binwiederhier/ntfy-android/blob/main/app/src/main/res/values/strings.xml)
|
|
if you're self-hosting the server. Then run:
|
|
```
|
|
# To build an unsigned .apk (app/build/outputs/apk/fdroid/*.apk)
|
|
./gradlew assembleFdroidRelease
|
|
|
|
# To build a bundle .aab (app/fdroid/release/*.aab)
|
|
./gradlew bundleFdroidRelease
|
|
```
|
|
|
|
### Building with Firebase (FCM, Google Play flavor)
|
|
To build your own version with Firebase, you must:
|
|
* Create a Firebase/FCM account
|
|
* Place your account file at `app/google-services.json`
|
|
* And change `app_base_url` in [strings.xml](https://github.com/binwiederhier/ntfy-android/blob/main/app/src/main/res/values/strings.xml)
|
|
* Then run:
|
|
```
|
|
# To build an unsigned .apk (app/build/outputs/apk/play/*.apk)
|
|
./gradlew assemblePlayRelease
|
|
|
|
# To build a bundle .aab (app/play/release/*.aab)
|
|
./gradlew bundlePlayRelease
|
|
```
|