Merge pull request #138 from garden-io/docs-overhaul

Docs overhaul

.gitbook.yaml

@@ -0,0 +1,3 @@
+structure:
+  readme: README.md
+  summary: docs/README.md

README.md

@@ -16,13 +16,32 @@ All that said, Garden can already be highly useful if the following applies to y
 
 * **You're deploying to (or transitioning to) Kubernetes.**
 * **You develop on Mac or Linux.**
-* **You work mostly with containers _today_ (but perhaps plan on adopting serverless platforms in the future).**
+* **You work mostly with containers** _**today**_ _\(but perhaps plan on adopting serverless platforms in the future\)._
+* **You keep all your services in a single repository** _(multi-repo support coming soon!)._
 * **You really don't want to spend your precious hours building your own developer tooling!**
 
 If that sounds right for you, please give it a go and don't hesitate to report issues or come right over 
 to our [Gitter](https://gitter.im/garden-io/Lobby#) for a chat!
 
 
+## Features
+
+With Garden, you can...
+
+* Configure and deploy a fleet of services to a local Kubernetes cluster using simple declarations.
+* Use an integrated framework for building, testing and deploying services.
+* Easily run end-to-end tests across multiple services without waiting for a slow CI pipeline.
+* Automatically build, deploy and/or test when your code changes, using the `--watch` flag or the `garden dev` command.
+* Manage build and runtime dependencies across all your services.
+* Leverage a suite of commands and helpers to facilitate developing and running your stack.
+* _Write code the way you want, and run your production system however suits you! Garden does not impose any new 
+libraries or languages aside from the config files._ 
+
+Garden is also designed to be pluggable and modular, with Kubernetes being just one plugin (albeit an important one). 
+Over time we will add native support for a variety of platforms, including AWS (Lambda, ECS, Fargate and more), 
+GCP, Heroku, OpenFaaS... and the list will continue growing.
+
+
 ## Setup
 
 ### Dependencies

docs/README.md

@@ -0,0 +1,10 @@
+# Table of Contents
+
+* [Read Me](../README.md)
+* [Getting Started](./getting-started/README.md)
+* [Guides](./guides/README.md)
+  * [Using Garden with Minikube](./guides/minikube.md)
+  * [Remote Kubernetes](./guides/remote-kubernetes.md)
+* [Reference](./reference/README.md)
+  * [Commands](./reference/commands.md)
+

docs/getting-started/README.md

@@ -0,0 +1,92 @@
+# Getting Started
+
+This guide will walk you through setting up the Garden framework. 
+
+## Install dependencies  
+
+You need the following dependencies on your local machine to use Garden:
+* Node.js >= 8.x
+* [Docker](https://docs.docker.com/)
+* Git
+* rsync
+* [Watchman](https://facebook.github.io/watchman/docs/install.html)
+* Local installation of Kubernetes
+
+### OSX
+
+#### Step 1: Docker and local Kubernetes
+To install Docker and Kubernetes, we recommend [Docker for Mac (edge version)](https://docs.docker.com/engine/installation/).
+
+_Note: you need to install the _edge version_ of Docker for Mac in 
+order to enable Kubernetes support._
+
+Once installed, open the 
+Docker preferences, go to the Kubernetes section, tick `Enable Kubernetes` and 
+save.
+
+Alternatively, you can use [Minikube](../guides/minikube.md) on any supported platform.
+
+#### Step 2: Other dependencies
+For installing the other dependencies, we recommend using Homebrew.
+
+### Linux
+
+#### Step 1: Docker
+To install Docker, please follow the instructions in the [official documentation](https://docs.docker.com/install/linux/docker-ce/ubuntu/).
+
+#### Step 2: Local Kubernetes
+For local Kubernetes, you can use Minikube. Please see the 
+[official installation guide](https://github.com/kubernetes/minikube#installation) for instructions.
+
+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#hyperkit-driver),
+and note the name of the driver.
+
+Once Minikube and the appropriate driver for your OS is installed, you can start it by running:
+
+    minikube start --vm-driver=<your vm driver>  # e.g. hyperkit on macOS
+
+Finally, you will need to configure a [kubectl context](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration)
+to point to your local instance.
+
+<!-- More detailed docs for configuring kubectl context -->
+
+Check out our [Minikube guide](../guides/minikube.md) for further information on using Garden with Minikube.
+
+#### Step 3: Other dependencies
+Other dependencies can be installed with the package manager of your choice
+
+## Install the Garden CLI
+
+Once you have the dependencies set up, simply run:
+
+    npm install -g garden-cli
+
+## Using the CLI
+
+With the CLI installed, we can now try out a few commands using the [hello-world](https://github.com/garden-io/garden/tree/master/examples/hello-world) example from this repository. The example consists of a container service that runs an [Express](http://expressjs.com/) app, a serverless function, and an npm library package.
+
+_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 `examples/hello-world`  directory:
+
+    git clone https://github.com/garden-io/garden.git &&
+    cd garden/examples/hello-world
+
+First, let's check the environment status by running the following from the project root:
+
+    garden status
+
+The response tells us how the environment is configured and the status of the providers. Next, we'll deploy the services with:
+
+    garden deploy
+
+And that's it! The services are now running on the Garden framework. You can see for yourself by querying the `/hello` endpoint of the container with:
+
+    garden call hello-container/hello
+
+Check out our [Commands](../guides/commands.md) guide for other features like auto-reload, streaming service logs, running tests, and lots more. 
+
+## What's next
+
+Kick the tires of our [examples](https://github.com/garden-io/garden/tree/master/examples/hello-world) to get a feel for how projects are configured, or head to the [Guides](../guides/README.md) section for a deep dive into the Garden framework.

docs/guides/README.md

@@ -0,0 +1,6 @@
+# Guides 
+
+* [Using Garden with Minikube](./minikube.md)
+* [Remote Kubernetes](./remote-kubernetes.md)
+
+

docs/guides/configuration.md

@@ -0,0 +1,243 @@
+## Configuration
+
+Garden is configured via `garden.yml` configuration files.
+
+The [project-wide](#project) `garden.yml` file should be located in the top-level directory of the project's Git 
+repository.
+
+In addition, each of the project's [modules](../other/glossary#module)' `garden.yml` should be located in that module's 
+top-level 
+directory.
+
+Currently, Garden projects assume that all their modules are rooted in subdirectories of the same Git repository.
+In a future release, this mono-repo structure will be made optional.
+
+To get started, create a `garden.yml` file in the top-level directory of your repository, and a `garden.yml` file 
+in the top-level directory of each of the modules you'd like do define for your project.
+
+To decide how to split your project up into modules, it's useful to consider what parts of it are built as a single
+step, and what the dependency relationships are between your build steps. For example, each container and each
+serverless function should be represented by its own module
+
+Then, you can configure each module's endpoints via the [`services` directive](#services) in its `garden.yml`.
+
+Below, we'll be using examples from the
+[hello-world example project](https://github.com/garden-io/garden/tree/528b141717f718ebe304d2ebde87b85d0c6c5e50/examples/hello-world).
+
+### Project Configuration
+[Github link](https://github.com/garden-io/garden/blob/528b141717f718ebe304d2ebde87b85d0c6c5e50/examples/hello-world/garden.yml)
+```yaml
+# examples/hello-world/garden.yml
+project:
+  name: hello-world
+  global:
+    providers:
+      - name: container
+      - name: npm-package
+    variables:
+      my-variable: hello-variable
+  environments:
+    - name: local
+      providers:
+        - name: local-kubernetes
+        - name: local-google-cloud-functions
+    - name: dev
+      providers:
+        - name: google-app-engine
+        - name: google-cloud-functions
+          default-project: garden-hello-world
+```
+The project-wide `garden.yml` defines the project's name, the default providers used for each
+[plugin](../other/glossary#plugin) the project requires (via the `global` directive), and
+[environment](../other/glossary#environment)-specific provider overrides as is appropriate for each of the project's
+configured environments (`local` and `dev` under the `environments` directive above).
+
+Here, project-wide configuration variables can also be specified (global, and/or environment-specific). These are 
+then available for interpolation in any string scalar value in any module's `garden.yml`.
+
+ For example, assuming the above project configuration, `"foo-${variables.my-variable}-bar"` would evaluate to 
+ `"foo-hello-variable-bar"` when used as a scalar string value in a module's `garden.yml`.
+
+### Module Configuration
+Below, we'll use the module configurations of `hello-function` and `hello-container` from the 
+[hello-world example project](https://github.com/garden-io/garden/tree/528b141717f718ebe304d2ebde87b85d0c6c5e50/examples/hello-world)
+as examples to illustrate some of the primary module-level configuration options.
+
+The following is a snippet from [`hello-function`'s module config](#hello-function-module-configuration):
+```yaml
+module:
+  description: Hello world serverless function
+  type: google-cloud-function
+  name: hello-function
+  ...
+  build:
+    dependencies:
+      - name: hello-npm-package
+        copy:
+          - source: "./"
+            target: libraries/hello-npm-package/
+```
+
+#### name
+The module's name, used e.g. when referring to it from another module's configuration as a
+[build dependency](#build-configuration), or when building specific modules with `garden build`.
+
+Note that module names must be unique within a given project. An error will be thrown in any Garden CLI command if two
+modules use the same name.
+
+#### type
+A [module](../other/glossary.md#module)'s `type` specifies its plugin type. Garden interprets this according to the 
+active environment's configured provider for the specified plugin type.
+
+For example,
+[`hello-container`](#hello-container-module-configuration)'s `type` is set to `container`, which the
+[project configuration](#project-configuration) above interprets as `local-kubernetes` (a Docker container managed 
+via a local Kubernetes installation), assuming that the `local` environment is being used.
+
+#### build
+A module's build configuration is specified via the `build` directive.
+
+Under `build`, the `command` subdirective sets the CLI command run during builds. A module's build command is executed 
+with its working directory set to a copy of the module's top-level directory, located at
+`[project-root]/.garden/build/[module-name]`. This internal directory is referred to as the module's
+[build directory](../other/glossary.md#build-directory).
+
+The `.garden` directory should not be modified by users, since this may lead to unexpected errors when the Garden CLI
+tools are used in the project.
+
+##### Build Dependencies
+The `dependencies` subdirective lists the module's build dependencies. `name` is the required module's name, and 
+`copy` indicates what files/folders, if any, should be copied from the required module's build directory to the 
+module in question after the required module is built (`source`), and where they should be copied (`target).
+
+#### Services
+The following is a snippet from [`hello-container's`'s module config](#hello-container-module-configuration):
+```yaml
+module:
+  description: Hello world container service
+  type: container
+  services:
+    - name: hello-container
+      command: [npm, start]
+      ports:
+        - name: http
+          containerPort: 8080
+      endpoints:
+        - paths: [/hello]
+          port: http
+      healthCheck:
+        httpGet:
+          path: /_ah/health
+          port: http
+      dependencies:
+        - hello-function
+  ...
+```
+The `services` directive defines the services exposed by the module.
+
+##### name
+The service's name, used e.g. when referring to it as a dependency of another service, or when deploying
+specific services with `garden deploy`. Service names must be unique across all modules within a given project. An
+error will be thrown in any Garden CLI command if two services use the same name.
+
+##### command
+The CLI command to be executed (after the module is built) to make the service's endpoints available.
+
+##### ports
+Names each port exposed by the service.
+
+##### endpoints
+Enumerates the functional endpoints exposed by the service, defining the relative path and port to associate with 
+each of them.
+
+##### healthcheck
+Defines the endpoint used to query the service's availability.
+
+##### dependencies
+Lists the names of the services that must be deployed before the service in question (the `hello-container` service, in 
+this case) is deployed.
+
+##### tests
+A list of named test configurations for the module.
+
+Following is another snippet from [`hello-container`'s module config](#hello-container-module-configuration):
+```yaml
+module:
+  description: Hello world container service
+  type: container
+  ...
+  tests:
+    - name: unit
+      command: [npm, test]
+    - name: integ
+      command: [npm, run, integ]
+      dependencies:
+        - hello-function
+```
+Test groups can be run by `name` via `garden test`. `command` is the CLI command to run the specified tests, and 
+`dependencies` lists (by name) the services (if any) that must be deployed before the test group in question is run.
+
+#### Functions (experimental)
+For modules defining serverless functions, the `functions` directive specifies the names and entry points of the 
+functions the module exposes. Note that serverless functionality is still experimental and under active development. 
+
+This section is currently only included to clarify the `functions` directive in
+[`hello-function`'s module config](#hello-function-module-configuration), since it's used as an example here.
+
+### Examples
+
+#### hello-function Module Configuration
+[Github link](https://github.com/garden-io/garden/blob/528b141717f718ebe304d2ebde87b85d0c6c5e50/examples/hello-world/services/hello-function/garden.yml)
+````yaml
+# examples/hello-world/services/hello-function/garden.yml
+module:
+  description: Hello world serverless function
+  name: hello-function
+  type: google-cloud-function
+  functions:
+    - name: hello-function
+      entrypoint: helloFunction
+  tests:
+    - name: unit
+      command: [npm, test]
+  build:
+    dependencies:
+      - name: hello-npm-package
+        copy:
+          - source: "./"
+            target: libraries/hello-npm-package/
+````
+
+#### hello-container Module Configuration
+[Github link](https://github.com/garden-io/garden/blob/528b141717f718ebe304d2ebde87b85d0c6c5e50/examples/hello-world/services/hello-container/garden.yml)
+```yaml
+# examples/hello-world/services/hello-container/garden.yml
+module:
+  description: Hello world container service
+  type: container
+  services:
+    - name: hello-container
+      command: [npm, start]
+      ports:
+        - name: http
+          containerPort: 8080
+      endpoints:
+        - paths: [/hello]
+          port: http
+      healthCheck:
+        httpGet:
+          path: /_ah/health
+          port: http
+      dependencies:
+        - hello-function
+  build:
+    dependencies:
+      - hello-npm-package
+  tests:
+    - name: unit
+      command: [npm, test]
+    - name: integ
+      command: [npm, run, integ]
+      dependencies:
+        - hello-function
+```