Added documentation.

README.md

@@ -0,0 +1,55 @@
+# Project Faros
+
+Project Faros is a reference implimentation of Red Hat OpenShift 4 on small,
+bare-metal clusters. The project includes reference architectures and automated
+deployment tools. We are looking to bring OpenShift everywhere, even to the
+edge.
+
+## Installation
+
+Please follow [these instructions](./docs/prereqs.md) to ensure all of the
+prerequisites are met and to install the Faros cluster manager.
+
+## Cluster Deployment
+
+Run the following commands from your bastion node:
+
+```bash
+# Launch the interactive cluster configuration TUI
+farosctl config
+
+# Create the required virtual infrastructure
+# (bootstrap and virtual bastion app node)
+farosctl create machines
+
+# Configure network infrastructure (DNS and DHCP)
+farosctl create network
+
+# Create the cluster load balancer
+farosctl create load-balancer
+
+# Create the installation source and config repositories
+farosctl create install-repos
+
+# Create the OpenShift cluster
+farosctl create cluster
+```
+
+That's it!
+
+## Connecting the the Cluster
+
+During install, cockpit is installed on the bastion node and hosted on port
+9090. Check that out [here](http://bastion:9090). Log in with the standard user
+account. This interface can be used to check virtual machines and get a
+terminal session on the server. There will also be a Faros tab with helpful
+links to various cluster resources.
+
+The farosctl command can be used to connect to the cluster as well.
+
+```bash
+farosctl oc get nodes
+```
+
+Any of the `oc` commands can be executed this way. They will be run as the
+default `kubeadmin` user.

docs/ilo.md

@@ -0,0 +1,6 @@
+# HPE iLO Management Provider
+
+HPE Integrated Lights Out (iLO) is the management interface that is built into
+HPE servers. Faros will connect over HTTPS to the iLO interface to control the
+bare metal systems. To prepare an iLO interface for Faros, simply set the
+Administrator password. All machines must have the same administrator password.

docs/kvm.md

@@ -0,0 +1,8 @@
+# KVM Management Provider
+
+Currently, the KVM provider can only be used for the bootstrap node and the
+bastion app node. These nodes will be provisioned as virtual machines on the
+bastion node and managed through the Qemu-KVM socket on that node.
+
+If you would like to see this provider support additional nodes, please open an
+issue.

docs/openwrt.md

@@ -0,0 +1,59 @@
+# OpenWRT DNS and DHCP Provider
+
+[OpenWRT](https://openwrt.org/) is an Open Source router firmware that is
+flexible and powerful. It can be very useful for building low-power,
+small-foorprint clusters because of its ability to run on very small gear.
+OpenWRT is capable of providing DNS, DHCP, routing, and firewall services to a
+Faros cluster.
+
+These instructions assume that the router's WAN connection, admin password, and
+WiFi settings have already been configured properly. It also never hurts to
+update all the firmware to the latest version.
+
+## General Configuration
+Faros will connect to your OpenWRT router via SSH to manage cluster
+configuration. To allow this to happen, you must upload your public SSH key to
+the OpenWRT router. You can do this in the LuCi web interface by navigating to
+`System -> Administration` and copy-pasting the public key to the text box
+labeled `SSH-Keys`.
+
+Faros will require a number of packages to be installed on the OpenWRT router.
+You can install packages from the LuCi interface by navigating to `System ->
+Software` and clicking the `Update lists` button. Then you can search for
+packages by typing their name in the `Filter` box. When you find the package
+you would like to install, click the `Install` button to the right.
+
+The following packages are required:
+* ca-certificates
+* ca-bundle
+* python-light
+* python-logging
+* python-codecs
+* python-crypto
+* openssh-sftp-server (technically optional, but recommended)
+* openssh-sftp-client (technically optional, but recommended)
+
+## DNS and DHCP Configuration
+
+OpenWRT uses Dnsmasq to provide DNS and DHCP services. This means that they are
+configured together.
+
+### DNS Search Domain
+
+To configure this setting, navigate to `Network -> DHCP and DNS` and edit the
+value called `Network Domain`.
+
+This must be of the format `CLUSTER_NAME.CLUSTER_DOMAIN`. For the examples in
+this documentation, the cluster name is `beacon01` and the domain is
+`faros.site`. This means the Local Domain is set to `beacon01.faros.site`.
+
+### Network Subnet and DHCP Pool
+
+The Faros installer does not have an opinion on the subnet address. However,
+you will require a pool of IP addresses that live outside of the DHCP pool but
+inside the subnet. To configure this, navigate to `Network -> Interfaces` and
+click the `Edit` button next to `LAN`.
+
+For the examples in this documentation, we will use 192.168.1 as the IPv4
+Address, 255.255.255.0 as the IPv4 netmask, and the DHCP server will Start at
+100.

docs/prereqs.md

@@ -0,0 +1,93 @@
+# Faros Installation
+
+## Prerequisites
+
+Before cluster configuration and deployment, you must have basic networking
+available for your network. This includes layer 3 routing, egress firewall, DNS
+services, and DHCP services. You must have an SSH key to use for the cluster.
+Finally, each server that is used must have out-of-band management configure.
+
+### Generate SSH Key
+
+From a Linux or Mac machine, use the following command to create an SSH key:
+
+```bash
+ssh-keygen -f id_cluster -N ""
+```
+
+This will generate public (id_cluster.pub) and private (id_cluster) key files
+for use during the install.
+
+### DHCP Configuration
+
+The following DHCP providers are supported:
+
+1. [OpenWRT](./openwrt.md)
+
+### DNS Configuration
+
+The following DNS providers are supported:
+
+1. [OpenWRT](./openwrt.md)
+
+### Out of Band Management
+
+The following management providers are supported:
+
+1. [iLO](./ilo.md)
+1. [KVM](./kvm.md)
+
+With the exception of the bootstrap node and the bastion app node, all machines
+in the cluster must use the same management interface. All machines must also
+use the same credentials on their management interfaces.
+
+### Machine BIOS Setup
+
+Faros is not impacted by much of the BIOS configurations on nodes. However, the
+system must be configured for BIOS boot, not UEFI. The internal hard drive
+should be the only boot device. If a RAID card is present in the machine,
+hardware RAID may also be configured.
+
+## Bastion Host
+
+The Faros Bastion host has many purposes. Primarily, it is the node from which
+you will create and control your cluster. This node will host a PXE boot (tftp)
+server, a web server (http), the cluster load balancer (haproxy), a virtual
+bootstrap server, and a cluster control interface (cockpit).
+
+The bastion node should be a physical node in your cluster. To prepare it,
+simply install RHEL or CentOS 8. EL7 should work as well, but it is not tested.
+You may use the default install, but you should set a static IP address during
+the install process. The IP address should be in your subnet but outside of
+the DHCP range and outside the range you will give to Faros. The hostname for
+this node should be `bastion.CLUSTER_NAME.CLUSTER_DOMAIN`. For example purposes,
+this documentation will use `bastion.beacon01.faros.site`. The user created
+during the install process must be made a system administrator.
+
+When the operating system install is complete, copy to the server the SSH keys
+that were generated earlier. This can be accomplished with the following
+commands on a Linux or Mac computer. For simplicity, simply place the SSH keys
+into the user's home directory.
+
+```bash
+ssh-copy-id -i id_cluster.pub USER@BASTION_IP
+scp id_cluster* USER@BASTION_IP:
+```
+
+If you are using Red Hat, subscribe to RHSM. For all operating systems: apply
+all available patches and reboot.
+
+Once the server has rebooted, connect to it and run the following command to
+install Faros.
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/project-faros/cluster-manager/master/bin/bootstrap-bastion.sh)"
+```
+
+The installer will first have you log in with the user's
+password to allow root access. Then, the installer will prompt for the path to
+the ssh keys. If you followed the examples in this documentation, they will be:
+
+- **Public Key:** ~/id_cluster.pub
+- **Private Key:** ~/id_cluster
+