Merge pull request #3 from rul/doc

Tidy up example files and add an scdoc manpage

23 files changed, 139 insertions, 7 deletions

diff --git a/.gitignore b/.gitignore
index 74046b8..be201f7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,3 +29,6 @@ _testmain.go
 shoelaces
 config.yaml
 *.deb
+
+# auto-generated manpage
+docs/shoelaces.8
diff --git a/Makefile b/Makefile
index 7ce9d40..a831cb3 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,6 @@
 GO = go
+SCDOC = scdoc
+
 pkgs = $(shell $(GO) list ./... | grep -v /vendor/)
 
 all:
@@ -8,8 +10,15 @@ fmt:
 	$(GO) fmt
 
 clean:
-	rm -f shoelaces
+	rm -f shoelaces docs/shoelaces.8
+
+shoelaces.8:
+	$(SCDOC) < docs/shoelaces.8.scd > docs/shoelaces.8
+
+docs: shoelaces.8
 
 test: fmt
 		$(GO) test -v $(pkgs) && \
 			./test/integ-test/integ_test.py
+
+.PHONY: all clean docs
diff --git a/README.md b/README.md
index a1309ae..a76ef52 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ As soon as Shoelaces starts, the service will be patiently waiting for servers
 to boot. If no servers are detected, you'll simply see a spinner in the web UI,
 as can be seen in the screenshot.
 
-![Shoelaces frontend - Waiting for hosts](shoelaces-frontend-1.png)
+![Shoelaces frontend - Waiting for hosts](docs/screenshots/shoelaces-frontend-1.png)
 
 The URL `localhost:8081` will actually point to wherever you are running your
 Shoelaces instance. It must be reachable by the booting hosts.
@@ -30,7 +30,7 @@ Shoelaces instance. It must be reachable by the booting hosts.
 The following picture shows a high level overview of how a server notifies
 Shoelaces that it's ready for booting.
 
-![Shoelaces overview](shoelaces-overview.png)
+![Shoelaces overview](docs/screenshots/shoelaces-overview.png)
 
 In this graph we can see that as soon as the server boots using network boot, we
 instruct the machine to switch to an [iPXE](https://ipxe.org/) ROM. We do this
@@ -50,7 +50,7 @@ guessed, will be pointing to Shoelaces.
 If there was no automated installation configured for the booting server, you'll
 be able to select an option to bootstrap it in the Shoelaces UI.
 
-![Shoelaces frontend - Host detected](shoelaces-frontend-2.png)
+![Shoelaces frontend - Host detected](docs/screenshots/shoelaces-frontend-2.png)
 
 A couple of things can be said about this screenshot:
 
@@ -95,7 +95,7 @@ Shoelaces accepts several parameters:
 * `config`: the path to a configuration file.
 * `data-dir`: the path to the root directory with the templates. It's advised to
   manage the templates in a VCS, such as a git repository. Refer to the [example
-  data directory](configs/example-templates-configs/) for more information.
+  data directory](configs/data-dir/) for more information.
 * `debug`: enable debug messages.
 * `domain`: the domain Shoelaces is going to be listening on.
 * `mappings-file`: the path to the YAML mappings file, relative to the `data-dir` parameter.
@@ -178,7 +178,7 @@ that.
 
 Shoelaces will read these mappings from a YAML file that can be passed as a
 program parameter. Refer to the [example mappings
-file](configs/example-templates-configs/mappings.yaml) for more information.
+file](configs/data-dir/mappings.yaml) for more information.
 
 ## Environments
 
diff --git a/configs/example-templates-configs/cloud-config/cloud-config-release.slc b/configs/data-dir/cloud-config/cloud-config-release.slc
index 0f3de35..0f3de35 100644
--- a/configs/example-templates-configs/cloud-config/cloud-config-release.slc
+++ b/configs/data-dir/cloud-config/cloud-config-release.slc
diff --git a/configs/example-templates-configs/cloud-config/users.slc b/configs/data-dir/cloud-config/users.slc
index 6ebdd3f..6ebdd3f 100644
--- a/configs/example-templates-configs/cloud-config/users.slc
+++ b/configs/data-dir/cloud-config/users.slc
diff --git a/configs/example-templates-configs/ipxe/centos.ipxe.slc b/configs/data-dir/ipxe/centos.ipxe.slc
index 88b3fc2..88b3fc2 100644
--- a/configs/example-templates-configs/ipxe/centos.ipxe.slc
+++ b/configs/data-dir/ipxe/centos.ipxe.slc
diff --git a/configs/example-templates-configs/ipxe/coreos.ipxe.slc b/configs/data-dir/ipxe/coreos.ipxe.slc
index 64685ff..64685ff 100644
--- a/configs/example-templates-configs/ipxe/coreos.ipxe.slc
+++ b/configs/data-dir/ipxe/coreos.ipxe.slc
diff --git a/configs/example-templates-configs/ipxe/debian.ipxe.slc b/configs/data-dir/ipxe/debian.ipxe.slc
index 8717d5e..8717d5e 100644
--- a/configs/example-templates-configs/ipxe/debian.ipxe.slc
+++ b/configs/data-dir/ipxe/debian.ipxe.slc
diff --git a/configs/example-templates-configs/ipxe/linux.cfg.slc b/configs/data-dir/ipxe/linux.cfg.slc
index 512f7f2..512f7f2 100644
--- a/configs/example-templates-configs/ipxe/linux.cfg.slc
+++ b/configs/data-dir/ipxe/linux.cfg.slc
diff --git a/configs/example-templates-configs/ipxe/storage.ipxe.slc b/configs/data-dir/ipxe/storage.ipxe.slc
index 457dad7..457dad7 100644
--- a/configs/example-templates-configs/ipxe/storage.ipxe.slc
+++ b/configs/data-dir/ipxe/storage.ipxe.slc
diff --git a/configs/example-templates-configs/ipxe/ubuntu-minimal.ipxe.slc b/configs/data-dir/ipxe/ubuntu-minimal.ipxe.slc
index e52f63c..e52f63c 100644
--- a/configs/example-templates-configs/ipxe/ubuntu-minimal.ipxe.slc
+++ b/configs/data-dir/ipxe/ubuntu-minimal.ipxe.slc
diff --git a/configs/example-templates-configs/kickstart/centos.ks.slc b/configs/data-dir/kickstart/centos.ks.slc
index 04d5455..04d5455 100644
--- a/configs/example-templates-configs/kickstart/centos.ks.slc
+++ b/configs/data-dir/kickstart/centos.ks.slc
diff --git a/configs/example-templates-configs/mappings.yaml b/configs/data-dir/mappings.yaml
index dfcb8c9..dfcb8c9 100644
--- a/configs/example-templates-configs/mappings.yaml
+++ b/configs/data-dir/mappings.yaml
diff --git a/configs/example-templates-configs/preseed/common.preseed.slc b/configs/data-dir/preseed/common.preseed.slc
index bcbf98b..bcbf98b 100644
--- a/configs/example-templates-configs/preseed/common.preseed.slc
+++ b/configs/data-dir/preseed/common.preseed.slc
diff --git a/configs/example-templates-configs/preseed/debian.preseed.slc b/configs/data-dir/preseed/debian.preseed.slc
index 0915fe3..0915fe3 100644
--- a/configs/example-templates-configs/preseed/debian.preseed.slc
+++ b/configs/data-dir/preseed/debian.preseed.slc
diff --git a/configs/example-templates-configs/preseed/storage.preseed.slc b/configs/data-dir/preseed/storage.preseed.slc
index 982b41b..982b41b 100644
--- a/configs/example-templates-configs/preseed/storage.preseed.slc
+++ b/configs/data-dir/preseed/storage.preseed.slc
diff --git a/configs/example-templates-configs/preseed/ubuntu-minimal.preseed.slc b/configs/data-dir/preseed/ubuntu-minimal.preseed.slc
index 2138764..2138764 100644
--- a/configs/example-templates-configs/preseed/ubuntu-minimal.preseed.slc
+++ b/configs/data-dir/preseed/ubuntu-minimal.preseed.slc
diff --git a/configs/example-templates-configs/static/test-script b/configs/data-dir/static/test-script
index 8c33db6..8c33db6 100644
--- a/configs/example-templates-configs/static/test-script
+++ b/configs/data-dir/static/test-script
diff --git a/configs/shoelaces.conf b/configs/shoelaces.conf
index fd4230f..b4ed606 100644
--- a/configs/shoelaces.conf
+++ b/configs/shoelaces.conf
@@ -1,6 +1,6 @@
 port=8081
 domain=localhost
-data-dir=configs/example-templates-configs/
+data-dir=configs/data-dir/
 template-extension=.slc
 mappings-file=mappings.yaml
 debug=true
diff --git a/shoelaces-frontend-1.png b/docs/screenshots/shoelaces-frontend-1.png
index 96518e9..96518e9 100644
--- a/shoelaces-frontend-1.png
+++ b/docs/screenshots/shoelaces-frontend-1.png
diff --git a/shoelaces-frontend-2.png b/docs/screenshots/shoelaces-frontend-2.png
index 4864303..4864303 100644
--- a/shoelaces-frontend-2.png
+++ b/docs/screenshots/shoelaces-frontend-2.png
diff --git a/shoelaces-overview.png b/docs/screenshots/shoelaces-overview.png
index 812fa8b..812fa8b 100644
--- a/shoelaces-overview.png
+++ b/docs/screenshots/shoelaces-overview.png
diff --git a/docs/shoelaces.8.scd b/docs/shoelaces.8.scd
new file mode 100644
index 0000000..ec38101
--- /dev/null
+++ b/docs/shoelaces.8.scd
@@ -0,0 +1,120 @@
+shoelaces(8)
+
+# NAME
+
+shoelaces - automated server bootstrapping
+
+# SYNOPSIS
+
+*shoelaces* [options...]
+
+# OPTIONS
+
+*-config* <config>
+	Specifies a config file. All the following options can be specified in
+	the config.
+
+*-data-dir* <directory>
+	Specifies a directory with mappings, configs, templates, etc.
+
+*-debug*
+	Enables debug mode.
+
+*-domain* <hostname>
+	Specifies the address where the server is going to listen.
+	Defaults to "localhost".
+
+*-env-dir* <directory>
+	Specifies a directory with environment overrides. Refer to the README of
+	the project for more information about environment overrides.
+
+*-mappings-file* <file>
+	Specifies a mappings YAML file. Defaults to "mappings.yaml". Refer to the
+	README of the project for more information about mappings.
+
+*-port* <port>
+	Specifies the port where the server is going to listen.
+	Defaults to 8080.
+
+*-static-dir* <directory>
+	Specifies a custom web directory with static files. Defaults to "web".
+
+*-template-extension* <extension>
+	Shoelaces template extension. Defaults to ".slc".
+
+# DESCRIPTION
+
+Shoelaces serves over HTTP iPXE boot scripts, cloud-init configuration, and
+any other configuration files to baremetal or virtual machines booting
+using iPXE. It also does a few other things to make easier managing server
+deployments:
+
+- Has a simple but nice UI to show the current configuration, and history
+  of servers that booted.
+- Uses Go templates to handle complex configurations.
+- Allows specifying the boot entry point for a given server based on its IP
+  address or DNS PTR record.
+- Supports the notion of environments for Development and Production
+  environment configurations, while trying to minimize template
+  duplication.
+- Puts unknown servers into iPXE script boot retry loop, while at the same
+  time showing them in the UI allowing the user to select a specific boot
+  configuration.
+
+Shoelaces is better when used along a DHCP server. Refer to the
+*CONFIGURATION* section for examples on how to configure a DHCP server for
+hooking it with Shoelaces.
+
+# CONFIGURATION
+
+Shoelaces searches for a config file whenever the *-config* flag is
+specified.
+
+Here is example config file:
+
+```
+port=8081
+domain=localhost
+data-dir=/etc/shoelaces/data-dir/
+template-extension=.slc
+mappings-file=mappings.yaml
+debug=true
+```
+
+*dhcpd*(8) can be hooked with Shoelaces by adding the following snippet in
+*dhcpd.conf*(5):
+
+```
+# dhcp.conf
+next-server <your-tftp-server>;
+if exists user-class and option user-class = "iPXE" {
+  filename "http://<shoelaces-server>/poll/1/${netX/mac:hexhyp}";
+} else {
+  filename "undionly.kpxe";
+}
+```
+
+Similarly, *dnsmasq*(8) can be configured for working with Shoelaces with
+the following snippet:
+
+```
+dhcp-match=set:ipxe,175 # iPXE sends a 175 option.
+dhcp-boot=tag:!ipxe,undionly.kpxe
+dhcp-boot=http://<shoelaces-server>/poll/1/${netX/mac:hexhyp}
+```
+
+A TFTP server such as *tftpd*(8) must be configured to serve the IPXE ROM,
+*undionly.kpxe*.
+
+# SEE ALSO
+
+*dhcpd*(8) *dhcpd.conf*(5) *dnsmasq*(8) *tftpd*(8)
+
+# AUTHORS
+
+Maintained by ThousandEyes Inc. <opensource@thousandeyes.com>.
+
+Up-to-date sources can be found at https://github.com/thousandeyes/shoelaces.
+
+Bugs reports and patches can be submitted via GitHub's interface or
+contacting the maintainers directly via email.