# Welcome to Terraforge!

### What is Terraforge?

Terraforge is a fully managed DevOps platform to provision services on all major cloud platforms.

**Defining** your infrastructure-as-code and **provisioning** your cloud services on the same platform makes your cloud engineering a lot easier and much more productive.

The built-in marketplace offers cloud service templates written by the Terraforge team and the community, ready for you to use and **get started even faster**!

There is no complicated setup required - [**Sign** **Up**](https://terraforge.io) and [**Start Forging**](https://beta.terraforge.io) your cloud!

### What are the features?

{% content-ref url="/pages/-Llqi7qVMNN9ch8jnXXd" %}
[Features](/features)
{% endcontent-ref %}

### How does it work?

{% content-ref url="/pages/-Llqah-QbWLQZDe1l2qy" %}
[How it works](/how-it-works)
{% endcontent-ref %}

{% hint style="success" %}
Check out the **Demos & Tutorials** to see Terraforge in action!
{% endhint %}

{% hint style="info" %}
Terraforge is still under heavy development - please contact us if you need a feature or want to help out!
{% endhint %}


# Features

### Online Code Editor

Writing infrastructure source code is assisted by a powerful online editor with Terraform code validation as you type and automatic code formatting, keeping your code clean and consistent.

Pending changes to your cloud services can be inspected directly from the editor with a single click.

{% hint style="success" %}
**Good to know:** The online code editor displays documentation of the cloud resource you're currently working on.
{% endhint %}

### Best Practices

Terraforge guides the creation of infrastructure-as-code with an opinionated source code structure for multiple environments keeping the code [DRY](https://en.wikipedia.org/wiki/Redundancy_\(engineering\)) and uniform across your company.

### DevOps Pipelines

Validate your infrastructure code, commit the code to a Git repository and provision your cloud services in a single DevOps pipeline.

### Cloud Service Templates

Copy existing infrastructure-as-code stacks from the Terraforge Marketplace and start forging your own cloud.

### It's FREE to use!

Seriously, the hosted version is free to use and will stay free! We believe in giving back to the open-source community and this is part of our contribution. Source code will follow.

Please [contact](mailto:contact@terraforge.io) us if you're interested in an on-premise installation at your company.

### No Terraform Setup required

Terraforge offers a built-in Terraform state management (optional) for each stack, accelerating the creation of new stacks without the need to configure a Terraform backend.

### Team Collaboration

Your team can work on multiple projects and stacks making it scale for small to large companies. Multiple organisations are supported for users which maintain clouds for many different companies.

{% hint style="warning" %}
**Need a feature? Let us know!**\
Terraforge is under heavy development with daily release cycles. Let us know what you think and which feature would be useful for your daily work.
{% endhint %}


# How it works

Terraforge is a web-based cloud infrastructure DevOps tool available as a free hosted solution or as an on-premise setup customised to your company.

![](https://3882212096-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LahX5FBixtrNAsBFikz%2F-LrQdvoot-rGxGGntF-K%2F-LrQdzRme1_HAAyO3zNZ%2Fterraforge-docs-how-it-works.png?alt=media\&token=8aefdf39-8e9e-4f42-bba5-36468c20ce80)

Through the Terraforge web interface, you can define different environments and configurations, resembling your cloud architecture (production, testing, etc...) and develop infrastructure-as-code using the online code editor.

Once your code is ready, the platform runs Terraform to provision your cloud services and optionally pushes your source code to one of the version control systems Gitlab or Github.


# HashiCorp Meetup Slides

Terraforge was presented at the HashiCorp User Group in Zurich on the 17. October; <https://www.meetup.com/Zurich-HashiCorp-User-Group/events/265368150/>

## Slides

<https://beta-terraforge-public-assets.s3.amazonaws.com/slides/Terraforge_20191017.pdf>


# First Steps

Estimated time: 5mins

This short tutorial gives an introduction to the basic features of Terraforge:

* Environments
* Terraform Backend
* Terraform Stack + Configuration per Environment
* Deployment + Pipeline

{% hint style="info" %}
The **Terraform Local Provider** will be used as it requires no configuration. Please find more information at <https://www.terraform.io/docs/providers/local/index.html>&#x20;
{% endhint %}


# 1 - Tutorial Environment

Goal: Create an environment for the tutorial

{% embed url="<https://beta-terraforge-public-assets.s3.amazonaws.com/first-steps-1-environment.mp4>" %}

## Steps

1. Navigate to **Environment** on the left side menu
2. Set **Environment name** to `tutorial`
3. Set **Description** to `Sandbox for tutorials`
4. Leave all other options as default and click **SAVE**

{% hint style="info" %}
**ENV Variables** are used to set Terraform variables via shell environment variables prefixed with `TF_VAR_`

**Backend** is the Terraform backend to store the Terraform state, see <https://www.terraform.io/docs/backends/> for further information.
{% endhint %}

{% hint style="success" %}
Terraforge provides each own **Backend** and needs no configuration!
{% endhint %}


# 2 - Terraform Stack (local\_file)

Goal: Create a Terraforge stack to provision a plain text-file

{% embed url="<https://beta-terraforge-public-assets.s3.amazonaws.com/first-steps-2-terraform-stack.mp4>" %}

## Steps

1. Navigate to **Stacks** on the left side menu
2. Click **+ ADD  STACK** on the left side
3. Set **Name** to `tutorial-text-file`&#x20;
4. Set **Description** to `Create a text-file on localhost`&#x20;
5. Set **Tags** to `tutorial` and `local` (press TAB after typing)
6. Leave all other options as default and click **SAVE**

{% hint style="info" %}
**Marketplace** allows the Stack to be copied across organizations and projects.

**Public** allows all other Terraforge users to copy (but not modify!) this stack from the marketplace.

**Backend** allows to append arguments to the Environment backend&#x20;
{% endhint %}

{% hint style="danger" %}
WARNING: Never store sensitive information in a Stack and enable **Marketplace** and **Public**! Keep Terraform code DRY and free of sensitive information.
{% endhint %}


# 2.1 - Source Code Editor

Goal: Create a Terraform resource

{% embed url="<https://beta-terraforge-public-assets.s3.amazonaws.com/first-steps-2.1-source-code-editor.mp4>" %}

## Steps

1. Select **main.tf** in the file tree and add the following Terraform code:\
   `resource "local_file" "txt" {`\
   &#x20; `filename = "tutorial.txt"`  \
   &#x20; `content  = "Hello world!"`\
   `}`
2. Click **SAVE**

{% hint style="info" %}
Your Terraform (HCL) source code is validated as you type!
{% endhint %}

{% hint style="success" %}
On the right side you can switch between the **CODE** view, **FORM** builder or official Terraform **DOCS** <img src="https://3882212096-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LahX5FBixtrNAsBFikz%2F-LlXvept5Mb6B3yo6CPq%2F-LlY-BAlBqWRa9Gk2DCG%2Fstaging.terraforge.io_megatech_aws-mock-cloud-1_stacks_text-file-2004_terraform_files_main.tf_t%3Dresource%26s%3Dlocal_file%26n%3Dtxt%20(1).png?alt=media&amp;token=406ebfac-3520-4a92-a897-9c7fc54fbdf0" alt="" data-size="original">
{% endhint %}


# 2.2 - Terraform validate & plan

Goal: Validate and plan the Terraform code

{% embed url="<https://beta-terraforge-public-assets.s3.amazonaws.com/first-steps-2.2-validate-plan.mp4>" %}

## Steps

1. Switch to the **Configuration** tab
2. Click **+ ADD CONFIG**, set **Environment** to `tutorial` and click **ADD**
3. At the screen bottom is the Terraform Console, select **VALIDATE** and press run&#x20;
   1. Terraforge now runs CLI command `terraform validate` on your stack
4. Press the **+** on the right side of the Terraform Console to view the console output
5. Select **PLAN**, the configuration **tutorial** and press run
   1. Terraforge now runs the CLI command `terraform init` and `terraform plan` on your stack
6. Press the **+** on the right side of the Terraform Console and click the **Fullscreen** button in black area to view the console output

{% hint style="info" %}
The **Name** property can be set if multiple configurations shall be deployed in a given environment.
{% endhint %}


# 2.3 - README

Goal: Use markdown to document your stack

{% embed url="<https://beta-terraforge-public-assets.s3.amazonaws.com/first-steps-2.3-readme.mp4>" %}

## Steps

1. Switch to the **README** tab
2. Click on **EDIT**
3. Write documentation for this stack:\
   `# Purpose`\
   \
   `This stack creates a text-file using the Terraform local provider`
4. Click **SAVE**

{% hint style="success" %}
The **README** can be used to document the architecture and configuration of a Terraform stack.
{% endhint %}


# 3 - Pipeline Apply

Goal: Run a DevOps pipeline to deploy the stack

{% embed url="<https://beta-terraforge-public-assets.s3.amazonaws.com/first-steps-3-pipeline.mp4>" %}

## Steps

1. Navigate to **Pipelines** on the left side menu
2. Select **Stack**`tutorial-text-file` and Configuration **tutorial**
3. Select steps **Plan** and **Apply** and click **RUN**
4. Click on the first pipeline in the list to view the Terraform console output of all steps

{% hint style="info" %}
The pipeline step **Commit** is used to push the Terraform source code to a Git repository configured in the stack **git Integration** tab

The pipeline step **Destroy** is used to destroy all resources of a stack.\
Try it with the `tutorial-text-file` stack!
{% endhint %}


# AWS Stack (simple)

Estimated time: 10mins

This tutorial gives an introduction how to provision resources in an AWS cloud.

We provision an AWS Docker registry called *"Elastic Container Registry"* or short **ECR** which is free to create on AWS.

## Preparation

For this tutorial you need an AWS account. If you don't have one already, you can sign-up here: <https://portal.aws.amazon.com/gp/aws/developer/registration/index.html>


# 1 - Terraform user

Goal: Create an AWS user for Terraform

{% embed url="<https://beta-terraforge-public-assets.s3.amazonaws.com/aws-stack-1-terraform-user.mp4>" %}

## Steps

1. Login to your [AWS Console](https://console.aws.amazon.com/console/home) and navigate to [IAM users](https://console.aws.amazon.com/iam/home#/users)
2. Click **Add user**
3. Set **User name** to `tutorial` and select **Access type** `programmatic access`
4. Click **Next: Permissions**
5. In **Attach existing policies directly** select `AmazonEC2ContainerRegistryFullAccess` for this tutorial. Please read the notes below.
6. Click **Next: Tags** and **Next: Review** and **Create user**
7. Write down the **Access key ID** and **Secret access key**

{% hint style="danger" %}
The policy`AmazonEC2ContainerRegistryFullAccess`is sufficient for this tutorial. For more complex stacks elevated permissions will be required.

Full access is provided by the policy`AdministratorAccess`&#x20;
{% endhint %}


# 2 - Sandbox Environment

Goal: Create an sandbox environment for AWS and store the AWS\_ACCESS\_KEY\_ID

{% embed url="<https://beta-terraforge-public-assets.s3.amazonaws.com/aws-stack-2-sandbox-environment.mp4>" %}

## Steps

1. Navigate to **Environment** on the left side menu
2. Set **Environment name** to `sandbox`
3. Set **Description** to `Sandbox for AWS tutorials`
4. Add the ENV Variable **AWS\_ACCESS\_KEY\_ID** and set it to the **Access key ID** from the AWS Console
5. Add the ENV Variable **AWS\_SECRET\_ACCESS\_KEY** and leave it empty
6. Leave all other options as default and click **SAVE**

{% hint style="info" %}
ENV variables are stored encrypted. Sensitive variables should be left empty and will be prompted on deployment.
{% endhint %}


# 3 - Terraform Stack (ECR registry)

Goal: Create a Terraforge stack to provision an AWS Docker registry (ECR)

{% embed url="<https://beta-terraforge-public-assets.s3.amazonaws.com/aws-stack-3-terraform-stack.mp4>" %}

## Steps

1. Navigate to **Stacks** on the left side menu
2. Click **+ ADD  STACK** on the left side
3. Set **Name** to `tutorial-ecr-registry`&#x20;
4. Set **Description** to `Create a Docker registry on AWS`&#x20;
5. Set **Tags** to `tutorial` and `aws` and `ecr` (press TAB after typing)
6. Leave all other options as default and click **SAVE**


# 3.1 - Terraform Code

Goal: Create a Terraform provider / resource / variable

{% embed url="<https://beta-terraforge-public-assets.s3.amazonaws.com/aws-stack-3.1-terraform-code.mp4>" %}

## Steps

1. Select **main.tf** in the file tree and add the following Terraform code:\
   `provider "aws" {`\
   &#x20; `region = var.aws_region`\
   `}`
2. Click **SAVE**
3. Select **variables.tf** in the file tree and the following Terraform code:\
   `variable "aws_region" {`\
   \
   `}`
4. Click **+ ADD**  and select **Terraform File** and set **File Path** to `ecr.tf`
5. Add the following Terraform code:\
   `resource "aws_ecr_repository" "tutorial" {`\
   &#x20; `name = "tutorial"`\
   `}`
6. Click **ADD** (or **SAVE**)
7. Click on **FORM** on the top-right corner to use the resource builder
8. Click on **DOCS** on the top-right corner to see the Terraform documentation for this resource


# 3.2 Terraform validate & plan

Goal: Validate and plan the Terraform code

{% embed url="<https://beta-terraforge-public-assets.s3.amazonaws.com/aws-stack-3.2-terraform-validate-plan.mp4>" %}

## Steps

1. Switch to the **Configuration** tab
2. Click **+ ADD CONFIG**, set **Environment** to `sandbox` , **aws\_region** to `"us-east-1"`and click **ADD**
3. At the screen bottom is the Terraform Console, select **VALIDATE** and press run
   1. Terraforge now runs CLI command `terraform validate` on your stack
4. Press the **+** on the right side of the Terraform Console to view the console output
5. Select **PLAN**, the configuration **tutorial** and press run
   1. You will be prompted to enter **AWS\_SECRET\_ACCESS\_KEY**, enter the **Secret access key** from the `tutorial` user created via AWS Console
   2. Terraforge now runs the CLI command `terraform init` and `terraform plan` on your stack in your AWS account
6. Press the **+** on the right side of the Terraform Console and click the **Fullscreen** button in black area to view the console output

{% hint style="danger" %}
Terraforge does **NOT** store any AWS credentials or values prompted after PLAN or APPLY!&#x20;
{% endhint %}


# 4 - Pipeline Apply

Goal: Run a DevOps pipeline to provision the AWS Docker registry (ECR)

{% embed url="<https://beta-terraforge-public-assets.s3.amazonaws.com/aws-stack-4-pipeline-apply.mp4>" %}

## Steps

1. Navigate to **Pipelines** on the left side menu
2. Select **Stack**`tutorial-ecr-registry` and Configuration **tutorial**
3. Select steps **Plan** and **Apply** and click **RUN**
4. You will be prompted to enter **AWS\_SECRET\_ACCESS\_KEY**, enter the **Secret access key** from the `tutorial` user created via AWS Console
5. Click on the first pipeline in the list to view the Terraform console output of all steps
6. Verify the ECR repository has been created by visiting the AWS Console at <https://console.aws.amazon.com/ecr/repositories?region=us-east-1>


# 5 - Pipeline Destroy

Goal: Run a DevOps pipeline to destroy the AWS Docker registry (ECR)

{% embed url="<https://beta-terraforge-public-assets.s3.amazonaws.com/aws-stack-5-pipeline-destroy.mp4>" %}

## Steps

1. Navigate to **Pipelines** on the left side menu
2. Select **Stack**`tutorial-ecr-registry` and Configuration **tutorial**
3. Select step **Destroy** and click **RUN**
4. You will be prompted to enter **AWS\_SECRET\_ACCESS\_KEY**, enter the **Secret access key** from the `tutorial` user created via AWS Console
5. Click on the first pipeline in the list to view the Terraform console output of all steps
6. Verify the ECR repository has been removed by visiting the AWS Console at <https://console.aws.amazon.com/ecr/repositories?region=us-east-1>