docs: document packaging and system-wide installation

Describe installing from the Arch and Debian packages, system-wide installs via PREFIX/DESTDIR, the packaging release flow, and add the new directories to the project layout.

.gitignore

@@ -19,3 +19,15 @@ coverage.*
 *.swp
 *~
 .DS_Store
+
+# Debian packaging build output
+/debian/files
+/debian/lazyntfy/
+/debian/*.substvars
+/debian/.debhelper/
+
+# Arch Linux packaging build output
+/packaging/archlinux/src/
+/packaging/archlinux/pkg/
+/packaging/archlinux/*.pkg.tar.*
+/packaging/archlinux/*.tar.gz

Makefile

@@ -2,33 +2,42 @@ BINARY  := lazyntfy
 PREFIX  ?= $(HOME)/.local
 BINDIR  ?= $(PREFIX)/bin
 MANDIR  ?= $(PREFIX)/share/man/man1
+DOCDIR  ?= $(PREFIX)/share/doc/$(BINARY)
+DESTDIR ?=
 VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null | sed 's/^v//' | grep . || echo 0.1.0)
 TOPIC   ?= alerts
+GO      ?= go
+GOFLAGS ?= -trimpath
 
 LDFLAGS := -X main.version=$(VERSION)
 
-.PHONY: build install uninstall test vet fmt run man clean
+.PHONY: all build install uninstall man test vet fmt run deb arch clean
+
+all: build
 
 build:
-	go build -ldflags "$(LDFLAGS)" -o $(BINARY) ./cmd/lazyntfy
+	$(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BINARY) ./cmd/lazyntfy
 
+# System-wide install: sudo make install PREFIX=/usr/local
+# Staged install:       make install DESTDIR=/tmp/pkg PREFIX=/usr
 install: build
-	mkdir -p "$(BINDIR)" "$(MANDIR)"
+	install -Dm755 $(BINARY) "$(DESTDIR)$(BINDIR)/$(BINARY)"
-	install -m 755 $(BINARY) "$(BINDIR)/$(BINARY)"
+	install -Dm644 man/lazyntfy.1 "$(DESTDIR)$(MANDIR)/lazyntfy.1"
-	install -m 644 man/lazyntfy.1 "$(MANDIR)/lazyntfy.1"
+	install -Dm644 LICENSE "$(DESTDIR)$(DOCDIR)/copyright"
+	install -Dm644 README.md "$(DESTDIR)$(DOCDIR)/README.md"
 
 uninstall:
-	rm -f "$(BINDIR)/$(BINARY)" "$(MANDIR)/lazyntfy.1"
+	rm -f "$(DESTDIR)$(BINDIR)/$(BINARY)" "$(DESTDIR)$(MANDIR)/lazyntfy.1"
+	rm -rf "$(DESTDIR)$(DOCDIR)"
 
 man:
-	mkdir -p "$(MANDIR)"
+	install -Dm644 man/lazyntfy.1 "$(DESTDIR)$(MANDIR)/lazyntfy.1"
-	install -m 644 man/lazyntfy.1 "$(MANDIR)/lazyntfy.1"
 
 test:
-	go test ./...
+	$(GO) test ./...
 
 vet:
-	go vet ./...
+	$(GO) vet ./...
 
 fmt:
 	gofmt -w .
@@ -36,5 +45,19 @@ fmt:
 run: build
 	./$(BINARY) $(TOPIC)
 
+# Build a Debian/Ubuntu package. -d skips build-dependency checks so the
+# package can also be built on a machine without golang-go installed as a
+# distro package.
+deb:
+	dpkg-buildpackage -us -uc -b -d
+	mkdir -p dist
+	mv -f ../$(BINARY)_*_*.deb ../$(BINARY)_*_*.changes ../$(BINARY)_*_*.buildinfo dist/ 2>/dev/null || true
+	@echo "  packages written to dist/"
+
+arch:
+	cd packaging/archlinux && makepkg -f
+
 clean:
 	rm -f $(BINARY)
+	rm -rf dist
+	-$(MAKE) -f debian/rules clean

README.md

@@ -41,24 +41,67 @@ already seen so nothing is delivered twice.
 
 ## Installation
 
+### Arch Linux
+
+A `PKGBUILD` lives in [`packaging/archlinux`](packaging/archlinux). Build and
+install the package with `makepkg`:
+
+```sh
+git clone https://src.panahifar.ir/ahp/lazyntfy.git
+cd lazyntfy/packaging/archlinux
+makepkg -si
+```
+
+This installs `/usr/bin/lazyntfy`, the man page under `/usr/share/man`, the
+license, and the README, and pulls in `ca-certificates` so TLS to your ntfy
+server works.
+
+### Debian and Ubuntu
+
+A debhelper-free source package lives in [`debian`](debian). Build a `.deb` and
+install it system-wide:
+
+```sh
+git clone https://src.panahifar.ir/ahp/lazyntfy.git
+cd lazyntfy
+make deb                       # writes dist/lazyntfy_<version>_<arch>.deb
+sudo apt install ./dist/lazyntfy_*.deb
+```
+
+`apt install ./file.deb` (or `dpkg -i` followed by `apt -f install`) resolves
+the `ca-certificates` dependency. The packaging needs only the Go toolchain and
+`dpkg-dev`; `make deb` passes `-d` so it also builds where `golang-go` is not
+installed as a distribution package.
+
 ### From source
 
 ```sh
 git clone https://src.panahifar.ir/ahp/lazyntfy.git
 cd lazyntfy
-make install            # installs the binary and the man page under ~/.local
+make install                   # into ~/.local, no root needed
 ```
 
-`make install` honors `PREFIX` (default `~/.local`):
+`make install` honors `PREFIX`, `BINDIR`, `MANDIR`, `DOCDIR`, and `DESTDIR`.
+Picking a system prefix installs for every user:
 
 ```sh
-make install PREFIX=/usr/local
+sudo make install PREFIX=/usr/local   # /usr/local/bin/lazyntfy, /usr/local/share/man/man1
+sudo make install PREFIX=/usr         # /usr/bin/lazyntfy, /usr/share/man/man1
+```
+
+Stage a filesystem tree into a temporary root instead of the live system (handy
+for building your own package):
+
+```sh
+make install DESTDIR="$PWD/stage" PREFIX=/usr
 ```
 
 ### With `go install`
 
+From a checkout:
+
 ```sh
-go install ./cmd/lazyntfy@latest   # or: go install lazyntfy/cmd/lazyntfy
+go install ./cmd/lazyntfy      # binary in $(go env GOPATH)/bin
 ```
 
 ## Usage
@@ -131,6 +174,25 @@ messages are pruned on startup. Credentials are never written to the database
 the current run's authentication is always used. History is best effort: if the
 file cannot be opened, the client still runs.
 
+## Packaging
+
+Both package formats are defined in the repository. `make deb` builds a Debian
+package from the working tree; the Arch `PKGBUILD` builds the `v$pkgver` release
+archive from the Gitea instance.
+
+| Format | Build | Definition |
+| --- | --- | --- |
+| Debian / Ubuntu | `make deb` → `dist/*.deb` | [`debian/`](debian) |
+| Arch Linux | `make arch` → `makepkg` | [`packaging/archlinux/PKGBUILD`](packaging/archlinux/PKGBUILD) |
+
+When cutting a release:
+
+1. Bump the version in [`debian/changelog`](debian/changelog) and `pkgver` in
+   the `PKGBUILD`.
+2. Tag the commit (`git tag -s vX.Y.Z`) and push it.
+3. In `packaging/archlinux`, run `updpkgsums` to refresh the tarball checksum and
+   `makepkg --printsrcinfo > .SRCINFO`.
+
 ## Development
 
 ```sh
@@ -162,6 +224,8 @@ go test ./internal/history/...
 | `internal/textutil` | width-aware text wrapping and clipping |
 | `internal/tui` | Bubble Tea interface |
 | `man` | `lazyntfy(1)` man page |
+| `debian` | Debian / Ubuntu package definition |
+| `packaging/archlinux` | Arch Linux `PKGBUILD` |
 
 ## Contributing
 

debian/changelog

@@ -0,0 +1,5 @@
+lazyntfy (0.1.0) unstable; urgency=medium
+
+  * Initial release.
+
+ -- Amir Husayn Panahifar <ahp@panahifar.ir>  Sun, 11 Oct 2026 12:00:00 +0330

debian/control

@@ -0,0 +1,23 @@
+Source: lazyntfy
+Section: utils
+Priority: optional
+Maintainer: Amir Husayn Panahifar <ahp@panahifar.ir>
+Build-Depends: golang-go (>= 2:1.26)
+Standards-Version: 4.7.0
+Homepage: https://src.panahifar.ir/ahp/lazyntfy
+Vcs-Git: https://src.panahifar.ir/ahp/lazyntfy.git
+Vcs-Browser: https://src.panahifar.ir/ahp/lazyntfy
+Rules-Requires-Root: no
+
+Package: lazyntfy
+Architecture: any
+Depends: ca-certificates
+Description: lazygit-style terminal client for ntfy
+ lazyntfy is a terminal user interface for the ntfy pub-sub notification
+ service, laid out like lazygit: topics in the left pane, messages in the
+ middle pane, and the selected message in the right pane.
+ .
+ It speaks the ntfy HTTP API directly, subscribes to several topics over a
+ single stream, reconnects automatically, summarizes Grafana and Alertmanager
+ webhook bodies, and remembers topics and messages between runs in a small
+ SQLite database.

debian/copyright

@@ -0,0 +1,19 @@
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: lazyntfy
+Source: https://src.panahifar.ir/ahp/lazyntfy
+
+Files: *
+Copyright: 2026 Amir Husayn Panahifar <ahp@panahifar.ir>
+License: GPL-3.0-or-later
+ This program is free software: you can redistribute it and/or modify it
+ under the terms of the GNU General Public License as published by the
+ Free Software Foundation, either version 3 of the License, or (at your
+ option) any later version.
+ .
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ General Public License for more details.
+ .
+ On Debian systems the full text of the GNU General Public License can be
+ found in /usr/share/common-licenses/GPL-3.

debian/rules

@@ -0,0 +1,37 @@
+#!/usr/bin/make -f
+# Debian packaging without debhelper: the Go toolchain builds the binary and
+# the rules stage it by hand. This keeps the build dependencies to just Go.
+
+export CGO_ENABLED = 0
+
+PACKAGE := lazyntfy
+VERSION := $(shell dpkg-parsechangelog -SVersion)
+PKGDIR  := debian/$(PACKAGE)
+
+.PHONY: clean build build-arch build-indep binary binary-arch binary-indep
+
+clean:
+	rm -rf $(PKGDIR) $(PACKAGE)
+	rm -f debian/files
+
+build: build-arch build-indep
+
+build-arch: $(PACKAGE)
+
+build-indep:
+
+$(PACKAGE):
+	go build -trimpath -ldflags "-s -w -X main.version=$(VERSION)" -o $(PACKAGE) ./cmd/$(PACKAGE)
+
+binary: binary-arch binary-indep
+
+binary-arch: build-arch
+	install -d $(PKGDIR)/DEBIAN
+	install -Dm755 $(PACKAGE) $(PKGDIR)/usr/bin/$(PACKAGE)
+	install -Dm644 man/lazyntfy.1 $(PKGDIR)/usr/share/man/man1/lazyntfy.1
+	install -Dm644 LICENSE $(PKGDIR)/usr/share/doc/$(PACKAGE)/copyright
+	install -Dm644 README.md $(PKGDIR)/usr/share/doc/$(PACKAGE)/README.md
+	dpkg-gencontrol -p$(PACKAGE) -P$(PKGDIR)
+	dpkg-deb --build --root-owner-group $(PKGDIR) ..
+
+binary-indep:

debian/source/format

@@ -0,0 +1 @@
+3.0 (native)

packaging/archlinux/.SRCINFO

@@ -0,0 +1,16 @@
+pkgbase = lazyntfy
+	pkgdesc = A lazygit-style terminal client for ntfy
+	pkgver = 0.1.0
+	pkgrel = 1
+	url = https://src.panahifar.ir/ahp/lazyntfy
+	arch = x86_64
+	arch = aarch64
+	license = GPL-3.0-or-later
+	makedepends = go
+	depends = ca-certificates
+	options = !strip
+	options = !debug
+	source = lazyntfy-0.1.0.tar.gz::https://src.panahifar.ir/ahp/lazyntfy/archive/v0.1.0.tar.gz
+	sha256sums = 72c8d2675b4b3241197748793b2e16afd7e1c61102433efbaf0bf93dd59c9141
+
+pkgname = lazyntfy

packaging/archlinux/PKGBUILD

@@ -0,0 +1,38 @@
+# Maintainer: Amir Husayn Panahifar <ahp@panahifar.ir>
+
+pkgname=lazyntfy
+pkgver=0.1.0
+pkgrel=1
+pkgdesc="A lazygit-style terminal client for ntfy"
+arch=('x86_64' 'aarch64')
+url="https://src.panahifar.ir/ahp/lazyntfy"
+license=('GPL-3.0-or-later')
+depends=('ca-certificates')
+makedepends=('go')
+options=('!strip' '!debug')
+source=("$pkgname-$pkgver.tar.gz::$url/archive/v$pkgver.tar.gz")
+sha256sums=('72c8d2675b4b3241197748793b2e16afd7e1c61102433efbaf0bf93dd59c9141')
+
+prepare() {
+	cd "$pkgname"
+	go mod download
+}
+
+build() {
+	cd "$pkgname"
+	export CGO_ENABLED=0
+	go build -trimpath -ldflags "-s -w -X main.version=$pkgver" -o lazyntfy ./cmd/lazyntfy
+}
+
+check() {
+	cd "$pkgname"
+	go test ./...
+}
+
+package() {
+	cd "$pkgname"
+	install -Dm755 lazyntfy "$pkgdir/usr/bin/lazyntfy"
+	install -Dm644 man/lazyntfy.1 "$pkgdir/usr/share/man/man1/lazyntfy.1"
+	install -Dm644 LICENSE "$pkgdir/usr/share/licenses/$pkgname/LICENSE"
+	install -Dm644 README.md "$pkgdir/usr/share/doc/$pkgname/README.md"
+}