diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 8eb9a56fd..e35ba5b70 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -54,7 +54,6 @@ export default defineConfig({ : ["/src/assets/docs.css", "@fontsource/roboto"], sidebar: [ { label: "Welcome", link: "/" }, - { label: "Quickstart Guide", link: "/quickstart-guide" }, { label: "How It Works", link: "/how-it-works" }, { label: "Getting Started", diff --git a/docs/src/assets/demo-create-fork.png b/docs/src/assets/demo-create-fork.png new file mode 100644 index 000000000..1c87a8162 Binary files /dev/null and b/docs/src/assets/demo-create-fork.png differ diff --git a/docs/src/assets/demo-fork.png b/docs/src/assets/demo-fork.png new file mode 100644 index 000000000..e99f7459e Binary files /dev/null and b/docs/src/assets/demo-fork.png differ diff --git a/docs/src/assets/demo-install-terrateam-2.png b/docs/src/assets/demo-install-terrateam-2.png new file mode 100644 index 000000000..b33e5967a Binary files /dev/null and b/docs/src/assets/demo-install-terrateam-2.png differ diff --git a/docs/src/assets/demo-install-terrateam.png b/docs/src/assets/demo-install-terrateam.png new file mode 100644 index 000000000..6c250dea5 Binary files /dev/null and b/docs/src/assets/demo-install-terrateam.png differ diff --git a/docs/src/assets/demo-plan-output.png b/docs/src/assets/demo-plan-output.png new file mode 100644 index 000000000..99bb9490f Binary files /dev/null and b/docs/src/assets/demo-plan-output.png differ diff --git a/docs/src/assets/demo-pr-2.png b/docs/src/assets/demo-pr-2.png new file mode 100644 index 000000000..fa17dc74e Binary files /dev/null and b/docs/src/assets/demo-pr-2.png differ diff --git a/docs/src/assets/demo-pr-apply.png b/docs/src/assets/demo-pr-apply.png new file mode 100644 index 000000000..cf8c7f548 Binary files /dev/null and b/docs/src/assets/demo-pr-apply.png differ diff --git a/docs/src/assets/demo-pr-enable-actions.png b/docs/src/assets/demo-pr-enable-actions.png new file mode 100644 index 000000000..cf0066e3c Binary files /dev/null and b/docs/src/assets/demo-pr-enable-actions.png differ diff --git a/docs/src/assets/demo-pr.png b/docs/src/assets/demo-pr.png new file mode 100644 index 000000000..0e7e87d85 Binary files /dev/null and b/docs/src/assets/demo-pr.png differ diff --git a/docs/src/assets/demo-terrateam-dashboard.png b/docs/src/assets/demo-terrateam-dashboard.png new file mode 100644 index 000000000..351b84425 Binary files /dev/null and b/docs/src/assets/demo-terrateam-dashboard.png differ diff --git a/docs/src/assets/demo-var-change-2.png b/docs/src/assets/demo-var-change-2.png new file mode 100644 index 000000000..d475f3bf2 Binary files /dev/null and b/docs/src/assets/demo-var-change-2.png differ diff --git a/docs/src/assets/demo-var-change.png b/docs/src/assets/demo-var-change.png new file mode 100644 index 000000000..2869ee51f Binary files /dev/null and b/docs/src/assets/demo-var-change.png differ diff --git a/docs/src/content/docs/getting-started/quickstart-guide.mdx b/docs/src/content/docs/getting-started/quickstart-guide.mdx new file mode 100644 index 000000000..7d983af92 --- /dev/null +++ b/docs/src/content/docs/getting-started/quickstart-guide.mdx @@ -0,0 +1,138 @@ +--- +title: Quickstart Guide +description: Get up and running with Terrateam in minutes. +--- +import { Steps } from '@astrojs/starlight/components'; +import { Icon } from '@astrojs/starlight/components'; +import { LinkCard, CardGrid, Card } from '@astrojs/starlight/components'; + +The following steps on this page will help you to set up Terrateam, integrate it with GitHub, and run your first Terraform deployment in just a few steps. + +## Prerequisites + +Before getting started with Terrateam quickstart guide, make sure you have the following: + +- **A GitHub account** to fork the Terrateam [demo repository](https://github.com/terrateam-demo/kick-the-tires). +- **GitHub Actions** enabled in your forked repository. +- **Administrator access** to install the Terrateam GitHub app. + + +## Demo Repository Workflow + +To have an overview on how to use Terrateam, use the the Terrateam ready-to-use demo repository with pre-configured Terraform code. Follow these steps to quickly test Terrateam's capabilities. + + + + +1. **Fork the Demo Repository** + + Click the link above to access our demo repository, then click the **Fork** button in the top-right corner of the page. + + ![Fork button on GitHub repository](../../../assets/demo-fork.png) + + On the "Create a new fork" screen, keep the default settings and click "Create fork". + + ![Create a new fork](../../../assets/demo-create-fork.png) + + +2. **Install the Terrateam GitHub Application (if you haven't already)** + + Sign up for a Terrateam account and install the GitHub app. Then, select the organizations and repositories that contain your Terraform code. + + + ![Install Terrateam](../../../assets/demo-install-terrateam-2.png) + After installation, go to [your Terrateam dashboard](https://app.terrateam.io/). Your forked repository should appear there. + ![Terrateam dashboard](../../../assets/demo-terrateam-dashboard.png) + +3. **Clone Your Forked Repository** + + Clone the repository to your local machine and navigate to its directory: + + ```bash + git clone https://github.com//kick-the-tires.git + cd kick-the-tires + ``` + + +4. **Create a New Branch** + + Create a branch to make your changes: + + ```bash + git checkout -b test-branch + ``` + +5. **Modify a Terraform File** + + Let's modify a file to test the workflow, changes are detected automatically. Open `staging/compute/main.tf` and change the instance name. + + ```hcl {5} + module "staging_compute_instance" { + source = "../../modules/compute" + + instance_count = 0 + instance_name = "staging-instance-modified" + instance_zone = "us-central1-a" + boot_disk_image = "debian-cloud/debian-11" + network_name = "default" + } + ``` + +6. **Commit and Push Your Changes** + + Commit your changes and push them to your branch: + + ```bash + git add . + git commit -m "Testing Terrateam workflow" + git push origin test-branch + ``` + +7. **Create a Pull Request** + + Go to your forked repository on GitHub. You should see a prompt to create a pull request for your recently pushed branch. + ![Create a pull request](../../../assets/demo-pr.png) + + :::warning + Important: Make sure to change the base repository to your fork instead of creating a PR on the original Terrateam repository. The base should be your `main` branch, and the compare should be your `test-branch`. + ::: + + ![Creating a pull request with proper base repository](../../../assets/demo-pr-2.png) + + :::caution + Ensure that [workflows are enabled](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/disabling-and-enabling-a-workflow#enabling-a-workflow) on your forked repository. If GitHub Actions workflows are disabled, you'll need to enable them in the repository settings. + ::: + +8. **Watch the Automatic Terraform Plan** + + Once the pull request is created, Terrateam will automatically trigger a [`terraform plan`](/getting-started/plan-and-apply). This plan will appear as a comment on your pull request, showing what changes would be made. + + + ![Automatic Terraform plan in PR comments](../../../assets/demo-plan-output.png) + + This plan is a preview of what will happen when you apply the changes. + +9. **Apply the Changes** + + To execute the changes, comment `terrateam apply` on the pull request. + ![Apply the changes](../../../assets/demo-pr-apply.png) + + After you add the comment, the Terrateam app will run the `terraform apply` command. This will apply the previous plan to the Terraform file, updating your infrastructure. + +10. **Merge Your Changes** + + Once applied and everything looks good, you can merge the pull request to incorporate the changes into your main branch. + + +### Next steps + + + + + diff --git a/docs/src/content/docs/quickstart-guide.mdx b/docs/src/content/docs/quickstart-guide.mdx deleted file mode 100644 index 817914e91..000000000 --- a/docs/src/content/docs/quickstart-guide.mdx +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Quickstart Guide -description: Get up and running with Terrateam in minutes ---- - -import { Steps } from '@astrojs/starlight/components'; -import { Icon } from '@astrojs/starlight/components'; -import { LinkCard } from '@astrojs/starlight/components'; - -Installing Terrateam is a straightforward process. By following these three easy steps, you'll have Terrateam up and running in your GitHub repository in no time. - -## Terrateam Installation - -#### Step 1. [Sign up and Install the Terrateam GitHub Application](https://terrateam.io/signup) - - * **$149/mo unlimited. 14-day free trial. No credit card required.** - * Select any of your GitHub organizations and repositories that contain Terraform code. - * [Click here to sign up and install the Terrateam GitHub application](https://terrateam.io/signup) - ![GitHub application installation](../../assets/install-terrateam-github.png) - -#### Step 2. Add the Terrateam GitHub Actions Workflow - - * **[Download terrateam.yml](https://raw.githubusercontent.com/terrateamio/terrateam-example/main/github/actions/workflows/default/terrateam.yml)** - * The Terrateam GitHub Actions workflow file (`.github/workflows/terrateam.yml`) must be stored in the default branch of your Terraform repository. The default branch is usually named `main` or `master`. - - :::note - Create the `.github/workflows` directory if it doesn't exist. This is done for you automatically if you're using the GitHub UI (GitHub.com in a browser). - ::: - - ![GitHub Actions Workflow File](../../assets/github-actions-workflow-file-location.png) - -#### Step 3. Start Using Terrateam - If you want to see how Terrateam works without connecting to your cloud provider, continue reading to deploy a simple `null_resource`. Otherwise, jump to [Cloud Providers -](/cloud-providers). - -## Your First Terrateam Deployment - -:::tip[Did you know?] -With Terrateam you can apply changes before or after merging a pull request. -::: - -### Plan and Apply - - We will now trigger our first Terrateam deployment by creating a simple pull request with a `null_resource`. The `null_resource` provider does not take any action against live environments - making it completely safe for our first deployment. - - - -1. #### New Branch - - Create a new branch against a repository with Terrateam installed. - - ![Terrateam first run branch](../../assets/terrateam-first-run-branch.png) - -1. #### Add Terraform Code - - Create a new file called `main.tf` in any directory in the repository. [Download the code here](https://raw.githubusercontent.com/terrateamio/terrateam-example/main/main.tf). - - ![Terrateam main.tf](../../assets/nibbler-main-tf.png) - -1. #### Pull Request - - Commit and push `main.tf` to your branch and then create a pull request. - - ![Terrateam pull request](../../assets/nibbler-pull-request.png) - -1. #### Terraform Plan - - Terrateam will automatically trigger a `terraform plan`. - - ![Terrateam plan](../../assets/nibbler-terrateam-plan.png) - -1. #### Terraform Apply - - Comment `terrateam apply` on the pull request. Terrateam will trigger a `terraform apply`. - - ![Terrateam Apply](../../assets/nibbler-terrateam-apply.png) - -1. #### Merge - - Merge the pull request. - - ![Pull Request Merge](../../assets/nibbler-merge.png) - - :::tip[Apply after merge] - [Click here to learn how to apply your changes after merging a pull request.](/advanced-workflows/apply-after-merge) - ::: - - - -### Bravo! - -You've just completed your first Terrateam deployment. - -## Learn More -See [Cloud Providers](/cloud-providers) to learn how to integrate Terrateam against AWS, GCP, Azure, and more. diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 000000000..f2e12eadb --- /dev/null +++ b/package-lock.json @@ -0,0 +1,6 @@ +{ + "name": "terrateam", + "lockfileVersion": 3, + "requires": true, + "packages": {} +}