Update README

2025-10-17 23:12:11 -04:00
parent eaf08421b0
commit 0b6efee2e2
1 changed files with 264 additions and 3 deletions
--- a/README.md
+++ b/README.md
@@ -1,8 +1,269 @@
 # Relibre
 **Music release one-page generator**

-Relibre is a simple, free and open source landing page generator that is an alternative to services such as HyperFollow. Relibre has one job- giving the artist the ability to generate a single html file to self-host with their own methods.
- 
-  
+Relibre is a simple, free, and open-source landing-page generator—an alternative to HyperFollow—that produces a **single self-contained HTML file** you can host anywhere.
+
 **Try the generator →** [`https://`](https://relibre.site)

+---
+
+## What you get
+- A clean, responsive, single-file HTML page for a release
+- No trackers, no analytics, no lock-in
+- Host it anywhere (object storage, GitHub/Gitea Pages, your own server, IPFS, etc.)
+- Optional native desktop app (Go + WebKit webview) that can save directly to your **Downloads** folder
+
+---
+
+## Quick start (static site)
+This repo already contains `index.html` and the generator under `/ui`.
+
+Open locally:
+```bash
+# simple Python server
+python3 -m http.server 8080
+# → http://localhost:8080
+```
+
+---
+
+## Launch / self-host with Docker or Podman
+
+Relibre ships multiple compose variants so you can choose your reverse proxy. All of them:
+- build an internal `web` container that serves the static files
+- expose a `proxy` on **localhost:8080** (HAProxy, Caddy, Apache httpd, or Nginx)
+
+**Files:**
+- `docker-compose.yml.haproxy`
+- `docker-compose.yml.caddy`
+- `docker-compose.yml.apache`
+- `docker-compose.yml.nginx`
+- `proxy/` (proxy configs)
+- `Dockerfile` (optional static Nginx serve; not required when using the variants above)
+
+### Docker
+```bash
+# HAProxy
+docker compose -f docker-compose.yml.haproxy up -d --build
+
+# Caddy
+docker compose -f docker-compose.yml.caddy up -d --build
+
+# Apache
+docker compose -f docker-compose.yml.apache up -d --build
+
+# Nginx
+docker compose -f docker-compose.yml.nginx up -d --build
+```
+Open: http://localhost:8080
+
+### Podman
+```bash
+# If you have podman-compose:
+podman-compose -f docker-compose.yml.nginx up -d --build
+
+# Or via podman directly (example for Nginx)
+podman build -t relibre-web -f Dockerfile.web .
+podman run --name relibre-web -d --rm -p 8081:80 relibre-web
+```
+
+> **Production note:** put a TLS-terminating proxy (Caddy/Traefik/HAProxy/Nginx) in front, or your existing edge/load balancer. These examples run HTTP only.
+
+---
+
+## Native desktop build (Go webview app)
+
+Builds a single executable that opens Relibre inside the OS webview (WebKitGTK on Linux, WebView2 on Windows, WKWebView on macOS). The app runs a tiny localhost server and can save the generated HTML directly to your **Downloads** folder.
+
+### Prereqs
+- **Arch:** `sudo pacman -S --needed base-devel go webkit2gtk gtk3 pkgconf`
+- **Debian/Ubuntu:** 
+  ```bash
+  sudo apt update
+  sudo apt install -y build-essential golang pkg-config     libgtk-3-dev libwebkit2gtk-4.1-dev libsoup-3.0-dev
+  ```
+- **macOS:** Install Go (Homebrew is fine). WebKit is built-in.
+- **Windows:** Install Go and the **WebView2** runtime (Win11 has it by default).
+
+> If your distro provides only `webkit2gtk-4.1.pc` and the module looks for `4.0`, you can locally add a compat symlink:
+> - Arch: `sudo ln -s /usr/lib/pkgconfig/webkit2gtk-4.1.pc /usr/lib/pkgconfig/webkit2gtk-4.0.pc`  
+> - Debian/Ubuntu: `sudo ln -s /usr/lib/x86_64-linux-gnu/pkgconfig/webkit2gtk-4.1.pc /usr/lib/x86_64-linux-gnu/pkgconfig/webkit2gtk-4.0.pc`
+
+### Build
+At the repo **root** (next to `index.html`, `ui/`, `images/`), add these files if they aren’t already present:
+
+`go.mod`
+```mod
+module relibre
+
+go 1.22
+```
+
+`Makefile`
+```makefile
+APP=relibre-app
+
+.PHONY: deps run build clean
+deps:
+	go get github.com/webview/webview_go@latest
+	go mod tidy
+
+run:
+	go run .
+
+build:
+	go build -trimpath -ldflags "-s -w" -o $(APP)
+
+clean:
+	rm -f $(APP)
+```
+
+`main.go` (excerpt – already in repo if you followed earlier steps)
+```go
+//go:embed index.html ui/* images/*
+var content embed.FS
+
+// POST /save writes to ~/Downloads when running the native app
+// (see main.go in the repo for full implementation)
+```
+
+Build & run:
+```bash
+make deps
+make build
+./relibre-app
+```
+
+---
+
+## Arch Linux (AUR) packaging
+
+You can publish two AUR packages:
+
+- **`relibre`** – builds from source
+- **`relibre-bin`** – installs a prebuilt binary from your Releases
+
+### From source (local PKGBUILD)
+Create `PKGBUILD`:
+```bash
+pkgname=relibre
+pkgver=0.1.0
+pkgrel=1
+pkgdesc="Native webview app to generate single-file landing pages for music releases"
+arch=('x86_64')
+url="https://git.circlewithadot.net/incentive/relibre"
+license=('MIT')
+depends=('gtk3' 'webkit2gtk' 'libsoup3')
+makedepends=('go' 'git')
+provides=('relibre')
+
+source=("${pkgname}::git+${url}.git#tag=v${pkgver}")
+sha256sums=('SKIP')
+
+prepare() {
+  cd "${srcdir}/${pkgname}"
+  export GOPATH="${srcdir}/gopath"
+  export GOMODCACHE="${GOPATH}/pkg/mod"
+  go mod download
+}
+
+build() {
+  cd "${srcdir}/${pkgname}"
+  export CGO_ENABLED=1
+  go build -trimpath -ldflags "-s -w" -o relibre
+}
+
+package() {
+  cd "${srcdir}/${pkgname}"
+  install -Dm755 relibre "${pkgdir}/usr/bin/relibre"
+
+  install -Dm644 dist/com.circlewithadot.Relibre.desktop     "${pkgdir}/usr/share/applications/com.circlewithadot.Relibre.desktop"
+  install -Dm644 dist/com.circlewithadot.Relibre.png     "${pkgdir}/usr/share/icons/hicolor/512x512/apps/com.circlewithadot.Relibre.png"
+
+  install -Dm644 LICENSE "${pkgdir}/usr/share/licenses/${pkgname}/LICENSE"
+}
+```
+
+Build locally:
+```bash
+makepkg -si
+```
+
+Publish to AUR (once your AUR repo is created):
+```bash
+makepkg --printsrcinfo > .SRCINFO
+git add PKGBUILD .SRCINFO
+git commit -m "relibre ${pkgver}"
+git push  # to your AUR remote
+```
+
+---
+
+## Flatpak / Flathub
+
+Relibre works well as a Flatpak using the GNOME runtime (WebKitGTK included).
+
+Create `com.circlewithadot.Relibre.yml` at repo root:
+```yaml
+app-id: com.circlewithadot.Relibre
+runtime: org.gnome.Platform
+runtime-version: '46'
+sdk: org.gnome.Sdk
+command: relibre
+finish-args:
+  - --share=network
+  - --socket=wayland
+  - --socket=fallback-x11
+  - --filesystem=xdg-download
+modules:
+  - name: relibre
+    buildsystem: simple
+    build-commands:
+      - go env -w CGO_ENABLED=1
+      - go mod download
+      - go build -trimpath -ldflags "-s -w" -o /app/bin/relibre
+      - install -Dm644 dist/com.circlewithadot.Relibre.desktop /app/share/applications/com.circlewithadot.Relibre.desktop
+      - install -Dm644 dist/com.circlewithadot.Relibre.png /app/share/icons/hicolor/512x512/apps/com.circlewithadot.Relibre.png
+    sources:
+      - type: dir
+        path: .
+```
+
+Also add:
+- `dist/com.circlewithadot.Relibre.desktop`
+  ```ini
+  [Desktop Entry]
+  Type=Application
+  Name=Relibre
+  Comment=Generate single-file landing pages for music releases
+  Exec=relibre
+  Icon=com.circlewithadot.Relibre
+  Categories=AudioVideo;Utility;
+  Terminal=false
+  ```
+- `dist/com.circlewithadot.Relibre.png` (512×512 icon – you can copy `images/relibre_logo.png`)
+
+Build & run locally:
+```bash
+flatpak install -y org.gnome.Platform//46 org.gnome.Sdk//46
+flatpak-builder --user --install --force-clean build-dir com.circlewithadot.Relibre.yml
+flatpak run com.circlewithadot.Relibre
+```
+
+### Submit to Flathub (outline)
+1. Ensure the app uses an **appstream** file: `dist/com.circlewithadot.Relibre.metainfo.xml`.
+2. Host a signed source archive or tag (Git).
+3. Fork the Flathub repo, add your manifest under `com.circlewithadot.Relibre`, open a PR.
+4. CI will build and review; address any sandboxing requests (portals, permissions).
+
+---
+
+## License
+MIT — see `LICENSE`.
+
+## Contributing
+PRs welcome!
+- Features: templates, themes, icon sets, translations
+- Packaging: help maintain Flatpak & AUR recipes
+- Docs: quickstart guides for common hosts (Netlify, Pages, S3, IPFS)
+