Add mkdocs generator, docs layout, and publish docs

* Publish matchbox docs to https://matchbox.psdn.io
* Remove references to https://coreos.com/matchbox/docs

CHANGES.md

@@ -4,6 +4,7 @@ Notable changes between releases.
 
 ## Latest
 
+* Publish docs to [https://matchbox.psdn.io](https://matchbox.psdn.io/)
 * Add `get-fedora-coreos` script ([#763](https://github.com/poseidon/matchbox/pull/763))
 * Update container image base from `alpine:3.9` to `alpine:3.10` ([#761](https://github.com/poseidon/matchbox/pull/761))
 * Build matchbox with Go v1.12.10 for images and binaries ([#766](https://github.com/poseidon/matchbox/pull/766))

README.md

@@ -1,43 +1,37 @@
 # matchbox [![Build Status](https://travis-ci.org/poseidon/matchbox.svg?branch=master)](https://travis-ci.org/poseidon/matchbox) [![GoDoc](https://godoc.org/github.com/poseidon/matchbox?status.svg)](https://godoc.org/github.com/poseidon/matchbox) [![Docker Repository on Quay](https://quay.io/repository/poseidon/matchbox/status "Docker Repository on Quay")](https://quay.io/repository/poseidon/matchbox)
 
-`matchbox` is a service that matches bare-metal machines (based on labels like MAC, UUID, etc.) to profiles that PXE boot and provision Container Linux clusters. Profiles specify the kernel/initrd, kernel arguments, iPXE config, GRUB config, [Container Linux Config][cl-config], or other configs a machine should use. Matchbox can be [installed](Documentation/deployment.md) as a binary, RPM, container image, or deployed on a Kubernetes cluster and it provides an authenticated gRPC API for clients like [Terraform][terraform].
+`matchbox` is a service that matches bare-metal machines to profiles that PXE boot and provision clusters. Machines are matched by labels like MAC or UUID during PXE and profiles specify a kernel/initrd, iPXE config, and Container Linux or Fedora CoreOS config.
 
-* [Documentation][docs]
-* [matchbox Service](Documentation/matchbox.md)
-* [Profiles](Documentation/matchbox.md#profiles)
-* [Groups](Documentation/matchbox.md#groups)
-* Config Templates
-  * [Container Linux Config][cl-config]
-  * [Cloud-Config][cloud-config]
-* [Configuration](Documentation/config.md)
-* [HTTP API](Documentation/api.md) / [gRPC API](https://godoc.org/github.com/poseidon/matchbox/matchbox/client)
-* [Background: Machine Lifecycle](Documentation/machine-lifecycle.md)
-* [Background: PXE Booting](Documentation/network-booting.md)
+## Features
 
-### Installation
+* Chainload via iPXE and match hardware labels
+* Provision Container Linux and Fedora CoreOS (powered by [Ignition](https://github.com/coreos/ignition))
+* Authenticated gRPC API for clients (e.g. Terraform)
 
-* Installation
-  * Installing on [Container Linux / other distros](Documentation/deployment.md)
-  * Installing on [Kubernetes](Documentation/deployment.md#kubernetes)
-  * Running with [docker](Documentation/deployment.md#docker)
-* [Network Setup](Documentation/network-setup.md)
+## Documentation
 
-### Tutorials
+* [Docs](https://matchbox.psdn.io/)
+* [Configuration](docs/config.md)
+* [HTTP API](docs/api-http.md) / [gRPC API](docs/grpc-api.md)
+
+## Installation
+
+Matchbox can be installed from a binary or a container image.
+
+* Install Matchbox on [Kubernetes](docs/deployment.md#kubernetes), on a [Linux](docs/deployment.md) host, or as a [container](docs/deployment.md#docker)
+* Setup a PXE-enabled [network](docs/network-setup.md)
+
+## Tutorials
+
+[Getting started](docs/getting-started.md) provisioning machines with Container Linux.
 
-* [Getting Started](Documentation/getting-started.md) - provision physical machines with Container Linux
 * Local QEMU/KVM
-  * [matchbox with Docker](Documentation/getting-started-docker.md)
+    * [matchbox with Docker](docs/getting-started-docker.md)
 * Clusters
-  * [etcd3](Documentation/getting-started-docker.md) - Install a 3-node etcd3 cluster
-* Clusters (Terraform-based)
-  * [etcd3](examples/terraform/etcd3-install/README.md) - Install a 3-node etcd3 cluster
+    * [etcd3](docs/getting-started-docker.md) - Install a 3-node etcd3 cluster
+    * [etcd3](https://github.com/poseidon/matchbox/tree/master/examples/terraform/etcd3-install) - Install a 3-node etcd3 cluster (terraform-based)
 
 ## Contrib
 
 * [dnsmasq](contrib/dnsmasq/README.md) - Run DHCP, TFTP, and DNS services as a container
 * [terraform-provider-matchbox](https://github.com/poseidon/terraform-provider-matchbox) - Terraform provider plugin for Matchbox
-
-[docs]: https://coreos.com/matchbox/docs/latest
-[terraform]: https://github.com/poseidon/terraform-provider-matchbox
-[cl-config]: Documentation/container-linux-config.md
-[cloud-config]: Documentation/cloud-config.md

docs/api-grpc.md

@@ -0,0 +1,16 @@
+# gRPC API
+
+## Protos
+
+* [rpc.proto](https://github.com/poseidon/matchbox/blob/master/matchbox/rpc/rpcpb/rpc.proto)
+* [storage.proto](https://github.com/poseidon/matchbox/blob/master/matchbox/storage/storagepb/storage.proto)
+
+## Client Libraries
+
+gRPC client libraries
+
+* [Go](https://godoc.org/github.com/poseidon/matchbox/matchbox/client)
+
+## Client Plugins
+
+* [terraform-provider-matchbox](https://github.com/poseidon/terraform-provider-matchbox)

docs/cloud-config.md

@@ -1,7 +1,7 @@
+# Cloud Config
 
-# Cloud config
-
-**Note:** Please migrate to [Container Linux Configs](container-linux-config.md). Cloud-Config support will be removed in the future.
+!!! warning
+    Migrate to [Container Linux Configs](container-linux-config.md). Cloud-Config support will be removed in the future.
 
 CoreOS Cloud-Config is a system for configuring machines with a Cloud-Config file or executable script from user-data. Cloud-Config runs in userspace on each boot and implements a subset of the [cloud-init spec](http://cloudinit.readthedocs.org/en/latest/topics/format.html#cloud-config-data). See the cloud-config [docs](https://coreos.com/os/docs/latest/cloud-config.html) for details.
 
@@ -18,13 +18,12 @@ Cloud-Config template files can be added in `/var/lib/matchbox/cloud` or in a `c
 
 ## Reference
 
-Reference a Cloud-Config in a [Profile](matchbox.md#profiles) with `cloud_id`. When PXE booting, use the kernel option `cloud-config-url` to point to `matchbox` [cloud-config endpoint](api.md#cloud-config).
+Reference a Cloud-Config in a [Profile](matchbox.md#profiles) with `cloud_id`. When PXE booting, use the kernel option `cloud-config-url` to point to `matchbox` [cloud-config endpoint](api-http.md#cloud-config).
 
 ## Examples
 
 Here is an example Cloud-Config which starts some units and writes a file.
 
-<!-- {% raw %} -->
 ```yaml
 #cloud-config
 coreos:
@@ -40,7 +39,6 @@ write_files:
     content: |
       {{.greeting}}
 ```
-<!-- {% endraw %} -->
 
 The Cloud-Config [Validator](https://coreos.com/validate/) is also useful for checking your Cloud-Config files for errors.
 

docs/config.md

@@ -54,7 +54,7 @@ $ sudo docker run -p 8080:8080 --rm -v $PWD/examples/assets:/var/lib/matchbox/as
 
 ### With examples
 
-Mount `examples` to pre-load the [example](../examples/README.md) machine groups and profiles. Run the container.
+Mount `examples` to pre-load the example machine groups and profiles. Run the container.
 
 ```sh
 $ sudo docker run -p 8080:8080 --rm -v $PWD/examples:/var/lib/matchbox:Z -v $PWD/examples/groups/etcd:/var/lib/matchbox/groups:Z quay.io/poseidon/matchbox:latest -address=0.0.0.0:8080 -log-level=debug

docs/container-linux-config.md

@@ -25,7 +25,7 @@ Container Linux Config templates can be added to the `/var/lib/matchbox/ignition
 
 ## Referencing in Profiles
 
-Profiles can include a Container Linux Config for provisioning machines. Specify the Container Linux Config in a [Profile](matchbox.md#profiles) with `ignition_id`. When PXE booting, use the kernel option `coreos.first_boot=1` and `coreos.config.url` to point to the `matchbox` [Ignition endpoint](api.md#ignition-config).
+Profiles can include a Container Linux Config for provisioning machines. Specify the Container Linux Config in a [Profile](matchbox.md#profiles) with `ignition_id`. When PXE booting, use the kernel option `coreos.first_boot=1` and `coreos.config.url` to point to the `matchbox` [Ignition endpoint](api-http.md#ignition-config).
 
 ## Examples
 

docs/dev/release.md

@@ -49,7 +49,7 @@ Verify the reported version.
 
 ## Signing
 
-Release tarballs are signed by Dalton Hubble's GPG [Key](Documentation/deployment.md#download)
+Release tarballs are signed by Dalton Hubble's GPG [Key](/docs/deployment.md#download)
 
 ```sh
 cd _output

docs/getting-started-docker.md

@@ -121,4 +121,4 @@ $ sudo ./scripts/libvirt destroy
 
 ## Going further
 
-Learn more about [matchbox](matchbox.md) or explore the other [example](../examples) clusters. Try the [k8s example](bootkube.md) to produce a TLS-authenticated Kubernetes cluster you can access locally with `kubectl`.
+Learn more about [matchbox](matchbox.md) or explore the other [example](../examples) clusters.

docs/getting-started.md

@@ -98,7 +98,7 @@ provider "matchbox" {
 
 #### Profiles
 
-Machine profiles specify the kernel, initrd, kernel args, Container Linux Config, Cloud-config, or other configs used to network boot and provision a bare-metal machine. This profile will PXE boot machines using the current stable Container Linux kernel and initrd (see [assets](api.md#assets) to learn about caching for speed) and supply a Container Linux Config specifying that a disk install and reboot should be performed. Learn more about [Container Linux configs](https://coreos.com/os/docs/latest/configuration.html).
+Machine profiles specify the kernel, initrd, kernel args, Container Linux Config, Cloud-config, or other configs used to network boot and provision a bare-metal machine. This profile will PXE boot machines using the current stable Container Linux kernel and initrd (see [assets](api-http.md#assets) to learn about caching for speed) and supply a Container Linux Config specifying that a disk install and reboot should be performed. Learn more about [Container Linux configs](https://coreos.com/os/docs/latest/configuration.html).
 
 ```hcl
 // Create a CoreOS-install profile
@@ -191,7 +191,7 @@ To re-provision the machine for another purpose, run `terraform apply` and PXE b
 
 ## Going Further
 
-Matchbox can be used to provision multi-node Container Linux clusters at one or many on-premise sites if deployed in an HA way. Machines can be matched individually by MAC address, UUID, region, or other labels you choose. Installs can be made much faster by caching images in the built-in HTTP [assets](api.md#assets) server.
+Matchbox can be used to provision multi-node Container Linux clusters at one or many on-premise sites if deployed in an HA way. Machines can be matched individually by MAC address, UUID, region, or other labels you choose. Installs can be made much faster by caching images in the built-in HTTP [assets](api-http.md#assets) server.
 
 [Container Linux configs](https://coreos.com/os/docs/latest/configuration.html) can be used to partition disks and filesystems, write systemd units, write networkd configs or regular files, and create users. Container Linux nodes can be provisioned into a system that meets your needs. Checkout the examples which create a 3 node [etcd](../examples/terraform/etcd3-install) cluster or a 3 node [Kubernetes](../examples/terraform/bootkube-install) cluster.
 

docs/index.md

@@ -0,0 +1,32 @@
+# Matchbox
+
+Matchbox is a service that matches bare-metal machines to profiles that PXE boot and provision clusters. Machines are matched by labels like MAC or UUID during PXE and profiles specify a kernel/initrd, iPXE config, and Container Linux or Fedora CoreOS config.
+
+## Features
+
+* Chainload via iPXE and match hardware labels
+* Provision Container Linux and Fedora CoreOS (powered by [Ignition](https://github.com/coreos/ignition))
+* Authenticated gRPC API for clients (e.g. Terraform)
+
+## Installation
+
+Matchbox can be installed from a binary or a container image.
+
+* Install Matchbox on [Kubernetes](deployment.md#kubernetes), on a [Linux](deployment.md) host, or as a [container](deployment.md#docker)
+* Setup a PXE-enabled [network](network-setup.md)
+
+## Tutorials
+
+[Getting started](getting-started.md) provisioning machines with Container Linux.
+
+* Local QEMU/KVM
+    * [matchbox with Docker](getting-started-docker.md)
+* Clusters
+    * [etcd3](getting-started-docker.md) - Install a 3-node etcd3 cluster
+    * [etcd3](https://github.com/poseidon/matchbox/tree/master/examples/terraform/etcd3-install) - Install a 3-node etcd3 cluster (terraform-based)
+
+## Related
+
+* [dnsmasq](https://github.com/poseidon/matchbox/tree/master/contrib/dnsmasq) - container image to run DHCP, TFTP, and DNS services
+* [terraform-provider-matchbox](https://github.com/poseidon/terraform-provider-matchbox) - Terraform provider plugin for Matchbox
+* [Typhoon](https://typhoon.psdn.io/) - minimal and free Kubernetes distribution, supporting bare-metal

docs/matchbox.md

@@ -18,7 +18,7 @@ See [configuration](config.md) flags and variables.
 
 ## API
 
-* [HTTP API](api.md)
+* [HTTP API](api-http.md)
 * [gRPC API](https://godoc.org/github.com/poseidon/matchbox/matchbox/client)
 
 ## Data
@@ -76,9 +76,9 @@ Profiles reference an Ignition config, Cloud-Config, and/or generic config by na
 
 The `"boot"` settings will be used to render configs to network boot programs such as iPXE or GRUB. You may reference remote kernel and initrd assets or [local assets](#assets).
 
-To use Ignition, set the `coreos.config.url` kernel option to reference the `matchbox` [Ignition endpoint](api.md#ignition-config), which will render the `ignition_id` file. Be sure to add the `coreos.first_boot` option as well.
+To use Ignition, set the `coreos.config.url` kernel option to reference the `matchbox` [Ignition endpoint](api-http.md#ignition-config), which will render the `ignition_id` file. Be sure to add the `coreos.first_boot` option as well.
 
-To use cloud-config, set the `cloud-config-url` kernel option to reference the `matchbox` [Cloud-Config endpoint](api.md#cloud-config), which will render the `cloud_id` file.
+To use cloud-config, set the `cloud-config-url` kernel option to reference the `matchbox` [Cloud-Config endpoint](api-http.md#cloud-config), which will render the `cloud_id` file.
 
 ### Groups
 
@@ -172,7 +172,7 @@ matchbox.foo/assets/
 
 For example, a `Profile` might refer to a local asset `/assets/coreos/VERSION/coreos_production_pxe.vmlinuz` instead of `http://stable.release.core-os.net/amd64-usr/VERSION/coreos_production_pxe.vmlinuz`.
 
-See the [get-coreos](../scripts/README.md#get-coreos) script to quickly download, verify, and place Container Linux assets.
+See the [get-coreos](https://github.com/poseidon/matchbox/blob/master/scripts/get-coreos) script to quickly download, verify, and place Container Linux assets.
 
 ## Network
 
@@ -181,5 +181,5 @@ See the [get-coreos](../scripts/README.md#get-coreos) script to quickly download
 ## Going further
 
 * [gRPC API Usage](config.md#grpc-api)
-* [Metadata](api.md#metadata)
-* OpenPGP [Signing](api.md#openpgp-signatures)
+* [Metadata](api-http.md#metadata)
+* OpenPGP [Signing](api-http.md#openpgp-signatures)

docs/network-booting.md

@@ -66,7 +66,7 @@ boot
 
 A TFTP server is used only to provide the `undionly.kpxe` boot program to older PXE firmware in order to bootstrap into iPXE.
 
-CoreOS `matchbox` can render signed iPXE scripts to machines based on their hardware attributes. Setup involves configuring your DHCP server to point iPXE clients to the `matchbox` [iPXE endpoint](api.md#ipxe).
+CoreOS `matchbox` can render signed iPXE scripts to machines based on their hardware attributes. Setup involves configuring your DHCP server to point iPXE clients to the `matchbox` [iPXE endpoint](api-http.md#ipxe).
 
 ## DHCP
 

docs/network-setup.md

@@ -208,7 +208,7 @@ $ sudo firewall-cmd --add-service=dhcp --add-service=tftp --add-service=dns
 
 ### Development
 
-Install the dependencies for [QEMU with UEFI](https://fedoraproject.org/wiki/Using_UEFI_with_QEMU). Walk through the [getting-started-with-docker](getting-started-with-docker.md) tutorial. Launch client VMs using `create-uefi`.
+Install the dependencies for [QEMU with UEFI](https://fedoraproject.org/wiki/Using_UEFI_with_QEMU). Walk through the [getting-started-with-docker](getting-started-docker.md) tutorial. Launch client VMs using `create-uefi`.
 
 Create UEFI QEMU/KVM VMs attached to the `docker0` bridge.
 

mkdocs.yml

@@ -0,0 +1,60 @@
+site_name: 'matchbox'
+site_description: 'Network boot and provision bare-metal clusters' 
+site_author: 'Dalton Hubble'
+repo_name: 'poseidon/matchbox'
+repo_url: 'https://github.com/poseidon/matchbox'
+theme:
+  name: 'material'
+  palette:
+    primary: 'red'
+    accent: 'orange'
+  font:
+    text: 'Roboto Slab'
+    code: 'Roboto Mono'
+extra:
+  social:
+    - type: 'github'
+      link: 'https://github.com/poseidon'
+    - type: 'twitter'
+      link: 'https://twitter.com/typhoon8s'
+nav:
+  - Home: 'index.md'
+  - 'Matchbox':
+    - 'Concepts': 'matchbox.md'
+    - 'Container Linux Config': 'container-linux-config.md'
+    - 'Cloud-Config': 'cloud-config.md'
+    - 'HTTP API': 'api-http.md'
+    - 'gRPC API': 'api-grpc.md'
+    - 'OpenPGP Signing': 'openpgp.md'
+  - 'Tutorials':
+    - 'getting-started.md'
+    - 'getting-started-docker.md'
+    - 'Network Boot Environment': 'network-booting.md' 
+    - 'Machine Lifecycle': 'machine-lifecycle.md'
+  - 'Install':
+    - 'Network Setup': 'network-setup.md'
+    - 'Deployment': 'deployment.md'
+    - 'Configuration': 'config.md'
+    - 'Troubleshooting': 'troubleshooting.md'
+markdown_extensions:
+  - admonition
+  - codehilite
+  - footnotes
+  - toc:
+      permalink: true
+  - pymdownx.arithmatex
+  - pymdownx.betterem:
+      smart_enable: all
+  - pymdownx.caret
+  - pymdownx.critic
+  - pymdownx.emoji:
+      emoji_generator: !!python/name:pymdownx.emoji.to_svg
+  - pymdownx.inlinehilite
+  - pymdownx.magiclink
+  - pymdownx.mark
+  - pymdownx.smartsymbols
+  - pymdownx.superfences
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - pymdownx.tilde
+

requirements.txt

@@ -0,0 +1,4 @@
+mkdocs==1.0.4
+mkdocs-material==4.5.0
+pygments==2.4.2
+pymdown-extensions==6.2.0