small fixes and doc updates

README.md

@@ -1,25 +1,74 @@
 # [gitdeploy](https://git.rootprojects.org/root/gitdeploy)
 
-**gitdeploy** is an app for handling continuous deployment of static websites.
+**gitdeploy** is an app for continuous deployment of static websites.
+
+## Features
+
+**gitdeploy** is intended for use with static websites that are generated after
+changes are pushed to a Git repository. This works with sites that are being
+edited in code and tracked in Git. Sites that have their content managed with a
+headless CMS that pushes to Git are also very well-suited.
+
+**gitdeploy** supports verified webhooks from Github, Bitbucket, and Gitea.
+
+**gitdeploy** is written in Go. This means that it's a standalone binary
+available on all major operating systems and architectures. It provides an API
+with endpoints that handle webhooks, allow for initiation of builds, and getting
+the status of builds and build jobs.
+
+**gitdeploy** comes with a simple interface. The interface be disabled if you
+don't want to use it.
 
 ## Usage
 
 ```bash
-echo 'GITHUB_SECRET=xxxxxxx' >> .env
+gitdeploy run --listen :3000 --serve-path ./public_overrides --exec ./scripts/
-./gitdeploy init
-./gitdeploy run --listen :3000 --serve-path ./public_overrides --exec ./path/to/scripts/dir/
 ```
 
-Note: If you have mulitple webhook secrets - such as different repos with the same provider -
+## Install
-you should put them in a comma-separated list, such as `GITHUB_SECRET=xxxxxxx,yyyyyyy`.
 
-To manage `git credentials` see [The Vanilla DevOps Git Credentials Cheatsheet][1]
+You can download `gitdeploy` from the Github Releases API and place it in your PATH,
+or install it with Webi:
 
-[1]: https://coolaj86.com/articles/vanilla-devops-git-credentials-cheatsheet/
+**Mac**, **Linux**:
 
-## Git Info
+```bash
+curl -sS https://webinstall.dev/gitdeploy | bash
+```
 
-The exec script will receive the parent environment as well as
+**Windows 10**:
+
+```bash
+curl -A MS https://webinstall.dev/gitdeploy | bash
+```
+
+## Setup with Deploy Scripts
+
+Start by copying from `examples/` to `scripts/`.
+
+```bash
+rsync -av examples/ scripts/
+```
+
+```txt
+scripts/
+├── deploy.sh
+├── git.example.com/org/go-project/deploy.sh
+├── git.example.com/org/node-project/deploy.sh
+├── git.example.com/org/mirror-project/deploy.sh
+└── promote.sh
+```
+
+The default `deploy.sh` is sensible -
+if another `deploy.sh` exists in a directory with the same repo name
+as an incoming webhook, it runs it.
+
+The example deploy scripts are a good start, but you'll probably
+need to update them to suit your build process for your project.
+
+### Git Info
+
+These ENVs are set before each script is run:
 
 ```bash
 GIT_DEPLOY_JOB_ID=xxxxxx
@@ -30,8 +79,6 @@ GIT_REPO_NAME=example
 GIT_CLONE_URL=https://github.com/example/example
 ```
 
-You can see examples in `examples/git.example.com/org`
-
 ## API
 
 ```txt
@@ -65,6 +112,8 @@ POST /api/admin/webhooks/{github,gitea,bitbucket}
 
 ## Build
 
+**Frontend**:
+
 ```bash
 pushd html/
   npm ci
@@ -72,9 +121,20 @@ pushd html/
 popd
 ```
 
+**API**:
+
+With [GoReleaser](https://webinstall.dev/goreleaser):
+
 ```bash
-go mod tidy
+goreleaser --snapshot --skip-publish --rm-dist
-go mod vendor
+```
+
+With [Golang](https://webinstall.dev/golang):
+
+```bash
+export GOFLAGS="-mod=vendor"
+
+go run -mod=vendor git.rootprojects.org/root/go-gitver/v2
 go generate -mod=vendor ./...
 go build -mod=vendor .
 ```
@@ -135,28 +195,6 @@ URL: https://YOUR_DOMAIN/api/webhooks/bitbucket?access_token=YOUR_SECRET
 Triggers: Repository push
 ```
 
-## TODO
-
-**gitdeploy** is intended for use with static websites that are generated after
-changes are pushed to a Git repository. This works with sites that are being
-edited in code and tracked in Git. Sites that have their content managed with a
-headless CMS that pushes to Git are also very well-suited.
-
-**gitdeploy** supports verified webhooks from Github, Bitbucket, and Gitea.
-
-**gitdeploy** is written in Go. This means that it's a standalone binary
-available on all major operating systems and architectures. It provides an API
-with endpoints that handle webhooks, allow for initiation of builds, and getting
-the status of builds and build jobs.
-
-**gitdeploy** comes with a simple interface. The interface be disabled if you
-don't want to use it.
-
-**gitdeploy** also comes with basic authentication via integration with
-[Pocket ID](https://pocketid.app). Authentication can also be disabled if you
-don't want to use it. The built-in interface requires the built-in
-authentication.
-
 ## How to Generate a Base64 Secret
 
 **in your browser**:

examples/dotenv

@@ -1,4 +1,13 @@
+# PORT only listens on localhost
 PORT=4483
-GITHUB_SECRET=xxxxxxxxxxxxxxxxxxxxxx
+
+# LISTEN lets you choose the interface also
+#LISTEN=0.0.0.0:4483
+
+# List promotions in descending order
+PROMOTIONS="production staging master"
+
+# List your various webhook secrets
+GITHUB_SECRET=xxxxxxxxxxxxxxxxxxxxxx,yyyyyyyyyyyyyyyyyy
 GITEA_SECRET=xxxxxxxxxxxxxxxxxxxxxx
 BITBUCKET_SECRET=xxxxxxxxxxxxxxxxxxxxxx

go.mod

@@ -3,6 +3,7 @@ module git.rootprojects.org/root/gitdeploy
 go 1.15
 
 require (
+	git.rootprojects.org/root/go-gitver/v2 v2.0.2
 	github.com/go-chi/chi v4.1.2+incompatible
 	github.com/google/go-github/v32 v32.1.0
 	github.com/joho/godotenv v1.3.0

go.sum

@@ -1,3 +1,5 @@
+git.rootprojects.org/root/go-gitver/v2 v2.0.2 h1:T+Je13wrY1jz4OPJF98HnuCNp6n2Xe2uK6/NNF6a4+0=
+git.rootprojects.org/root/go-gitver/v2 v2.0.2/go.mod h1:ur82M/jZcvr1WWihyVtNEgDBqIjo22o56wcVHeVJFh8=
 github.com/go-chi/chi v4.1.2+incompatible h1:fGFk2Gmi/YKXk0OmGfBh0WgmN3XB8lVnEyNz34tQRec=
 github.com/go-chi/chi v4.1.2+incompatible/go.mod h1:eB3wogJHnLi3x/kFX2A+IbTBlXxmMeXJVKy9tTv1XzQ=
 github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=

internal/tools/tools.go

@@ -4,7 +4,8 @@
 package tools
 
 import (
-	// these are 'go generate' tooling dependencies, not including in the binary
+	// these are 'go generate' tooling dependencies, not included in the binary
 	_ "github.com/shurcooL/vfsgen"
 	_ "github.com/shurcooL/vfsgen/cmd/vfsgendev"
+	_ "git.rootprojects.org/root/go-gitver/v2"
 )

main.go

@@ -30,16 +30,15 @@ var (
 )
 
 func usage() {
-	ver()
+	fmt.Println(ver())
 	fmt.Println("")
-	fmt.Println("Use 'help <command>'")
+	fmt.Printf("Use '%s help <command>'\n", name)
-	fmt.Println("  help")
 	fmt.Println("  init")
 	fmt.Println("  run")
 }
 
-func ver() {
+func ver() string {
-	fmt.Printf("%s v%s %s (%s)\n", name, version, commit[:7], date)
+	return fmt.Sprintf("%s v%s %s (%s)", name, version, commit[:7], date)
 }
 
 type job struct {
@@ -78,13 +77,22 @@ func init() {
 }
 
 func main() {
+	// Support [--]version and -V
+	if len(os.Args) > 1 {
+		if "version" == strings.TrimLeft(os.Args[1], "-") || "-V" == os.Args[1] {
+			fmt.Println(ver())
+			os.Exit(0)
+			return
+		}
+	}
+
 	args := os.Args[:]
 	if 1 == len(args) {
 		// "run" should be the default
 		args = append(args, "run")
 	}
 
-	if "help" == args[1] {
+	if "help" == strings.TrimLeft(args[1], "-") {
 		// top-level help
 		if 2 == len(args) {
 			usage()
@@ -99,7 +107,7 @@ func main() {
 
 	switch args[1] {
 	case "version":
-		ver()
+		fmt.Println(ver())
 		os.Exit(0)
 		return
 	case "init":
@@ -191,6 +199,23 @@ func serve() {
 
 	webhooks.RouteHandlers(r)
 
+	r.Get("/version", func(w http.ResponseWriter, r *http.Request) {
+		w.Write(append([]byte(ver()), '\n'))
+	})
+	r.Get("/api/version", func(w http.ResponseWriter, r *http.Request) {
+		b, _ := json.MarshalIndent(struct {
+			Name    string `json:"name"`
+			Version string `json:"version"`
+			Date    string `json:"date"`
+			Commit  string `json:"commit"`
+		}{
+			Name:    name,
+			Version: version,
+			Date:    date,
+			Commit:  commit,
+		}, "", "  ")
+		w.Write(append(b, '\n'))
+	})
 	r.Route("/api/admin", func(r chi.Router) {
 		r.Use(func(next http.Handler) http.Handler {
 			return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

vendor/modules.txt

@@ -1,3 +1,7 @@
+# git.rootprojects.org/root/go-gitver/v2 v2.0.2
+## explicit
+git.rootprojects.org/root/go-gitver/v2
+git.rootprojects.org/root/go-gitver/v2/gitver
 # github.com/go-chi/chi v4.1.2+incompatible
 ## explicit
 github.com/go-chi/chi