Update documentation

[ci skip]

Author: Anthony Emengo

FAQ.md

@@ -0,0 +1,52 @@
+# FAQ
+
+## Can I configure the working directory?
+
+Yes you can, by exporting the environment variable `CFDEV_HOME` to your custom location before invoking CF Dev. All 
+state used by the plugin will be contained in the that directory. By default, the working directory is set to `~/.cfdev`.
+
+## `cf dev start` failed while deploying. It got stuck at _Progress x of 15 (55m10s)_.
+
+Running an entire PAAS on one workstation is an ambitious endeavor and the workstation has to be performant enough
+for the task. The most common insufficiency is the disk speed due to CF Dev being such an disk I/O intensive process.
+As mentioned in our [recommended requirements](https://github.com/cloudfoundry-incubator/cfdev#recommended-system-requirements).
+No less than flash storage (i.e. SSDs) is recommended for use with CF Dev. If your workstation has an HDD, this is the most
+likely cause of issue.
+
+We are always working towards reducing the footprint of CF Dev.
+
+## The only service available is mysql. How do I get access to pivotal apps manager, rabbitmq, redis, spring-cloud-services?
+
+A separate asset is needed. You can download the correct asset for your platform at
+[https://network.pivotal.io/products/pcfdev](https://network.pivotal.io/products/pcfdev).
+Then you perform a start with the downloaded asset specified via the `-f` flag, like so: `cf dev start -f ./pcfdev-v*.tgz`
+
+## Why are the assets to download so big?
+
+Under the hood, CF Dev is performing a [BOSH](https://bosh.io/docs/) deploy - but into containers rather than full-sized VMs.
+The significant bulk of what is packaged are those same assets that are needed for a deployment into a cloud provider. 
+
+## How do I inspect debugging information?
+
+Logging information is written to various files in the `log` directory of the CF Dev working directory. If the working directory has not
+been reconfigured, it can be found in: `~/.cfdev/log`.
+
+## What ports are available for use with TCP routing?
+
+`1024 - 1049`.
+
+## Is there a command to make more ports available?
+
+No. Exposing ports to the VM can currently only be specified during the build process of the virtual machine.
+
+## What is the pcfdev repository? https://github.com/pivotal-cf/pcfdev
+
+pcfdev is our previous, _deprecated_ offering that satisfied the same use case: standing up a local Cloud Foundry environment.
+We have chosen to move away from it because its architecture made maintenance incredibly difficult. Engineers are no longer allocated to it
+and CF Dev is meant to supplant it completely. In addition to offering more recent version of CF internals and features, CF Dev
+make use of native hypervisors which offers better performance.
+
+## Copyright
+
+See [LICENSE](LICENSE) for details.
+Copyright (c) 2018 [Pivotal Software, Inc](http://www.pivotal.io/).

README.md

@@ -1,80 +1,75 @@
-![ci.cfdev.sh](http://ci.cfdev.sh/api/v1/teams/main/pipelines/cfdev/jobs/build-cli/badge)
-
-```
-$ cf dev start
-Downloading Resources...
-Starting VPNKit ...
-Starting the VM...
-Deploying the BOSH Director...
-Deploying CF...
-
-  ██████╗███████╗██████╗ ███████╗██╗   ██╗
- ██╔════╝██╔════╝██╔══██╗██╔════╝██║   ██║
- ██║     █████╗  ██║  ██║█████╗  ██║   ██║
- ██║     ██╔══╝  ██║  ██║██╔══╝  ╚██╗ ██╔╝
- ╚██████╗██║     ██████╔╝███████╗ ╚████╔╝
-  ╚═════╝╚═╝     ╚═════╝ ╚══════╝  ╚═══╝
-             is now running!
+# CF Dev
 
-To begin using CF Dev, please run:
-    cf login -a https://api.dev.cfdev.sh --skip-ssl-validation
-
-Admin user => Email: admin / Password: admin
-Regular user => Email: user / Password: pass
+![ci.cfdev.sh](http://ci.cfdev.sh/api/v1/teams/main/pipelines/cfdev/jobs/build-cli/badge)
 
-```
+![start](./docs/start.png)
 
 ***********************************
 
-CF Dev is a new distribution of Cloud Foundry designed to run on a developer’s laptop or workstation using native hypervisors and a fully functional BOSH Director. CF Dev gives application developers the full Cloud Foundry experience in a lightweight, easy to install package. CF Dev is intended for application developers who wish to develop and debug their application locally on a full-featured Cloud Foundry. CF Dev is also an excellent getting started environment for developers interested in learning and exploring Cloud Foundry.
-
-## Prerequisites
-
-* [CF CLI](https://github.com/cloudfoundry/cli)
-* Internet connection (or Dnsmasq or Acrylic) required for wildcard DNS resolution
-* Please note CF Dev only supports MacOS and Windows 10 at this time
+CF Dev is a distribution of Cloud Foundry designed to run on a developer’s laptop or workstation using native hypervisors and a fully functional BOSH Director. CF Dev gives application developers the full Cloud Foundry experience in a lightweight, easy to install package. CF Dev is intended for application developers who wish to develop and debug their application locally on a full-featured Cloud Foundry. CF Dev is also an excellent getting started environment for developers interested in learning and exploring Cloud Foundry.
 
 ## Recommended system requirements
-* Operating system: MacOS 10.12+/Windows 10+
+
+* Operating system: MacOS 10.12+/Windows 10+/Linux
 * CPU: 2 Cores or more
 * Memory: 8 Gigabytes _available memory_
 * Disk: 60GB _flash_ storage
+* Dependencies: _QEMU_ and _Libvirt_ for Linux
+  * Ubuntu: `sudo apt install qemu-kvm libvirt-bin libvirt-doc`
 
-## Install 
-1. _(if needed)_ Uninstall your existing PCF Dev plugin if it is installed `cf uninstall-plugin pcfdev`
-1. Install the CF Dev plugin `cf install-plugin -r CF-Community "cfdev"`.
-
-## Start
-Run CF Dev `cf dev start`.
+## Getting Started
 
+### Install
 
-## Run BOSH with CF Dev
-1. _(if needed)_ Install [BOSH CLI v2](https://bosh.io/docs/cli-v2.html).
-1. Set environment variables to point BOSH to your CF Dev instance `eval "$(cf dev bosh env)"`.
-1. Run BOSH `bosh <command you want to run>`.
+1. Install the [CF CLI](https://github.com/cloudfoundry/cli)
+1. Install the CF Dev plugin `cf install-plugin -r CF-Community cfdev`
+1. Run CF Dev `cf dev start`
 
-## Project Backlog
+### Use BOSH
 
-Follow the CF Dev team's progress [here](https://github.com/cloudfoundry-incubator/cfdev/projects/1).  This backlog contains a prioritized list of features and bugs the CF Dev team is working on.  Check the project board for the latest updates on features and when they will be released.
+1. Install [BOSH CLI v2](https://bosh.io/docs/cli-v2.html).
+1. Set environment variables to point BOSH to your CF Dev instance
+	* Unix: `eval "$(cf dev bosh env)"`
+	* Windows: `cf dev bosh env | Invoke-Expression`
+1. Run BOSH `bosh <command you want to run>`
 
-## Uninstall
+### Uninstall
 
 To stop CF Dev run `cf dev stop`. This will completely stop and destroy the CF Dev VM.
 
 To uninstall the CF Dev cf CLI plugin run `cf uninstall-plugin cfdev`.
 
+To reclaim consumed disk space, delete your CF Dev directory:
+
+* Unix: `rm -rf ~/.cfdev`
+* Windows `Remove-Item -Recurse ~/.cfdev`
+
+## Features
+
+* **Insecure Docker Registries:** Invoke `cf dev start` with the `-r` flag to specify a comma separated list of insecure docker registries that will be
+   available for use during the `cf push` process.
+
+* **Proxy Support:** Export `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` environment variables during your terminal session to have them respected during the start process and _within_
+  your CF Dev virtual machine. _Not yet supported on the Linux platform_.
+
+* **Host Access:** Access the host machine from within application containers using the `host.cfdev.sh` domain name.
+
+* **TCP Routing:** You can learn more about TCP Routing from within the Cloud Foundry platform [here](https://github.com/cloudfoundry/routing-release#post-deploy-steps).
+
 ## Telemetry
 
 Here on the CF Dev team, we use telemetry to help us understand how our tool is being used.  We value our users privacy, therefore all telemetry is completely anonymous. There is no way for anyone with the telemetry to identify who is using the CF Dev tool.  In an effort to make our data as transparent as possible, we will be publishing aggregated anonymous usage data to this page periodically to help our user community understand how the tool is being used. 
 
-In addition to making this data completely anonymous, we require users to opt-in to allowing us to collect telemetry from their tool. Upon running `$ cf dev start` for the first time, we will prompt the user to opt-in to capturing analytics.  Any time after that you can turn on/off telemetry by running `$ cf dev telemetry --on/off`
+In addition to making this data completely anonymous, we require users to opt-in to allowing us to collect telemetry from their tool. Upon running `$ cf dev start` for the first time, we will prompt the user to opt-in to capturing analytics.  Any time after that you can turn on/off telemetry by running `$ cf dev telemetry --on/off`.
 
 You can learn more about what we do with telemetry [here](https://github.com/cloudfoundry-incubator/cfdev/wiki/Telemetry)
 
-## TCP Ports
+## Community
+
+* [#cfdev on Cloudfoundry Slack](https://cloudfoundry.slack.com)
 
-The tcp port range has been limited to 1024 - 1049 to prevent reaching file descriptor limits on some systems.
+* [Contributing](CONTRIBUTING.md)
 
-## Contributing
+## FAQ
 
-If you are interested in contributing to CF Dev, please refer to the [contributing guidelines](CONTRIBUTING.md).
+See [FAQ](FAQ.md).