astra
/
ntfy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

More docs

pull/178/head
Philipp Heckel 2022-03-18 17:00:08 -04:00
parent 15265d9ef3
commit 1f75498dca
1 changed files with 78 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
docs/develop.md
View File

@ -1,14 +1,14 @@
# Building # Development
Hurray 🥳 🎉, you are interested in writing code for ntfy! **That's awesome.** 😎
!!! info I tried my very best to write up detailed instructions, but if at any point in time you run into issues, don't
These instructions are pretty rough. My apologies for that. Please help improve them my letting me hesitate to **contact me on [Discord](https://discord.gg/cT7ECsZj9w) or [Matrix](https://matrix.to/#/#ntfy:matrix.org)**.
know in a [GitHub issue](https://github.com/binwiederhier/ntfy/issues).
## ntfy server ## ntfy server
The ntfy server source code is available [on GitHub](https://github.com/binwiederhier/ntfy). The codebase for the The ntfy server source code is available [on GitHub](https://github.com/binwiederhier/ntfy). The codebase for the
server consists of three components: 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 * **The main server/client** 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 [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 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 [SQLite](https://sqlite.org) library called [go-sqlite3](https://github.com/mattn/go-sqlite3), which requires
@ -18,7 +18,7 @@ server consists of three components:
build the docs. 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/) * **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 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*). and install all the 100,000 dependencies (*sigh*).
All of these components are built and then **baked into one binary**. All of these components are built and then **baked into one binary**.
@ -54,10 +54,11 @@ the generated output is copied to `server/site` (web app and landing page) and `
* [nodejs](https://nodejs.org/en/) (for `npm`, only to build the web app) * [nodejs](https://nodejs.org/en/) (for `npm`, only to build the web app)
### Install dependencies ### Install dependencies
These steps assume Ubuntu. Steps may vary on different Linux distributions. 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)): First, install [Go](https://go.dev/) (see [official instructions](https://go.dev/doc/install)):
``` shell ``` shell
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 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 export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin
go version # verifies that it worked go version # verifies that it worked
@ -73,7 +74,7 @@ Install [nodejs](https://nodejs.org/en/) (see [official instructions](https://no
``` shell ``` shell
curl -fsSL https://deb.nodesource.com/setup_17.x | sudo -E bash - curl -fsSL https://deb.nodesource.com/setup_17.x | sudo -E bash -
sudo apt-get install -y nodejs sudo apt-get install -y nodejs
npm # verifies that it worked npm -v # verifies that it worked
``` ```
Then install a few other things required: Then install a few other things required:
@ -84,7 +85,8 @@ sudo apt install \
gcc-arm-linux-gnueabi \ gcc-arm-linux-gnueabi \
gcc-aarch64-linux-gnu \ gcc-aarch64-linux-gnu \
python3-pip \ python3-pip \
upx upx \
git
``` ```
### Check out code ### Check out code
@ -155,10 +157,11 @@ $ make release-snapshot
During development, you may want to be more picky and build only certain things. Here are a few examples. During development, you may want to be more picky and build only certain things. Here are a few examples.
### Building ntfy binary ### Build the ntfy binary
To build only the `ntfy` binary **without the web app or documentation**, use the `make server-...` targets: To build only the `ntfy` binary **without the web app or documentation**, use the `make server-...` targets:
``` shell ``` shell
$ make
Build server & client (not release version): Build server & client (not release version):
make server - Build server & client (all architectures) make server - Build server & client (all architectures)
make server-amd64 - Build server & client (amd64 only) make server-amd64 - Build server & client (amd64 only)
@ -190,17 +193,41 @@ $ go run main.go serve
``` ```
### Building the web app ### Build the web app
The sources for the web app live in `web/`. As long as you have `npm` installed (see above), building the web app
is really simple. Just type `make web` and you're in business:
### Building the docs ``` shell
$ make web
``` ...
pip3 install -r requirements.txt
mkdocs build
``` ```
This will build the web app using Create React App and then **copy the production build to the `server/site` folder**, so
that when you `make server` (or `make server-amd64`, ...), you will have the web app included in the `ntfy` binary.
If you're developing on the web app, it's best to just `cd web` and run `npm start` manually. This will open your browser
at `http://127.0.0.1:3000` with the web app, and as you edit the source files, they will be recompiled and the browser
will automatically refresh:
``` shell
$ cd web
$ npm start
``` ```
mkdocs serve
### Build the docs
The sources for the docs live in `docs/`. Similarly to the web app, you can simply run `make docs` to build the
documentation. As long as you have `mkdocs` installed (see above), this should work fine:
``` shell
$ make docs
...
```
If you are changing the documentation, you should be running `mkdocs serve` directly. This will build the documentation,
serve the files at `http://127.0.0.1:8000/`, and rebuild every time you save the source files:
```
$ mkdocs serve
INFO - Building documentation... INFO - Building documentation...
INFO - Cleaning site directory INFO - Cleaning site directory
INFO - Documentation built in 5.53 seconds INFO - Documentation built in 5.53 seconds
@ -209,56 +236,45 @@ 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. 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 ## Android app
The ntfy Android app source code is available [on GitHub](https://github.com/binwiederhier/ntfy-android). The ntfy Android app source code is available [on GitHub](https://github.com/binwiederhier/ntfy-android).
The Android app has two flavors: The Android app has two flavors:
* **Google Play:** The `play` flavor includes Firebase (FCM) and requires a Firebase account * **Google Play:** The `play` flavor includes [Firebase (FCM)](https://firebase.google.com/) and requires a Firebase account
* **F-Droid:** The `fdroid` flavor does not include Firebase or Google dependencies * **F-Droid:** The `fdroid` flavor does not include Firebase or Google dependencies
### Navigating the code
* [main/](https://github.com/binwiederhier/ntfy-android/tree/main/app/src/main) - Main Android app source code
* [play/](https://github.com/binwiederhier/ntfy-android/tree/main/app/src/play) - Google Play / Firebase specific code
* [fdroid/](https://github.com/binwiederhier/ntfy-android/tree/main/app/src/fdroid) - F-Droid Firebase stubs
* [build.gradle](https://github.com/binwiederhier/ntfy-android/blob/main/app/build.gradle) - Main build file
### IDE/Environment
You should download [Android Studio](https://developer.android.com/studio) (or [IntelliJ IDEA](https://www.jetbrains.com/idea/)
with the relevant Android plugins). Everything else will just be a pain for you. Do yourself a favor. 😀
### Check out the code
First check out the repository: First check out the repository:
=== "via HTTPS"
``` shell
git clone https://github.com/binwiederhier/ntfy-android.git
cd ntfy-android
``` ```
git clone git@github.com:binwiederhier/ntfy-android.git # or: https://github.com/binwiederhier/ntfy-android.git
=== "via SSH"
``` shell
git clone git@github.com:binwiederhier/ntfy-android.git
cd ntfy-android cd ntfy-android
``` ```
Then either follow the steps for building with or without Firebase. Then either follow the steps for building with or without Firebase.
### Building without Firebase (F-Droid flavor) ### Build F-Droid flavor (no FCM)
!!! info
I do build the ntfy Android app using IntelliJ IDEA (Android Studio), so I don't know if these Gradle commands will
work without issues. Please give me feedback if it does/doesn't work for you.
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) 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: if you're self-hosting the server. Then run:
``` ```
@ -269,8 +285,13 @@ if you're self-hosting the server. Then run:
./gradlew bundleFdroidRelease ./gradlew bundleFdroidRelease
``` ```
### Building with Firebase (FCM, Google Play flavor) ### Build Play flavor (FCM)
!!! info
I do build the ntfy Android app using IntelliJ IDEA (Android Studio), so I don't know if these Gradle commands will
work without issues. Please give me feedback if it does/doesn't work for you.
To build your own version with Firebase, you must: To build your own version with Firebase, you must:
* Create a Firebase/FCM account * Create a Firebase/FCM account
* Place your account file at `app/google-services.json` * 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) * And change `app_base_url` in [strings.xml](https://github.com/binwiederhier/ntfy-android/blob/main/app/src/main/res/values/strings.xml)