Merge pull request #20 from github/vdye/docs

Update documentation and installation scripts, fix bug

Author: vdye

Diff for: .github/workflows/release.yml

@@ -47,6 +47,10 @@ jobs:
         uses: actions/setup-go@v3
         with:
           go-version: '1.19.0'
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.2.1'
+      - run: gem install asciidoctor
       - name: Clone repository
         uses: actions/checkout@v3
       - name: Build the release artifact

Diff for: .gitignore

@@ -2,3 +2,4 @@
 /git-bundle-web-server
 /bin/
 /_dist/
+/_docs/

Diff for: .vscode/settings.json

@@ -13,6 +13,13 @@
         "editor.wordWrap": "off",
         "files.trimTrailingWhitespace": true,
     },
+    "[asciidoc]": {
+        "editor.detectIndentation": false,
+        "editor.insertSpaces": true,
+        "editor.tabSize": 2,
+        "editor.wordWrap": "off",
+        "files.trimTrailingWhitespace": true,
+    },
     "[shellscript]": {
         "editor.detectIndentation": false,
         "editor.insertSpaces": false,
@@ -21,6 +28,8 @@
         "files.trimTrailingWhitespace": true,
     },
     "files.associations": {
+        "*.adoc": "asciidoc",
+        "*.asc": "asciidoc",
         "*.md": "markdown",
         "*.sh": "shellscript",
         "prerm": "shellscript",

Diff for: Makefile

@@ -6,9 +6,13 @@ NAME := git-bundle-server
 VERSION :=
 PACKAGE_REVISION := 1
 
+# Installation information
+INSTALL_ROOT := /
+
 # Helpful paths
 BINDIR := $(CURDIR)/bin
 DISTDIR := $(CURDIR)/_dist
+DOCDIR := $(CURDIR)/_docs
 
 # Platform information
 GOOS := $(shell go env GOOS)
@@ -25,6 +29,23 @@ build:
 	@mkdir -p $(BINDIR)
 	GOOS="$(GOOS)" GOARCH="$(GOARCH)" go build -o $(BINDIR) ./...
 
+.PHONY: doc
+doc:
+	@scripts/make-docs.sh --docs="$(CURDIR)/docs/man" \
+			      --output="$(DOCDIR)"
+
+# Installation targets
+.PHONY: install
+install: build doc
+	@echo
+	@echo "======== Installing to $(INSTALL_ROOT) ========"
+	@scripts/install.sh --bindir="$(BINDIR)" \
+			    --docdir="$(DOCDIR)" \
+			    --uninstaller="$(CURDIR)/scripts/uninstall.sh" \
+			    --allow-root \
+			    --include-symlinks \
+			    --install-root="$(INSTALL_ROOT)"
+
 # Packaging targets
 .PHONY: check-arch
 check-arch:
@@ -49,12 +70,13 @@ DEBDIR := $(DISTDIR)/deb
 DEB_FILENAME := $(DISTDIR)/$(NAME)_$(VERSION)-$(PACKAGE_REVISION)_$(PACKAGE_ARCH).deb
 
 # Targets
-$(DEBDIR)/root: check-arch build
+$(DEBDIR)/root: check-arch build doc
 	@echo
 	@echo "======== Formatting package contents ========"
-	@build/package/layout-unix.sh --bindir="$(BINDIR)" \
-				      --include-symlinks \
-				      --output="$(DEBDIR)/root"
+	@scripts/install.sh --bindir="$(BINDIR)" \
+			    --docdir="$(DOCDIR)" \
+			    --include-symlinks \
+			    --install-root="$(DEBDIR)/root"
 
 $(DEB_FILENAME): check-version $(DEBDIR)/root
 	@echo
@@ -80,12 +102,13 @@ PKGDIR := $(DISTDIR)/pkg
 PKG_FILENAME := $(DISTDIR)/$(NAME)_$(VERSION)-$(PACKAGE_REVISION)_$(PACKAGE_ARCH).pkg
 
 # Targets
-$(PKGDIR)/payload: check-arch build
+$(PKGDIR)/payload: check-arch build doc
 	@echo
 	@echo "======== Formatting package contents ========"
-	@build/package/layout-unix.sh --bindir="$(BINDIR)" \
-				      --uninstaller="$(CURDIR)/build/package/pkg/uninstall.sh" \
-				      --output="$(PKGDIR)/payload"
+	@scripts/install.sh --bindir="$(BINDIR)" \
+			    --docdir="$(DOCDIR)" \
+			    --uninstaller="$(CURDIR)/scripts/uninstall.sh" \
+			    --install-root="$(PKGDIR)/payload"
 
 $(PKG_FILENAME): check-version $(PKGDIR)/payload
 	@echo
@@ -111,3 +134,4 @@ clean:
 	go clean ./...
 	$(RM) -r $(BINDIR)
 	$(RM) -r $(DISTDIR)
+	$(RM) -r $(DOCDIR)

Diff for: README.md

@@ -1,4 +1,4 @@
-# `git-bundle-server`: Manage a self-hosted bundle server
+# Git Bundle Server
 
 [bundle-uris]: https://github.com/git/git/blob/next/Documentation/technical/bundle-uri.txt
 [codeowners]: CODEOWNERS
@@ -15,26 +15,86 @@ This repository is under active development, and loves contributions from the
 community :heart:. Check out [CONTRIBUTING][contributing] for details on getting
 started.
 
-## Cloning and Building
+## Getting Started
 
-Be sure to clone inside the `src` directory of your `GOROOT`.
+### Installing
 
-Once there, you can build the `git-bundle-server` and `git-bundle-web-server`
-executables with
+> :warning: Installation on Windows is currently unsupported :warning:
+
+<!-- Common sources -->
+[releases]: https://github.com/github/git-bundle-server/releases
+
+#### Linux
+
+Debian packages (for x86_64 systems) can be downloaded from the
+[Releases][releases] page and installed with:
+
+```bash
+sudo dpkg -i /path/to/git-bundle-server_VVV-RRR_amd64.deb
+
+# VVV: version
+# RRR: package revision
+```
+
+#### MacOS
+
+Packages for both Intel and M1 systems can be downloaded from the
+[Releases][releases] page (identified by the `amd64` vs `arm64` filename suffix,
+respectively). The package can be installed by double-clicking the downloaded
+file, or on the command line with:
+
+```bash
+sudo installer -pkg /path/to/git-bundle-server_VVV-RRR_AAA.pkg -target /
+
+# VVV: version
+# RRR: package revision
+# AAA: platform architecture (amd64 or arm64)
+```
+
+#### From source
+
+> To avoid environment issues building and executing Go code, we recommend that
+> you clone inside the `src` directory of your `GOROOT`.
+
+You can also install the bundle server application from source on any Unix-based
+system. To install to the system root, clone the repository and run:
 
 ```ShellSession
-$ go build -o . ./...
+$ make install
 ```
 
-## Testing and Linting
+Note that you will likely be prompted for a password to allow installing to
+root-owned directories (e.g. `/usr/local/bin`).
 
-To run the project's unit tests, navigate to the repository root directory and
-run `go test -v ./...`.
+To install somewhere other than the system root, you can manually specify an
+`INSTALL_ROOT` when building the `install` target:
 
-To run the project's linter, navigate to the repository root directory and run
-`go vet ./...`.
+```ShellSession
+$ make install INSTALL_ROOT=</your/install/root>
+```
+
+### Uninstalling
+
+#### From Debian package
+
+To uninstall `git-bundle-server` if it was installed from a Debian package, run:
+
+```ShellSession
+$ sudo dpkg -r git-bundle-server
+```
 
-## Bundle Management through CLI
+#### Everything else
+
+All other installation methods include an executable script that uninstalls all
+bundle server resources. On MacOS & Linux, run:
+
+```ShellSession
+$ /usr/local/git-bundle-server/uninstall.sh
+```
+
+## Usage
+
+### Repository management
 
 The following command-line interface allows you to manage which repositories are
 being managed by the bundle server.
@@ -73,7 +133,7 @@ being managed by the bundle server.
 * `git-bundle-server delete <route>`: Remove the configuration for the given
   `<route>` and delete its repository data.
 
-## Web Server Management
+### Web server management
 
 Independent of the management of the individual repositories hosted by the
 server, you can manage the web server process itself using these commands:
@@ -85,6 +145,37 @@ server, you can manage the web server process itself using these commands:
 Finally, if you want to run the web server process directly in your terminal,
 for debugging purposes, then you can run `git-bundle-web-server`.
 
+## Local development
+
+### Building
+
+> To avoid environment issues building and executing Go code, we recommend that
+> you clone inside the `src` directory of your `GOROOT`.
+
+In the root of your cloned repository, you can build the `git-bundle-server` and
+`git-bundle-web-server` executables a few ways.
+
+The first is to use GNU Make; from the root of the repository, simply run:
+
+```ShellSession
+$ make
+```
+
+If you do not have `make` installed on your system, you may instead run (again
+from the repository root):
+
+```ShellSession
+$ go build -o bin/ ./...
+```
+
+### Testing and Linting
+
+To run the project's unit tests, navigate to the repository root directory and
+run `go test -v ./...`.
+
+To run the project's linter, navigate to the repository root directory and run
+`go vet ./...`.
+
 ## License
 
 This project is licensed under the terms of the MIT open source license. Please

Diff for: build/package/layout-unix.sh

@@ -5,15 +5,32 @@ PACKAGE=$1
 INSTALL_DESTINATION=$2
 
 # Directories
-INSTALL_TO="$INSTALL_DESTINATION/usr/local/git-bundle-server/"
-LINK_TO="$INSTALL_DESTINATION/usr/local/bin/"
-RELATIVE_LINK_TO_INSTALL="../git-bundle-server"
+APP_ROOT="$INSTALL_DESTINATION/usr/local/git-bundle-server"
+LINK_TO="$INSTALL_DESTINATION/usr/local/bin"
+RELATIVE_LINK_TO_BIN="../git-bundle-server/bin"
 mkdir -p "$LINK_TO"
 
 # Create symlinks
-for program in "$INSTALL_TO"/bin/*
+for program in "$APP_ROOT"/bin/*
 do
-	/bin/ln -Fs "$RELATIVE_LINK_TO_INSTALL/bin/$(basename $program)" "$LINK_TO/$(basename $program)"
+	p=$(basename "$program")
+	rm -f "$LINK_TO/$p"
+	ln -s "$RELATIVE_LINK_TO_BIN/$p" "$LINK_TO/$p"
+done
+
+for mandir in "$APP_ROOT"/share/man/man*/
+do
+	mdir=$(basename "$mandir")
+	LINK_TO="$INSTALL_DESTINATION/usr/local/share/man/$mdir"
+	RELATIVE_LINK_TO_MAN="../../../git-bundle-server/share/man/$mdir"
+	mkdir -p "$LINK_TO"
+
+	for manpage in "$mandir"/*
+	do
+		mpage=$(basename "$manpage")
+		rm -f "$LINK_TO/$mpage"
+		ln -s "$RELATIVE_LINK_TO_MAN/$mpage" "$LINK_TO/$mpage"
+	done
 done
 
 exit 0