WIP: Develop docs
Philipp Heckel
parent
470d11f442
commit
5b10f51af1
60
Makefile
60
Makefile
|
|
@ -4,37 +4,47 @@ VERSION := $(shell git describe --tag)
|
|||
|
||||
help:
|
||||
@echo "Typical commands:"
|
||||
@echo " make check - Run all tests, vetting/formatting checks and linters"
|
||||
@echo " make fmt build-snapshot install - Build latest and install to local system"
|
||||
@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 "Test/check:"
|
||||
@echo " make test - Run tests"
|
||||
@echo " make race - Run tests with -race flag"
|
||||
@echo " make coverage - Run tests and show coverage"
|
||||
@echo " make coverage-html - Run tests and show coverage (as HTML)"
|
||||
@echo " make coverage-upload - Upload coverage results to codecov.io"
|
||||
@echo " make test - Run tests"
|
||||
@echo " make race - Run tests with -race flag"
|
||||
@echo " make coverage - Run tests and show coverage"
|
||||
@echo " make coverage-html - Run tests and show coverage (as HTML)"
|
||||
@echo " make coverage-upload - Upload coverage results to codecov.io"
|
||||
@echo
|
||||
@echo "Lint/format:"
|
||||
@echo " make fmt - Run 'go fmt'"
|
||||
@echo " make fmt-check - Run 'go fmt', but don't change anything"
|
||||
@echo " make vet - Run 'go vet'"
|
||||
@echo " make lint - Run 'golint'"
|
||||
@echo " make staticcheck - Run 'staticcheck'"
|
||||
@echo " make fmt - Run 'go fmt'"
|
||||
@echo " make fmt-check - Run 'go fmt', but don't change anything"
|
||||
@echo " make vet - Run 'go vet'"
|
||||
@echo " make lint - Run 'golint'"
|
||||
@echo " make staticcheck - Run 'staticcheck'"
|
||||
@echo
|
||||
@echo "Build:"
|
||||
@echo " make build - Build"
|
||||
@echo " make build-snapshot - Build snapshot"
|
||||
@echo " make build-simple - Build (using go build, without goreleaser)"
|
||||
@echo " make clean - Clean build folder"
|
||||
@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 " make release - Create a release"
|
||||
@echo " make release-snapshot - Create a test release"
|
||||
@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 - Copy binary from dist/ to /usr/bin"
|
||||
@echo " make install-deb - Install .deb from dist/"
|
||||
@echo " make install-lint - Install golint"
|
||||
|
||||
|
||||
# Documentation
|
||||
|
|
@ -42,9 +52,11 @@ help:
|
|||
docs-deps: .PHONY
|
||||
pip3 install -r requirements.txt
|
||||
|
||||
docs: docs-deps
|
||||
docs-build: .PHONY
|
||||
mkdocs build
|
||||
|
||||
docs: docs-deps docs-build
|
||||
|
||||
|
||||
# Web app
|
||||
|
||||
|
|
@ -126,7 +138,7 @@ build: build-deps
|
|||
build-snapshot: build-deps
|
||||
goreleaser build --snapshot --rm-dist --debug
|
||||
|
||||
build-simple: clean
|
||||
build-simple: .PHONY
|
||||
mkdir -p dist/ntfy_linux_amd64 server/docs server/site
|
||||
touch server/docs/index.html
|
||||
touch server/site/app.html
|
||||
|
|
|
|||
|
|
@ -1,16 +1,72 @@
|
|||
# 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 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/). 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
|
||||
|
||||
* [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)
|
||||
|
||||
### Check out the code & install dependencies
|
||||
Check out via git:
|
||||
|
||||
=== "via SSH"
|
||||
```
|
||||
git clone git@github.com:binwiederhier/ntfy.git
|
||||
cd ntfy
|
||||
```
|
||||
=== "via HTTPS"
|
||||
```
|
||||
git clone https://github.com/binwiederhier/ntfy.git
|
||||
cd ntfy
|
||||
```
|
||||
|
||||
Then install the dependencies (this assumes Debian/Ubuntu):
|
||||
|
||||
```
|
||||
sudo apt install build-essential libsqlite3-dev
|
||||
```
|
||||
|
||||
To install Python/NodeJS (for docs and web app), please see instructions on their websites.
|
||||
|
||||
###
|
||||
|
||||
XXXXXXXXXXXXXXXXXXXXx
|
||||
|
||||
|
||||
### Quick & dirty (amd64 only)
|
||||
To quickly build on amd64, you can use `make build-simple`:
|
||||
|
||||
```
|
||||
git clone git@github.com:binwiederhier/ntfy.git
|
||||
cd ntfy
|
||||
make build-simple
|
||||
```
|
||||
|
||||
That'll generate a statically linked binary in `dist/ntfy_linux_amd64/ntfy`.
|
||||
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:
|
||||
|
|
@ -39,7 +95,7 @@ The Android app has two flavors:
|
|||
First check out the repository:
|
||||
|
||||
```
|
||||
git clone git@github.com:binwiederhier/ntfy-android.git
|
||||
git clone git@github.com:binwiederhier/ntfy-android.git # or: https://github.com/binwiederhier/ntfy-android.git
|
||||
cd ntfy-android
|
||||
```
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue