Deploying - using 3d party CI

Overview

Using Stacktape in your continuous integration/continuous deployment pipeline is very straightforward.

In most cases, you just need to add 2 simple steps to your pipeline to deploy your application in a CI/CD pipeline:

Install Stacktape (curl -L https://installs.stacktape.com/linux.sh | bash or curl -L https://installs.stacktape.com/alpine.sh | bash for alpine linux images).
Deploy using stacktape deploy --stage <<stage>> --region region.

1. Using Github actions

If you're using Github and want to deploy your Stacktape application from a CI/CD pipeline:

1.1 - Create Github repository

If you don't have a repository, navigate to https://github.com/new.

1.2 - Create repository secrets

The deployment pipeline requires Stacktape credentials - STACKTAPE_API_KEY. If your AWS account is connected to the Stacktape in Manual credentials mode, you will also need to provide AWS credentials AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
Hard-coding them in the pipeline file is not safe, and you should use secrets instead.
To create these secrets, navigate to your github project's settings, select Secrets tab, choose Actions->secrets and then create your secrets by clicking on New repository secret. These secrets will be securely stored and accessible to all of your workflows using the ${{ secrets.<<secret-name>> }} syntax.
Alternatively, you can use organization-wide secrets.

1.3 - Add workflow config

Create your Github action workflow configuration at .github/workflows/<<your-workflow-name>>.yml in your project directory. You can use the following template:
The Install project dependencies step is optional and required only if you use Stacktape lambda buildpack or Stacktape image buildpack to package your workloads.


Copy
name: Deploy application using Stacktape
on:
  push:
    branches:
      - main
jobs:
  deploy-app:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: "16"
      - name: Install Stacktape
        run: curl -L https://installs.stacktape.com/linux.sh | bash
      - name: Deploy the stack
        run: stacktape deploy --stage <<stage>> --region <<region>>
        env:
          STACKTAPE_API_KEY: ${{ secrets.STACKTAPE_API_KEY }}

1.4 - Push to the Github repository

The pipeline is triggered when you push to the main branch of you github repository.

git init --initial-branch=main
git commit -m "setup stacktape project"
git remote add origin git@github.com:<<namespace-name>>/<<repo-name>>.git (replace with your github repository)
git push -u origin main
To monitor the deployment progress, navigate to your gitlab project and select Actions tab.

2 - Using Gitlab CI

If you're using Gitlab and want to deploy your Stacktape application from a CI/CD pipeline:

2.1 - Create Gitlab repository

If you don't have a repository, navigate to https://gitlab.com/projects/new.

2.2 - Create Gitlab repository secrets

The deployment pipeline requires Stacktape credentials - STACKTAPE_API_KEY. If your AWS account is connected to the Stacktape in Manual credentials mode, you will also need to provide AWS credentials AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
Hard-coding them in the pipeline file is not safe, and you should use secrets instead.
@todo

2.3 - Add workflow config

Create your Gitlab action workflow configuration at .gitlab-ci.yml in the root directory of your project. You can use the following template:
The install project dependencies step is optional and required only if you use Stacktape lambda buildpack or Stacktape image buildpack to package your compute resources.


Copy
variables:
  DOCKER_DRIVER: overlay2

stages:
  - build

services:
  - docker:dind

deploy-app-job:
  stage: build
  rules:
    # only execute job on push to the master/main
    - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  image: docker:20
  script:
    # install container dependencies
    - apk add --update bash curl nodejs npm
    # install project dependencies
    - npm install
    # install Stacktape
    - curl -L https://installs.stacktape.com/alpine.sh | bash
    # set PATH so that we can use the "stacktape" and "stp" aliases for the binary
    - export PATH=$PATH:/root/.stacktape/bin
    # deploy the stack
    - stp deploy --stage <<stage>> --region <<region>>

2.4 - Push to the gitlab repository

The pipeline is triggered when you push to the main branch of you gitlab repository.

git init --initial-branch=main
git commit -m "setup stacktape project"
git remote add origin git@gitlab.com:<<namespace-name>>/<<repo-name>>.git (replace with your gitlab repository)
git push -u origin main
To monitor the deployment progress, navigate to your gitlab project and select CI/CD->jobs.

3 - Using Bitbucket CI

3.1 - Create Stacktape project

First, create a Stacktape project.

In the Stacktape console click on the Deploy new project button in the top right corner and choose Any project using CLI.

Choose project name - project name can contain lowercase letters, numbers, and dashes. The name is arbitrary, but developers often use the name of the Bitbucket repository as their project name. In this tutorial, we are using my-project-1.
Choose how you write a configuration - If you already have our Stacktape configuration prepared in our Bitbucket repository, choose I'll write Stacktape config on my own. In our case, we will create the Stacktape configuration now, so we choose Interactively in console - this option provides an interactive editor to write your Stacktape configuration in the next step.

If you have chosen to write configuration Interactively in console, then in this step, you will write Stacktape config using the interactive config editor. Our configuration only contains an HTTP API gateway connected to a Lambda function. After finishing with the configuration, continue to the next step.

Your Stacktape project is created and ready to be used. In the final step, you can see information on how to install Stacktape CLI and log in to Stacktape on your local machine.

If you have used an interactive configuration editor to create your configuration, you can use stacktape init command to download the created configuration onto your local machine. You should place the downloaded file in the root of your project repository.

3.2 Create API key

For Stacktape CLI to securely communicate with the rest of the Stacktape infrastructure, the API Key must be used.

Get the API key by navigating into API key overview

If you do not have an API key, create one.

After creating the API key, you can copy its value. We will use it in the next step.

3.3 Setup Bitbucket Pipeline

This step will set up BitBucket pipelines to automatically deploy on push to your repository.

Navigate to your Bitbucket repository to Deployments page.

Your repository should already contain stacktape.yml or stacktape.ts in its root directory.

On the Deployment page, we will:

configure the bitbucket-pipelines.yml file.
add Stacktape API key to our pipeline

3.4 Configure bitbucket-pipelines.yml

The bitbucket-pipelines.yml file is used to configure automated continuous integration and deployment pipelines within Bitbucket's repository. It specifies a series of commands that Bitbucket executes automatically to build, test, and deploy code changes based on defined triggers.

In our case, we will be installing and executing Stacktape in the pipeline.

Stacktape offers two ways to execute the deployment from within the pipeline:

Option A - Using codebuild:deploy (recommended)
Option B - Using deploy

Option A - Using codebuild:deploy

When you use stacktape codebuild:deploy command, CLI executes the deployment remotely inside the Codebuild in your AWS account. This means that the CLI that runs in the Bitbucket pipeline container merely monitors the deployment - all the packaging, uploading of the artifacts, and other operations are executed strictly within your AWS account (in Codebuild). It also means you do not need any dependencies (such as Docker or Nodejs) installed in your pipeline container image since the CLI in the pipeline only oversees the deployment.


Copy
image: atlassian/default-image:4

pipelines:
  default:
    - step:
        name: "Deploy"
        deployment: production
        script:
          # install stacktape
          - curl -L https://installs.stacktape.com/linux.sh | sh
          - export PATH="/root/.stacktape/bin:\\$PATH"
          # run stacktape
          - stacktape codebuild:deploy --projectName my-project-1 --stage production --region eu-west-1

Example bitbucket-pipelines.yml using stacktape codebuild:deploy

Option B - Using deploy

When you use stacktape deploy command, all of the operations, such as packaging and uploading artifacts, are executed inside the pipeline container directly. When using this option, you must make sure to use a container image that already has dependencies installed. In our example, we use public.ecr.aws/codebuild/amazonlinux2-x86_64-standard:5.0 container image (which is also used in Codebuild and contains all the dependencies). However, using a custom image like this can prolong the pipeline execution time because the image must be downloaded every time the pipeline executes.


Copy
image: public.ecr.aws/codebuild/amazonlinux2-x86_64-standard:5.0

pipelines:
  default:
    - step:
        name: "Deploy"
        deployment: production
        script:
          # install stacktape
          - curl -L https://installs.stacktape.com/linux.sh | sh
          - export PATH="/root/.stacktape/bin:\\$PATH"
          # run stacktape
          - stacktape deploy --projectName my-project-1 --stage production --region eu-west-1

Example bitbucket-pipelines.yml using stacktape deploy

Creating content of bitbucket-pipelines.yml

3.5 Add Stacktape API key

Whether you use stacktape deploy or stacktape codebuild:deploy, you must set the STACKTAPE_API_KEY environment variable for your Bitbucket pipeline. Use the Stacktape API key you created in previous steps for the value.

Continue by committing the file.

3.6 Monitor deployment

After you commit the bitbucket-pipelines.yml file, the first deployment will automatically start. Click on the deployment number to navigate to the pipeline container execution overview.

Deployments page after committing `bitbucket-pipelines.yml`

In the pipeline execution overview, you can find logs from the execution, along with other details. After the execution succeeds, you can navigate to your newly deployed Stacktape project stage using the link printed at the end of the logs.