documentation: getting-started doc

_documentation/getting-started.md

@@ -3,4 +3,144 @@ title: 'Getting Started'
 weight: 2
 ---
 
-TODO
+This page explains the basics of using AsCode to define your infrastructure in Terraform. It assumes that you have already [installed](/docs/install) Ascode.
+
+```sh
+> ascode --help
+Usage:
+  ascode [OPTIONS] <repl | run | version>
+
+AsCode - Terraform Alternative Syntax.
+
+Help Options:
+  -h, --help  Show this help message
+
+Available commands:
+  repl     Run as interactive shell.
+  run      Run parses, resolves, and executes a Starlark file.
+  version  Version prints information about this binary.
+```
+
+## The `repl` command
+
+The `repl` command provides a handy `REPL` interface for debugging and tinkering with AsCode. 
+
+For example you can explore the API of a resource  printing the list of arguments:
+
+```sh
+> ascode repl
+>>> print(dir(helm.resource))
+["__kind__", "__provider__", "release", "repository"]
+```
+
+Or to validate how a resource will be rendered:
+```sh
+> ascode repl
+>>> aws = tf.provider("aws")
+>>> web = aws.resource.instance("web", instance_type="t2.micro")
+>>> print(hcl(web))
+resource "aws_instance" "web" {
+  provider      = aws.id_01E4JV722PS2WPKK7WQ2NMZY6D
+  instance_type = "t2.micro"
+}
+```
+
+## The `run` command
+
+The `run` command executes a valid Starlack program. Using the `--print-hcl` and `--to-hcl`, an HCL encoded version of the `tf` object will be printed or saved to a given file, respectively.
+
+This is the first step to deploy any infrastructure d defined with AsCode, using `run` and generating a valid `.tf` file, we can use the standard Terraform tooling to deploy our infrastructure using `terraform init`, `terraform plan` and `terraform apply`.
+
+To learn about writing Starlark programs, please refer to the [Language definition](/docs/starlark/) and the [API Reference](/docs/reference/) sections of this documentation.
+
+
+### Basic Example
+
+The goal of the example is create, in DigitalOcean, one `s-1vcpu-1gb` instance called `web` in the `nyc2` region:
+
+> For running this example, you need `terraform` correctly installed on your system.
+
+```sh
+> mkdir example; cd example
+> echo 'do = tf.provider("digitalocean")' > main.star
+> echo 'web = do.resource.droplet("web", name="web", size="s-1vcpu-1gb")' >> main.star
+> echo 'web.region = "nyc2"' >> main.star
+> echo 'web.image  = "ubuntu-18-04-x64"' >> main.star
+```
+
+Now we are ready to run our Starlark program and generate a valid `HCL` file:
+
+```sh
+> ascode run main.star --to-hcl main.tf
+> cat main.tf
+provider "digitalocean" {
+  alias   = "id_01E4JXQD8HKW7XEQ7R5S8SP8AQ"
+  version = "1.15.1"
+}
+
+resource "digitalocean_droplet" "web" {
+  provider = digitalocean.id_01E4JXQD8HKW7XEQ7R5S8SP8AQ
+  image    = "ubuntu-18-04-x64"
+  name     = "web"
+  region   = "nyc2"
+  size     = "s-1vcpu-1gb"
+}
+
+
+```
+
+And now as it's common in terraform we can run `init`, `plan` or/and `apply`
+
+```sh
+> terraform init
+...
+> terraform plan
+Terraform will perform the following actions:
+
+  # digitalocean_droplet.web will be created
+  + resource "digitalocean_droplet" "web" {
+      + backups              = false
+      + disk                 = (known after apply)
+      + id                   = (known after apply)
+      + image                = "ubuntu-18-04-x64"
+      + ipv4_address         = (known after apply)
+      + ipv4_address_private = (known after apply)
+      + ipv6                 = false
+      + ipv6_address         = (known after apply)
+      + ipv6_address_private = (known after apply)
+      + locked               = (known after apply)
+      + memory               = (known after apply)
+      + monitoring           = false
+      + name                 = "web"
+      + price_hourly         = (known after apply)
+      + price_monthly        = (known after apply)
+      + private_networking   = false
+      + region               = "nyc2"
+      + resize_disk          = true
+      + size                 = "s-1vcpu-1gb"
+      + status               = (known after apply)
+      + urn                  = (known after apply)
+      + vcpus                = (known after apply)
+      + volume_ids           = (known after apply)
+    }
+
+Plan: 1 to add, 0 to change, 0 to destroy.
+
+> terraform apply
+...
+```
+
+## The `version` command
+
+The `version` command prints a report about the versions of the different
+dependencies, and AsCode itself used to compile the binary.
+
+```
+> ascode version
+Go Version: go1.14.1
+AsCode Version: v0.0.1
+AsCode Commit: 6a682e4
+AsCode Build Date: 2020-03-29T12:43:52+02:00
+Terraform Version: v0.12.23
+Starlark Version: v0.0.0-20200306205701-8dd3e2ee1dd5
+```