Lots of development instructions, Makefile things

.goreleaser.yml

@@ -4,7 +4,7 @@ before:
     - go mod tidy
 builds:
   -
-    id: ntfy
+    id: ntfy_amd64
     binary: ntfy
     env:
       - CGO_ENABLED=1 # required for go-sqlite3

Makefile

@@ -3,9 +3,33 @@ VERSION := $(shell git describe --tag)
 .PHONY:
 
 help:
-	@echo "Typical commands:"
+	@echo "Typical commands (more see below):"
+	@echo "  make build                   - Build web app, documentation and server/client (sloowwww)"
+	@echo "  make server-amd64            - Build server/client binary (amd64, no web app or docs)"
+	@echo "  make install-amd64           - Install ntfy binary to /usr/bin/ntfy (amd64)"
+	@echo "  make web                     - Build the web app"
+	@echo "  make docs                    - Build the documentation"
 	@echo "  make check                   - Run all tests, vetting/formatting checks and linters"
-	@echo "  make build-snapshot install  - Build latest and install to local system"
+	@echo
+	@echo "Build everything:"
+	@echo "  make build                   - Build web app, documentation and server/client"
+	@echo "  make clean                   - Clean build/dist folders"
+	@echo
+	@echo "Build server & client (not release version):"
+	@echo "  make server                  - Build server & client (all architectures)"
+	@echo "  make server-amd64            - Build server & client (amd64 only)"
+	@echo "  make server-armv7            - Build server & client (armv7 only)"
+	@echo "  make server-arm64            - Build server & client (arm64 only)"
+	@echo
+	@echo "Build web app:"
+	@echo "  make web                     - Build the web app"
+	@echo "  make web-deps                - Install web app dependencies (npm install the universe)"
+	@echo "  make web-build               - Actually build the web app"
+	@echo
+	@echo "Build documentation:"
+	@echo "  make docs                    - Build the documentation"
+	@echo "  make docs-deps               - Install Python dependencies (pip3 install)"
+	@echo "  make docs-build              - Actually build the documentation"
 	@echo
 	@echo "Test/check:"
 	@echo "  make test                    - Run tests"
@@ -21,49 +45,45 @@ help:
 	@echo "  make lint                    - Run 'golint'"
 	@echo "  make staticcheck             - Run 'staticcheck'"
 	@echo
-	@echo "Build main client/server:"
-	@echo "  make build                   - Build (using goreleaser, requires clean repo)"
-	@echo "  make build-snapshot          - Build snapshot (using goreleaser, dirty repo)"
-	@echo "  make build-simple            - Quick & dirty build (using go build, without goreleaser)"
-	@echo "  make clean                   - Clean build folder"
-	@echo
-	@echo "Build web app:"
-	@echo "  make web                     - Build the web app"
-	@echo "  make web-deps                - Install web app dependencies (npm install the universe)"
-	@echo "  make web-build               - Actually build the web app"
-	@echo
-	@echo "Build documentation:"
-	@echo "  make docs                     - Build the documentation"
-	@echo "  make docs-deps                - Install Python dependencies (pip3 install)"
-	@echo "  make docs-build               - Actually build the documentation"
-	@echo
-	@echo "Releasing (requires goreleaser):"
+	@echo "Releasing:"
 	@echo "  make release                 - Create a release"
 	@echo "  make release-snapshot        - Create a test release"
 	@echo
 	@echo "Install locally (requires sudo):"
-	@echo "  make install                 - Copy binary from dist/ to /usr/bin"
-	@echo "  make install-deb             - Install .deb from dist/"
-	@echo "  make install-lint            - Install golint"
+	@echo "  make install-amd64           - Copy amd64 binary from dist/ to /usr/bin/ntfy"
+	@echo "  make install-armv7           - Copy armv7 binary from dist/ to /usr/bin/ntfy"
+	@echo "  make install-arm64           - Copy arm64 binary from dist/ to /usr/bin/ntfy"
+	@echo "  make install-deb-amd64       - Install .deb from dist/ (amd64 only)"
+	@echo "  make install-deb-armv7       - Install .deb from dist/ (armv7 only)"
+	@echo "  make install-deb-arm64       - Install .deb from dist/ (arm64 only)"
+
+
+# Building everything
+
+clean: .PHONY
+	rm -rf dist build server/docs server/site
+
+build: web docs server
 
 
 # Documentation
 
+docs: docs-deps docs-build
+
 docs-deps: .PHONY
 	pip3 install -r requirements.txt
 
 docs-build: .PHONY
 	mkdocs build
 
-docs: docs-deps docs-build
-
 
 # Web app
 
+web: web-deps web-build
+
 web-deps:
-	cd web \
-		&& npm install \
-		&& node_modules/svgo/bin/svgo src/img/*.svg
+	cd web && npm install
+	# If this fails for .svg files, optimizes them with svgo
 
 web-build:
 	cd web \
@@ -75,7 +95,37 @@ web-build:
 			../server/site/config.js \
 			../server/site/asset-manifest.json
 
-web: web-deps web-build
+
+# Main server/client build
+
+server: server-deps
+	goreleaser build --snapshot --rm-dist --debug
+
+server-amd64: server-deps-static-sites
+	goreleaser build --snapshot --rm-dist --debug --id ntfy_amd64
+
+server-armv7: server-deps-static-sites server-deps-gcc-armv7
+	goreleaser build --snapshot --rm-dist --debug --id ntfy_armv7
+
+server-arm64: server-deps-static-sites server-deps-gcc-arm64
+	goreleaser build --snapshot --rm-dist --debug --id ntfy_arm64
+
+server-deps: server-deps-static-sites server-deps-all server-deps-gcc
+
+server-deps-gcc: server-deps-gcc-armv7 server-deps-gcc-arm64
+
+server-deps-static-sites:
+	mkdir -p server/docs server/site
+	touch server/docs/index.html server/site/app.html
+
+server-deps-all:
+	which upx || { echo "ERROR: upx not installed. On Ubuntu, run: apt install upx"; exit 1; }
+
+server-deps-gcc-armv7:
+	which arm-linux-gnueabi-gcc || { echo "ERROR: ARMv7 cross compiler not installed. On Ubuntu, run: apt install gcc-arm-linux-gnueabi"; exit 1; }
+
+server-deps-gcc-arm64:
+	which aarch64-linux-gnu-gcc || { echo "ERROR: ARM64 cross compiler not installed. On Ubuntu, run: apt install gcc-aarch64-linux-gnu"; exit 1; }
 
 
 # Test/check targets
@@ -126,34 +176,15 @@ staticcheck: .PHONY
 	rm -rf build/staticcheck
 
 
-# Building targets
-
-build-deps: docs web
-	which arm-linux-gnueabi-gcc || { echo "ERROR: ARMv6/v7 cross compiler not installed. On Ubuntu, run: apt install gcc-arm-linux-gnueabi"; exit 1; }
-	which aarch64-linux-gnu-gcc || { echo "ERROR: ARM64 cross compiler not installed. On Ubuntu, run: apt install gcc-aarch64-linux-gnu"; exit 1; }
-
-build: build-deps
-	goreleaser build --rm-dist --debug
-
-build-snapshot: build-deps
-	goreleaser build --snapshot --rm-dist --debug
-
-build-simple: .PHONY
-	mkdir -p dist/ntfy_linux_amd64 server/docs server/site
-	touch server/docs/index.html
-	touch server/site/app.html
-	export CGO_ENABLED=1
-	go build \
-		-o dist/ntfy_linux_amd64/ntfy \
-		-tags sqlite_omit_load_extension,osusergo,netgo \
-		-ldflags \
-		"-linkmode=external -extldflags=-static -s -w -X main.version=$(VERSION) -X main.commit=$(shell git rev-parse --short HEAD) -X main.date=$(shell date +%s)"
+# Releasing targets
 
-clean: .PHONY
-	rm -rf dist build server/docs server/site
+release: release-deps
+	goreleaser release --rm-dist --debug
 
+release-snapshot: release-deps
+	goreleaser release --snapshot --skip-publish --rm-dist --debug
 
-# Releasing targets
+release-deps: clean server-deps release-check-tags docs web check
 
 release-check-tags:
 	$(eval LATEST_TAG := $(shell git describe --abbrev=0 --tags | cut -c2-))
@@ -161,29 +192,35 @@ release-check-tags:
 	 	echo "ERROR: Must update docs/install.md with latest tag first.";\
 	 	exit 1;\
 	fi
-	if grep -q XXXXX docs/releases.md; then\
-		echo "ERROR: Must update docs/releases.md, found XXXXX.";\
-		exit 1;\
-	fi
 	if ! grep -q $(LATEST_TAG) docs/releases.md; then\
 		echo "ERROR: Must update docs/releases.mdwith latest tag first.";\
 		exit 1;\
 	fi
 
-release: build-deps release-check-tags check
-	goreleaser release --rm-dist --debug
 
-release-snapshot: build-deps
-	goreleaser release --snapshot --skip-publish --rm-dist --debug
+# Installing targets
 
+install-amd64: remove-binary
+	sudo cp -a dist/ntfy_amd64_linux_amd64/ntfy /usr/bin/ntfy
 
-# Installing targets
+install-armv7: remove-binary
+	sudo cp -a dist/ntfy_armv7_linux_armv7/ntfy /usr/bin/ntfy
 
-install:
+install-arm64: remove-binary
+	sudo cp -a dist/ntfy_arm64_linux_arm64/ntfy /usr/bin/ntfy
+
+remove-binary:
 	sudo rm -f /usr/bin/ntfy
-	sudo cp -a dist/ntfy_linux_amd64/ntfy /usr/bin/ntfy
 
-install-deb:
+install-amd64-deb: purge-package
+	sudo dpkg -i dist/ntfy_*_linux_amd64.deb
+
+install-armv7-deb: purge-package
+	sudo dpkg -i dist/ntfy_*_linux_armv7.deb
+
+install-arm64-deb: purge-package
+	sudo dpkg -i dist/ntfy_*_linux_arm64.deb
+
+purge-package:
 	sudo systemctl stop ntfy || true
 	sudo apt-get purge ntfy || true
-	sudo dpkg -i dist/ntfy_*_linux_amd64.deb

docs/develop.md

@@ -16,12 +16,34 @@ server consists of three components:
 * **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/). 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*).
+* **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**. 
 
-### Requirements
+### 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)
@@ -31,27 +53,162 @@ All of these components are built and then **baked into one binary**.
 * [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)
 
-### Check out the code & install dependencies
-Check out via git:
+### 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 SSH"
-    ```
-    git clone git@github.com:binwiederhier/ntfy.git 
-    cd ntfy
-    ```
 === "via HTTPS"
-    ```
+    ``` shell
     git clone https://github.com/binwiederhier/ntfy.git
     cd ntfy
     ```
 
-Then install the dependencies (this assumes Debian/Ubuntu):
+=== "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
+...
 ```
-sudo apt install build-essential libsqlite3-dev
+
+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?
 ```
 
-To install Python/NodeJS (for docs and web app), please see instructions on their websites.
+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.
+
 
 ### 
 

docs/releases.md

@@ -16,9 +16,10 @@ and the [ntfy Android app](https://github.com/binwiederhier/ntfy-android/release
 
 ## ntfy server v1.19.0 (UNRELEASED)
 
-**Bug fixes:**
+**Bug fixes & documentation:**
 
 * Fix install instructions (thanks to [@Fallenbagel](https://github.com/Fallenbagel) for reporting)
+* Additional examples (thanks to [@nickexyz](https://github.com/nickexyz))
 
 -->
 

docs/static/css/extra.css

@@ -8,6 +8,10 @@
     width: unset !important;
 }
 
+.md-sidebar {
+    width: 12.5rem !important;
+}
+
 .md-typeset h4 {
     font-weight: 500 !important;
     margin: 0 !important;

web/package.json

@@ -22,8 +22,7 @@
     "react-router-dom": "^6.2.2",
     "react-scripts": "^5.0.0",
     "stacktrace-gps": "^3.0.4",
-    "stacktrace-js": "^2.0.2",
-    "svgo": "^2.8.0"
+    "stacktrace-js": "^2.0.2"
   },
   "browserslist": {
     "production": [