Merge pull request #289 from garden-io/allthedocs

Documentation Overhaul

docs/README.md

@@ -1,17 +1,22 @@
 # Table of Contents
 
-* [Read Me](../README.md)
-* [Introduction](./introduction/README.md)
-  * [Getting Started](./introduction/getting-started.md)
-  * [Motivation](./introduction/motivation.md)
-* [Guides](./guides/README.md)
-  * [Configuration](./guides/configuration.md)
-  * [Using Garden with Minikube](./guides/minikube.md)
-  * [Remote Kubernetes](./guides/remote-kubernetes.md)
-  * [Glossary](./guides/glossary.md)
+* [Home](./home.md)
+* [Basics](./basics/README.md)
+  * [Installation](./basics/installation.md)
+  * [Quick Start](./basics/quick-start.md)
+  * [Concepts](./basics/concepts.md)
+* [Using Garden](./using-garden/README.md)
+  * [Features and usage](./using-garden/features-and-usage.md)
+  * [Configuration files](./using-garden/configuration-files.md)
+  * [Remote Clusters](./using-garden/remote-clusters.md)
+  * [Hot Reload](./using-garden/hot-reload.md)
+* [Example projects](./examples/README.md)
+  * [Hello world](./examples/hello-world.md)
+  * [Simple project](./examples/simple-project.md)
+  * [TLS project](./examples/tls-project.md)
+  * [Remote sources project](./examples/remote-sources.md)
 * [Reference](./reference/README.md)
-  * [Commands](./reference/commands.md)
-  * [Config](./reference/config.md)
-* [Examples](./examples/README.md)
-  * [Simple Project](./examples/simple-project.md)
-* [FAQs](./faqs.md)
+  * [Glossary](./reference/glossary.md)
+  * [Commands Reference](./reference/command-reference.md)
+  * [Config Files Reference](./reference/config-files-reference.md)
+* [FAQs](./faqs.md)

docs/basics/README.md

@@ -0,0 +1,11 @@
+# Basics
+
+The following articles cover the basics of installing and using Garden:
+
+  * Installation instructions for your platform: [Installation](./basics/installation.md).
+  * A very brief guide on the main commands you should be familiar with, and an example project to test them in: [Quick Start](./basics/quick-start.md).
+  * An overview of the framework's main concepts, to help get you started using Garden with your own projects: [Concepts](./basics/concepts.md).
+
+If you're already familiar with the basics, feel free to move on to the next chapter: [Using Garden](./using-garden/README.md). 
+
+Or dive right in by exploring our [Guides](./guides/README.md) and [Example projects](./examples/README.md).

docs/basics/concepts.md

@@ -0,0 +1,43 @@
+# How Garden works
+
+The mechanics of how Garden works are fundamentally straightforward:
+
+*Providers* implement the specifics of how to e.g. build, deploy or test a given type of module. For example, Garden includes providers for local Kubernetes, remote Kubernetes and OpenFAAS serverless functions.
+
+Garden projects, in turn, consist of *modules*. Each module in a project has a type (e.g. container, OpenFaaS), and the type then indicates which provider should deal with a given module when it comes to building, deploying, and testing it.
+
+This information is conveyed through [configuration files](../using-garden/configuration-files.md), usually in YAML format, which live in the project root for project-wide settings, and in each module's directory for module-specific settings.
+
+# Projects vs. modules vs. services
+
+Garden has three main organizational units: projects, modules, and services.
+
+A project is the top-level unit, and it contains all the others. You can think of a project as a context: there aren't any hard rules or limitations as to how big or small your project should be, but it's advisable to keep all elements belonging to the same context inside the same project.
+
+Modules can be thought of as the individual units of the build process. So, for example, every container and every serverless function should, as a rule of thumb, have its own module.
+
+Lastly, services are units of deployment, or instances. They're *usually* one service per module, but not necessarily: you might have, for example, two instances of the same container working on different queues or data streams.
+
+To sum it all up: A project consists of one or more modules, and each module may deploy zero or more services.
+
+# The build → test → deploy sequence
+
+The dev command (called with garden dev) combines the `build`, `deploy` and `test` commands, and is a convenient way to get your development environment up and running: It builds, deploys and tests your modules and services as needed when their source code changes.
+
+The `build`, `deploy` and `test` commands, and by extension the `dev` command, are all dependency-aware. They will always build, test, and deploy modules in the right order so that all dependencies are respected.
+
+# Hot reload
+
+Hot reloading means updating a running service when its source files are changed, without re-building and re-deploying the whole thing. 
+
+In the case of a container, for example, we would not destroy the container, build a new version, and then re-deploy. Instead, we would update the changed files without stopping the running container, updating the running application more quickly.
+
+Hot reloading is disabled by default. To enable hot reloading for a set of services, use the `--hot-reload` option with the names of those services when calling the deploy or dev commands.
+
+# Projects with multiple and/or remote repositories
+
+Garden projects may include sources hosted in any number of local or remote repositories. Remote sources may later be linked to local directories for convenience or to work offline. 
+
+You could have, for example, a project that has one local module, one remote module from an external source, and a second external source that contains two more modules.
+
+For specifics see our [Remote sources project](../examples/remote-sources.md) example.

docs/basics/installation.md

@@ -0,0 +1,161 @@
+## Installation
+
+This guide will walk you through setting up the Garden framework.
+
+Please follow the guide for your operating system:
+
+* [macOS](#macos)
+* [Windows](#windows)
+* [Linux (Manual Installation)](#linux-manual-installation)
+
+And if you decide to use Minikube, please see our [Minikube Instructions](#minikube-instructions) further down in this
+document.
+
+### macOS
+
+For Mac, we recommend the following steps to install Garden. You can also follow the manual installation
+steps below if you prefer.
+
+#### Step 1: Install Homebrew
+
+If you haven't already set up homebrew, please follow [their instructions](https://brew.sh/) to set it up.
+
+#### Step 2: Docker and local Kubernetes
+
+To install Docker, Kubernetes and kubectl, we strongly recommend Docker for Mac.
+
+_Note: If you have an older version installed, you may need to update it in
+order to enable Kubernetes support._
+
+Once installed, open Docker for Mac's preferences, go to the Kubernetes section,
+tick `Enable Kubernetes` and save. Please refer to their
+[installation guide](https://docs.docker.com/engine/installation/) for details.
+
+Alternatively, you can use Minikube. We generally find it less stable and more hassle to
+configure and use, but we do fully support it on Mac. Please look at the
+[Minikube Instructions](#minikube-instructions) section for details.
+
+#### Step 3: Install `garden-cli`
+
+We have a Homebrew tap and package that you can use to easily install `garden-cli` and all dependencies:
+
+```sh
+brew tap garden-io/garden
+brew install garden-cli
+```
+
+To later upgrade to the newest version, simply run `brew update` and then `brew upgrade garden-cli`.
+
+### Windows
+
+You can run Garden on Windows 10 Pro or Enterprise editions (the Home edition unfortunately does not work because it does not include support for virtualization).
+
+To install the Garden CLI, please use our automated installation script, which will
+check for dependencies, install missing dependencies if needed, and finally install the Garden CLI.
+
+To run the script, open PowerShell as an Administrator and run:
+
+```PowerShell
+Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/garden-io/garden/master/support/install.ps1'))
+```
+
+The things the script will check for are the following:
+
+* The [Chocolatey](https://chocolatey.org) package manager. The script installs it automatically if necessary.
+* _git_, _rsync_ and _Docker for Windows_. The script will install or upgrade those via Chocolatey.
+* Whether you have Hyper-V enabled. This is required for _Docker for Windows_. If you do not already have it enabled,
+  the script will enable it but you will need to restart your computer before starting Docker for Windows.
+* Whether you have Kubernetes enabled in your _Docker for Windows_ installation.
+
+To later upgrade to the newest version, simply re-run the above script.
+
+### Linux (manual installation)
+
+You need the following dependencies on your local machine to use Garden:
+
+* [Docker](https://docs.docker.com/)
+* Git
+* rsync
+* Local installation of Kubernetes and kubectl
+
+#### Step 1: Docker
+
+To install Docker, please follow the instructions in the [official documentation](https://docs.docker.com/install/).
+
+#### Step 2: Local Kubernetes
+
+For local Kubernetes, you can use [Minikube](https://github.com/kubernetes/minikube). Please see our
+[Minikube Instructions](#minikube-instructions).
+
+#### Step 3: Install other dependencies
+
+Use your preferred method or package manager to install `git` and `rsync`.
+
+#### Step 4: Install `garden-cli`
+
+Once you have the dependencies set up, install the Garden CLI via `npm`:
+
+```sh
+npm install -g garden-cli
+```
+
+To later upgrade to the newest version, run `npm install -g -U garden-cli`.
+
+# Minikube Instructions
+
+Garden can be used with [Minikube](https://github.com/kubernetes/minikube) on supported platforms.
+
+_NOTE: We highly recommend using Docker for Mac and Docker for Windows, on macOS and Windows respectively._
+
+## Installation
+
+For Minikube installation instructions, please see the [official guide](https://github.com/kubernetes/minikube#installation).
+
+You'll likely also need to install a driver to run the Minikube VM. Please follow the
+[instructions here](https://github.com/kubernetes/minikube/blob/master/docs/drivers.md)
+and note the name of the driver you use. The driver you choose will likely vary depending on your
+OS/platform. We recommend [hyperkit](https://github.com/kubernetes/minikube/blob/master/docs/drivers.md#hyperkit-driver)
+for macOS and [kvm2](https://github.com/kubernetes/minikube/blob/master/docs/drivers.md#kvm2-driver) on most Linux
+distributions.
+
+Once Minikube and the appropriate driver for your OS are installed, you can start Minikube by running:
+
+```sh
+minikube start --vm-driver=<your vm driver>  # e.g. hyperkit on macOS
+```
+
+You'll also need to have Docker (for macOS, we recommend [Docker for Mac](https://docs.docker.com/engine/installation/))
+and [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) installed.
+
+## Usage
+
+The `local-kubernetes` plugin attempts to automatically detect if it is installed and set the appropriate context
+for connecting to the local Kubernetes instance. In most cases you should not have to update your `garden.yml`,
+since it uses the `local-kubernetes` plugin by default, but you can configure it explicitly in your project-level
+`garden.yml` as follows:
+
+```yaml
+project:
+  environments:
+    - name: local
+      providers:
+        - name: local-kubernetes
+          context: minikube
+```
+
+If you happen to have installed both Minikube and a version of Docker for Mac with Kubernetes support enabled,
+`garden` will choose whichever one is configured as the current context in your `kubectl` configuration, and if neither
+is set as the current context, Docker for Mac is preferred by default.
+
+(If you're not yet familiar with Garden configuration files, see: [Configuration files](../using-garden/configuration-files.md))
+
+## Hostname
+
+Garden needs the Kubernetes instance to have a hostname. By default Garden will use `<minikube-ip>.nip.io`. If you'd
+like to use a custom hostname, you can specify it via the `ingressHostname` in the `local-kubernetes` provider config
+(see above).
+
+## Anything else?
+
+Once the above is set up, the `local-kubernetes` plugin will automatically configure everything else Garden needs to
+work. The built-in nginx ingress controller will be automatically enabled and used to route requests to services.

docs/basics/quick-start.md

@@ -0,0 +1,58 @@
+# Getting Started
+
+This guide will walk you through setting up the Garden framework. It assumes you already have Garden installed. If you don't, please check out our [installation guide](./installation.md).
+
+## Using the CLI
+
+With the CLI installed, we can now try out a few commands using the [Simple Project](../examples/simple-project.md) from our [example projects](../examples/README.md). The example project consists of a couple of simple modules, each defining one service.
+
+_Note: Check if Kubernetes is running with `kubectl version`. You should see both a `Client Version` and a `Server Version` in the response. If not, please start it up before proceeding._
+
+Clone the repo and change into the `simple-project`  directory:
+
+```sh
+$ git clone https://github.com/garden-io/garden.git
+$ cd garden/examples/simple-project
+```
+
+First, let's check the environment status by running the following from the project root:
+
+```sh
+$ garden get status
+```
+
+The response tells us how the environment is configured and the status of the providers. Next, we'll build our modules with:
+
+```sh
+$ garden build
+```
+
+This builds Docker images for `go-service` and `node-service` respectively. Next, we'll deploy the services with:
+
+```sh
+$ garden deploy
+```
+
+And that's it! The `garden build` step above is actually unnecessary (only included here for clarity), since `garden deploy` will also rebuild modules as needed. The services are now running on the Garden framework. You can see for yourself by querying the `/hello` endpoint of `go-service`'s running container:
+
+```sh
+$ garden call go-service/hello-go
+```
+
+To run tests for all modules:
+
+```sh
+$ garden test
+```
+
+And if you prefer an interactive terminal that watches your project for changes and re-builds, re-deploys, and re-tests automatically, try:
+
+```sh
+$ garden dev
+```
+
+Go ahead, leave it running and change one of the files in the project, then watch it re-build.
+
+That's it for now. Check out our [Using Garden](../using-garden/README.md) section for other features like hot reload, remote clusters, integration tests, and lots more. 
+
+To see how a Garden project is configured from scratch check, out the [Simple Project](../examples/simple-project.md) guide for a more in-depth presentation.

docs/examples/README.md

@@ -1,6 +1,17 @@
-# Examples
+# Example projects
 
-The source code for the examples in this section can be found in our Github repository under the
-[examples directory](https://github.com/garden-io/garden/tree/master/examples).
+## [Hello world](./hello-world.md)
 
-* [Simple Project](./simple-project.md)
+In this project we see in practice the basics of configuring dependencies, defining ports and endpoints, and setting up tests.
+
+## [Simple project](./simple-project.md)
+
+Here we see how to "gardenify" a pre-existing project, creating a project config and the individual module configs for every part.
+
+## [TLS project](./tls-project.md)
+
+This is an example project of how to set up TLS using the `mkcert` tool.
+
+## [Remote sources project](./remote-sources.md)
+
+This project demonstrates how to use multiple sources and repositories together into the same project. Although in this project we're using _remote_ sources, the same applies to using multiple _local_ repositories.