rewrite circleci docs

localstack · Oct 23, 2023 · 1922654 · 1922654
1 parent b82e4bf
commit 1922654
Showing 1 changed file with 90 additions and 22 deletions.
diff --git a/content/en/user-guide/ci/circle-ci/index.md b/content/en/user-guide/ci/circle-ci/index.md
@@ -1,45 +1,113 @@
 ---
 title: "CircleCI"
-tags: ["continuous-integration", "ci", "continuous-delivery", "testing"] 
+linkTitle: "CircleCI"
 weight: 4
 description: >
   Use LocalStack in [Circle CI](https://circleci.com/)
-aliases:
-  - /ci/circle-ci/
 ---
 
-This guide describes how to start and use LocalStack in your CircleCI pipelines.
+CircleCI is a continuous integration and continuous delivery (CI/CD) platform which uses a configuration file (usually named `.circleci/config.yml`) to define the build, test, and deployment workflows. LocalStack supports CircleCI out of the box and can be easily integrated into your pipeline to run your tests against a local cloud emulator.
 
-## Setting up your CircleCI job
+## Getting started
 
-LocalStack is an official partner of [Circle CI](https://circleci.com/) and can easily be integrated into your pipeline by using the [official CircleCI Orb](https://circleci.com/developer/orbs/orb/localstack/platform).\
-The [Orb's documentation](https://circleci.com/developer/orbs/orb/localstack/platform) features examples, as well as a description of the available commands.
+This guide is designed for users new to CircleCI and assumes basic knowledge of YAML and our LocalStack tooling.
 
-When using the official CircleCI Orb, using LocalStack in your pipeline is as easy as adding the Orb to your pipeline and executing the startup command.\
-The following example CircleCI config (`.circleci/config.yml`) starts LocalStack, creates a new S3 bucket, and prints a nice message in the end:
-```yaml
+Create a new file named `.circleci/config.yml` in your project's root directory and add the following content:
+
+{{< tabpane >}}
+{{< tab header="Community" lang="yml" >}}
+version: 2.1
+
+orbs:
+  python: circleci/[email protected]
+
+jobs:
+  example-job:
+    machine: # executor type
+      image: ubuntu-2004:2022.04.1
+
+    steps:
+      - checkout
+
+      - run:
+          name: Start LocalStack
+          command: |
+            pip3 install localstack awscli-local[ver1] # Install LocalStack CLI and `awslocal`
+            docker pull localstack/localstack
+            localstack start -d                       # Start LocalStack in the background
+
+            echo "Waiting for LocalStack startup..."  # Wait 30 seconds for the LocalStack container
+            localstack wait -t 30                     # to become ready before timing out 
+            echo "Startup complete"
+            
+      - run:
+          name: Run AWS CLI commands against LocalStack
+          command: |
+            awslocal s3 mb s3://test-bucket
+            awslocal sqs create-queue --queue-name test-queue
+            awslocal sns create-topic --name test-topic
+
+workflows:
+  version: 2
+  build:
+    jobs:
+      - example-job
+{{< /tab >}}
+{{< tab header="Pro" lang="yml" >}}
 version: 2.1
+
 orbs:
-  localstack: localstack/[email protected]
+  python: circleci/[email protected]
+
 jobs:
-  run-integration-tests:
-    executor: localstack/default
+  example-job:
+    machine: # executor type
+      image: ubuntu-2004:2022.04.1
+    environment:
+      LOCALSTACK_API_KEY: YOUR_API_KEY_HERE
+
     steps:
-      - localstack/startup
+      - checkout
+
       - run:
-          command: awslocal s3 mb s3://test-bucket
+          name: Start LocalStack
+          command: |
+            pip3 install localstack awscli-local[ver1]
+            docker pull localstack/localstack-pro
+            localstack start -d
+            echo "Waiting for LocalStack startup..."
+            localstack wait -t 30
+            echo "Startup complete"
+            
       - run:
-          command: echo "Execute your tests here :)"
+          name: Run AWS CLI commands against LocalStack
+          command: |
+            awslocal s3 mb s3://test-bucket
+            awslocal sqs create-queue --queue-name test-queue
+            awslocal sns create-topic --name test-topic
+
 workflows:
-  integration-test:
+  version: 2
+  build:
     jobs:
-      - run-integration-tests
-```
+      - example-job
+{{< /tab >}}
+{{< /tabpane >}}
+
+The above CircleCI job does the following:
+
+- Defines a job called `example-job` that installs the `localstack` CLI and `awslocal` wrapper script to execute AWS CLI commands against LocalStack.
+- Pulls the LocalStack Docker image depending on the product tier (For Community, the image is `localstack/localstack`, while for Pro it is `localstack/localstack-pro`).
+- Starts LocalStack in the background and waits for it to become ready. After 30 seconds, the job will execute basic AWS CLI commands against LocalStack.
 
 ## Configuring an API key
 
-You can easily enable LocalStack Pro by adding your API key to the project's environment variables. The LocalStack Orb will automatically pick it up and activate the Pro features.
+To enable LocalStack Pro, you need to add your LocalStack API key to the project's environment variables. The LocalStack will automatically pick it up and activate the licensed features. To add the API key, follow these steps:
 
-Just go to the project settings in CircleCI, click on `Environment Variables` in the sidebar and add your API key:
+- Click on **Project Settings**.
+- Select **Environment Variables** from the left side menu.
+- Click **Add Environment Variable**.
+- Name your environment variable `LOCALSTACK_API_KEY`.
+- Paste your secret into the input field.
 
-![Adding the LocalStack API key in CircleCI](circleci-env-config.png)
+<img src="circleci-env-config.png" width="800px" alt="Adding the LocalStack API key in CircleCI" />